Node: added DUMP and RESTORE commands (#2126)

* Node: added DUMP and RESTORE command Signed-off-by: Yi-Pin Chen <yi-pin.chen@improving.com>
valkey-io · Aug 17, 2024 · 048812b · 048812b
1 parent 1195c82
commit 048812b
Show file tree

Hide file tree

Showing 10 changed files with 287 additions and 18 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -64,6 +64,7 @@
 * Node: Added PFMERGE command ([#2053](https://github.com/valkey-io/valkey-glide/pull/2053))
 * Node: Added WATCH and UNWATCH commands ([#2076](https://github.com/valkey-io/valkey-glide/pull/2076))
 * Node: Added WAIT command ([#2113](https://github.com/valkey-io/valkey-glide/pull/2113))
+* Node: Added DUMP and RESTORE commands ([#2126](https://github.com/valkey-io/valkey-glide/pull/2126))
 * Node: Added ZLEXCOUNT command ([#2022](https://github.com/valkey-io/valkey-glide/pull/2022))
 * Node: Added ZREMRANGEBYLEX command ([#2025](https://github.com/valkey-io/valkey-glide/pull/2025))
 * Node: Added ZRANGESTORE command ([#2068](https://github.com/valkey-io/valkey-glide/pull/2068))

diff --git a/java/client/src/main/java/glide/api/commands/GenericBaseCommands.java b/java/client/src/main/java/glide/api/commands/GenericBaseCommands.java
@@ -1153,8 +1153,8 @@ CompletableFuture<Boolean> pexpireAt(
      * user.
      *
      * @see <a href="https://valkey.io/commands/dump/">valkey.io</a> for details.
-     * @param key The key of the set.
-     * @return The serialized value of a set.<br>
+     * @param key The <code>key</code> to serialize.
+     * @return The serialized value of the data stored at <code>key</code>.<br>
      *     If <code>key</code> does not exist, <code>null</code> will be returned.
      * @example
      *     <pre>{@code
@@ -1171,10 +1171,10 @@ CompletableFuture<Boolean> pexpireAt(
      * deserializing the provided serialized <code>value</code> (obtained via {@link #dump}).
      *
      * @see <a href="https://valkey.io/commands/restore/">valkey.io</a> for details.
-     * @param key The key of the set.
+     * @param key The <code>key</code> to create.
      * @param ttl The expiry time (in milliseconds). If <code>0</code>, the <code>key</code> will
      *     persist.
-     * @param value The serialized value.
+     * @param value The serialized value to deserialize and assign to <code>key</code>.
      * @return Return <code>OK</code> if successfully create a <code>key</code> with a <code>value
      *      </code>.
      * @example
@@ -1189,11 +1189,12 @@ CompletableFuture<Boolean> pexpireAt(
      * Create a <code>key</code> associated with a <code>value</code> that is obtained by
      * deserializing the provided serialized <code>value</code> (obtained via {@link #dump}).
      *
+     * @apiNote <code>IDLETIME</code> and <code>FREQ</code> modifiers cannot be set at the same time.
      * @see <a href="https://valkey.io/commands/restore/">valkey.io</a> for details.
-     * @param key The key of the set.
+     * @param key The <code>key</code> to create.
      * @param ttl The expiry time (in milliseconds). If <code>0</code>, the <code>key</code> will
      *     persist.
-     * @param value The serialized value.
+     * @param value The serialized value to deserialize and assign to <code>key</code>.
      * @param restoreOptions The restore options. See {@link RestoreOptions}.
      * @return Return <code>OK</code> if successfully create a <code>key</code> with a <code>value
      *      </code>.

diff --git a/java/client/src/main/java/glide/api/models/BaseTransaction.java b/java/client/src/main/java/glide/api/models/BaseTransaction.java
@@ -5230,9 +5230,9 @@ public <ArgType> T copy(@NonNull ArgType source, @NonNull ArgType destination) {
      * @implNote {@link ArgType} is limited to {@link String} or {@link GlideString}, any other type
      *     will throw {@link IllegalArgumentException}.
      * @see <a href="https://valkey.io/commands/dump/">valkey.io</a> for details.
-     * @param key The key of the set.
-     * @return Command Response - The serialized value of a set. If <code>key</code> does not exist,
-     *     <code>null</code> will be returned.
+     * @param key The <code>key</code> to serialize.
+     * @return Command Response - The serialized value of the data stored at <code>key</code>.<br>
+     *     If <code>key</code> does not exist, <code>null</code> will be returned.
      */
     public <ArgType> T dump(@NonNull ArgType key) {
         checkTypeOrThrow(key);
@@ -5247,12 +5247,12 @@ public <ArgType> T dump(@NonNull ArgType key) {
      * @implNote {@link ArgType} is limited to {@link String} or {@link GlideString}, any other type
      *     will throw {@link IllegalArgumentException}.
      * @see <a href="https://valkey.io/commands/restore/">valkey.io</a> for details.
-     * @param key The key of the set.
+     * @param key The <code>key</code> to create.
      * @param ttl The expiry time (in milliseconds). If <code>0</code>, the <code>key</code> will
      *     persist.
-     * @param value The serialized value.
-     * @return Command Response - Return <code>OK</code> if successfully create a <code>key</code>
-     *     with a <code>value</code>.
+     * @param value The serialized value to deserialize and assign to <code>key</code>.
+     * @return Command Response - Return <code>OK</code> if the <code>key</code> was successfully
+     *     restored with a <code>value</code>.
      */
     public <ArgType> T restore(@NonNull ArgType key, long ttl, @NonNull byte[] value) {
         checkTypeOrThrow(key);
@@ -5267,14 +5267,15 @@ public <ArgType> T restore(@NonNull ArgType key, long ttl, @NonNull byte[] value
      *
      * @implNote {@link ArgType} is limited to {@link String} or {@link GlideString}, any other type
      *     will throw {@link IllegalArgumentException}.
+     * @apiNote <code>IDLETIME</code> and <code>FREQ</code> modifiers cannot be set at the same time.
      * @see <a href="https://valkey.io/commands/restore/">valkey.io</a> for details.
-     * @param key The key of the set.
+     * @param key The <code>key</code> to create.
      * @param ttl The expiry time (in milliseconds). If <code>0</code>, the <code>key</code> will
      *     persist.
-     * @param value The serialized value.
+     * @param value The serialized value to deserialize and assign to <code>key</code>.
      * @param restoreOptions The restore options. See {@link RestoreOptions}.
-     * @return Command Response - Return <code>OK</code> if successfully create a <code>key</code>
-     *     with a <code>value</code>.
+     * @return Command Response - Return <code>OK</code> if the <code>key</code> was successfully
+     *     restored with a <code>value</code>.
      */
     public <ArgType> T restore(
             @NonNull ArgType key,

diff --git a/java/client/src/main/java/glide/api/models/commands/RestoreOptions.java b/java/client/src/main/java/glide/api/models/commands/RestoreOptions.java
@@ -11,9 +11,10 @@
 
 /**
  * Optional arguments to {@link GenericBaseCommands#restore(GlideString, long, byte[],
- * RestoreOptions)}
+ * RestoreOptions)}.
  *
  * @see <a href="https://valkey.io/commands/restore/">valkey.io</a>
+ * @apiNote <code>IDLETIME</code> and <code>FREQ</code> modifiers cannot be set at the same time.
  */
 @Getter
 @Builder

diff --git a/node/npm/glide/index.ts b/node/npm/glide/index.ts
@@ -113,6 +113,7 @@ function initialize() {
         TimeUnit,
         RouteByAddress,
         Routes,
+        RestoreOptions,
         SingleNodeRoute,
         PeriodicChecksManualInterval,
         PeriodicChecks,
@@ -210,6 +211,7 @@ function initialize() {
         ReturnTypeXinfoStream,
         RouteByAddress,
         Routes,
+        RestoreOptions,
         SingleNodeRoute,
         PeriodicChecksManualInterval,
         PeriodicChecks,

diff --git a/node/src/BaseClient.ts b/node/src/BaseClient.ts
@@ -41,6 +41,7 @@ import {
     RangeByIndex,
     RangeByLex,
     RangeByScore,
+    RestoreOptions,
     ReturnTypeXinfoStream,
     ScoreFilter,
     SearchOrigin,
@@ -68,6 +69,7 @@ import {
     createDecr,
     createDecrBy,
     createDel,
+    createDump,
     createExists,
     createExpire,
     createExpireAt,
@@ -140,6 +142,7 @@ import {
     createRPushX,
     createRename,
     createRenameNX,
+    createRestore,
     createSAdd,
     createSCard,
     createSDiff,
@@ -1094,6 +1097,81 @@ export class BaseClient {
         return this.createWritePromise(createDel(keys));
     }
 
+    /**
+     * Serialize the value stored at `key` in a Valkey-specific format and return it to the user.
+     *
+     * @See {@link https://valkey.io/commands/dump/|valkey.io} for details.
+     *
+     * @param key - The `key` to serialize.
+     * @returns The serialized value of the data stored at `key`. If `key` does not exist, `null` will be returned.
+     *
+     * @example
+     * ```typescript
+     * let result = await client.dump("myKey");
+     * console.log(result); // Output: the serialized value of "myKey"
+     * ```
+     *
+     * @example
+     * ```typescript
+     * result = await client.dump("nonExistingKey");
+     * console.log(result); // Output: `null`
+     * ```
+     */
+    public async dump(key: GlideString): Promise<Buffer | null> {
+        return this.createWritePromise(createDump(key), {
+            decoder: Decoder.Bytes,
+        });
+    }
+
+    /**
+     * Create a `key` associated with a `value` that is obtained by deserializing the provided
+     * serialized `value` (obtained via {@link dump}).
+     *
+     * @See {@link https://valkey.io/commands/restore/|valkey.io} for details.
+     * @remarks `options.idletime` and `options.frequency` modifiers cannot be set at the same time.
+     *
+     * @param key - The `key` to create.
+     * @param ttl - The expiry time (in milliseconds). If `0`, the `key` will persist.
+     * @param value - The serialized value to deserialize and assign to `key`.
+     * @param options - (Optional) Restore options {@link RestoreOptions}.
+     * @returns Return "OK" if the `key` was successfully restored with a `value`.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.restore("myKey", 0, value);
+     * console.log(result); // Output: "OK"
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const result = await client.restore("myKey", 1000, value, {replace: true, absttl: true});
+     * console.log(result); // Output: "OK"
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const result = await client.restore("myKey", 0, value, {replace: true, idletime: 10});
+     * console.log(result); // Output: "OK"
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const result = await client.restore("myKey", 0, value, {replace: true, frequency: 10});
+     * console.log(result); // Output: "OK"
+     * ```
+     */
+    public async restore(
+        key: GlideString,
+        ttl: number,
+        value: Buffer,
+        options?: RestoreOptions,
+    ): Promise<"OK"> {
+        return this.createWritePromise(
+            createRestore(key, ttl, value, options),
+            { decoder: Decoder.String },
+        );
+    }
+
     /** Retrieve the values of multiple keys.
      *
      * @see {@link https://valkey.io/commands/mget/|valkey.io} for details.

diff --git a/node/src/Commands.ts b/node/src/Commands.ts
@@ -2815,6 +2815,77 @@ export function createMove(
     return createCommand(RequestType.Move, [key, dbIndex.toString()]);
 }
 
+/**
+ * @internal
+ */
+export function createDump(key: GlideString): command_request.Command {
+    return createCommand(RequestType.Dump, [key]);
+}
+
+/**
+ * Optional arguments for `RESTORE` command.
+ *
+ * @See {@link https://valkey.io/commands/restore/|valkey.io} for details.
+ * @remarks `IDLETIME` and `FREQ` modifiers cannot be set at the same time.
+ */
+export type RestoreOptions = {
+    /**
+     * Set to `true` to replace the key if it exists.
+     */
+    replace?: boolean;
+    /**
+     * Set to `true` to specify that `ttl` argument of {@link BaseClient.restore} represents
+     * an absolute Unix timestamp (in milliseconds).
+     */
+    absttl?: boolean;
+    /**
+     * Set the `IDLETIME` option with object idletime to the given key.
+     */
+    idletime?: number;
+    /**
+     * Set the `FREQ` option with object frequency to the given key.
+     */
+    frequency?: number;
+};
+
+/**
+ * @internal
+ */
+export function createRestore(
+    key: GlideString,
+    ttl: number,
+    value: GlideString,
+    options?: RestoreOptions,
+): command_request.Command {
+    const args: GlideString[] = [key, ttl.toString(), value];
+
+    if (options) {
+        if (options.idletime !== undefined && options.frequency !== undefined) {
+            throw new Error(
+                `syntax error: both IDLETIME and FREQ cannot be set at the same time.`,
+            );
+        }
+
+        if (options.replace) {
+            args.push("REPLACE");
+        }
+
+        if (options.absttl) {
+            args.push("ABSTTL");
+        }
+
+        if (options.idletime !== undefined) {
+            args.push("IDLETIME", options.idletime.toString());
+        }
+
+        if (options.frequency !== undefined) {
+            args.push("FREQ", options.frequency.toString());
+        }
+    }
+
+    return createCommand(RequestType.Restore, args);
+}
+
 /**
  * Optional arguments to LPOS command.
  *