@valkey/valkey-glide 2.4.2-rc2 → 2.5.0-rc2

package/build-ts/BaseClient.d.ts

@@ -6,7 +6,8 @@ import { Buffer, Writer } from "protobufjs/minimal";
 import { AggregationType, BaseScanOptions, BitFieldGet, // eslint-disable-line @typescript-eslint/no-unused-vars
 BitFieldSubCommands, // eslint-disable-line @typescript-eslint/no-unused-vars
 BitOffsetOptions, BitwiseOperation, Boundary, ClientSideCache, CompressionConfiguration, ConnectionError, ExpireOptions, GeoAddOptions, // eslint-disable-line @typescript-eslint/no-unused-vars
-GeoSearchResultOptions, GeoSearchShape, GeoSearchStoreResultOptions, GeoUnit, GeospatialData, GlideClientConfiguration, GlideClusterClientConfiguration, HExpireOptions, HGetExOptions, HScanOptions, HSetExOptions, InsertPosition, KeyWeight, LPosOptions, ListDirection, RangeByIndex, RangeByLex, RangeByScore, RequestError, RestoreOptions, Routes, ScoreFilter, Script, SearchOrigin, SetOptions, SortOptions, StreamAddOptions, StreamClaimOptions, StreamGroupOptions, StreamPendingOptions, StreamReadGroupOptions, StreamReadOptions, StreamTrimOptions, TimeUnit, ValkeyError, ZAddOptions, ZScanOptions } from ".";
+GeoSearchResultOptions, GeoSearchShape, GeoSearchStoreResultOptions, GeoUnit, GeospatialData, GlideClientConfiguration, GlideClusterClientConfiguration, HExpireOptions, HGetExOptions, HScanOptions, HSetExOptions, InsertPosition, KeyWeight, LPosOptions, ListDirection, // eslint-disable-line @typescript-eslint/no-unused-vars
+MigrateOptions, RangeByIndex, RangeByLex, RangeByScore, RequestError, RestoreOptions, Routes, ScoreFilter, Script, SearchOrigin, SetOptions, SortOptions, StreamAddOptions, StreamClaimOptions, StreamGroupOptions, StreamPendingOptions, StreamReadGroupOptions, StreamReadOptions, StreamTrimOptions, TimeUnit, ValkeyError, ZAddOptions, ZScanOptions } from ".";
 import { command_request, connection_request, response } from "../build-ts/ProtobufMessage";
 type PromiseFunction = (value?: any) => void;
 type ErrorFunction = (error: ValkeyError) => void;
@@ -514,6 +515,60 @@ export interface BaseClientConfiguration {
      * ```
      */
     clientSideCache?: ClientSideCache;
+    /**
+     * Optional callback for resolving server addresses before connection.
+     *
+     * When provided, this callback will be invoked for each configured address during connection
+     * establishment and during cluster topology refreshes. The callback receives the configured
+     * host and port, and should return a tuple `[resolvedHost, resolvedPort]` with the actual
+     * address to use for the connection.
+     *
+     * Use cases:
+     * - Custom DNS resolution for service discovery
+     * - Address translation for proxy setups
+     * - Dynamic endpoint resolution for cloud environments
+     *
+     * If the resolver throws an exception or returns an invalid value, the original address
+     * is used as a fallback.
+     *
+     * @example
+     * ```typescript
+     * const config: BaseClientConfiguration = {
+     *   addresses: [{ host: "internal-service", port: 9999 }],
+     *   addressResolver: (host, port) => {
+     *     if (host === "internal-service") {
+     *       return ["10.0.0.5", 6379];
+     *     }
+     *     return [host, port];
+     *   },
+     * };
+     * ```
+     */
+    addressResolver?: (host: string, port: number) => [string, number];
+    /**
+     * Configuration for the client-wide circuit breaker.
+     * When set, enables the circuit breaker which detects sustained error rates
+     * and rejects requests before they enter the core.
+     * If not set (undefined), the circuit breaker is disabled.
+     */
+    clientCircuitBreaker?: ClientCircuitBreakerConfiguration;
+}
+/**
+ * Configuration for the client-wide circuit breaker.
+ */
+export interface ClientCircuitBreakerConfiguration {
+    /** Sliding window duration in milliseconds for error rate calculation. Default: 10000. */
+    windowSizeMs?: number;
+    /** Error rate (0.0-1.0) within the window to trip the breaker. Default: 0.5. */
+    failureRateThreshold?: number;
+    /** Minimum errors within window before rate is evaluated. Default: 50. */
+    minErrors?: number;
+    /** Time in milliseconds in Open state before allowing a probe. Default: 5000. */
+    openTimeoutMs?: number;
+    /** Whether timeouts count toward tripping. Default: false. */
+    countTimeouts?: boolean;
+    /** Consecutive successful probes needed before closing. Default: 3. */
+    consecutiveSuccesses?: number;
 }
 /**
  * Represents advanced configuration settings for a client, including connection-related options.
@@ -655,6 +710,7 @@ export declare class BaseClient {
     private pendingPushNotification;
     private readonly inflightRequestsLimit;
     private config;
+    private addressResolverKey;
     protected configurePubsub(options: GlideClusterClientConfiguration | GlideClientConfiguration, configuration: connection_request.IConnectionRequest): void;
     private handleReadData;
     protected toProtobufRoute(route: Routes | undefined): command_request.Routes | undefined;
@@ -1114,6 +1170,34 @@ export declare class BaseClient {
         destinationDB?: number;
         replace?: boolean;
     }): Promise<boolean>;
+    /**
+     * Atomically transfers a key from a source Valkey instance to a destination Valkey instance.
+     * Once the key is successfully transferred, it is deleted from the source instance
+     * unless `copy` is set to `true` in options.
+     *
+     * @see {@link https://valkey.io/commands/migrate/|valkey.io} for details.
+     *
+     * @param host - The host of the destination Valkey instance.
+     * @param port - The port of the destination Valkey instance.
+     * @param key - The key to migrate.
+     * @param destinationDB - The database index on the destination instance.
+     * @param timeout - The maximum idle time in milliseconds for the bulk-transfer.
+     * @param options - Optional migration options.
+     * @returns `"OK"` on success, or `"NOKEY"` if the key does not exist.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.migrate("127.0.0.1", 6379, "mykey", 0, 5000);
+     * console.log(result); // Output: "OK" - "mykey" was migrated to the destination instance.
+     * ```
+     * @example
+     * ```typescript
+     * // Migrate with copy (keep source key) and replace (overwrite destination)
+     * const result = await client.migrate("127.0.0.1", 6379, "mykey", 0, 5000, { copy: true, replace: true });
+     * console.log(result); // Output: "OK" - "mykey" was copied to the destination instance.
+     * ```
+     */
+    migrate(host: string, port: number, key: GlideString, destinationDB: number, timeout: number, options?: MigrateOptions): Promise<string>;
     /** Decrements the number stored at `key` by one. If `key` does not exist, it is set to 0 before performing the operation.
      *
      * @see {@link https://valkey.io/commands/decr/|valkey.io} for details.
@@ -6238,6 +6322,22 @@ export declare class BaseClient {
      * ```
      */
     wait(numreplicas: number, timeout: number): Promise<number>;
+    /**
+     * Resets the connection state.
+     *
+     * @see {@link https://valkey.io/commands/reset/|valkey.io} for more details.
+     *
+     * @remarks Resets the database index, client name, protocol, and pubsub subscriptions.
+     *
+     * @returns "RESET" when the connection state is successfully reset.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.reset();
+     * console.log(result); // Output: "RESET"
+     * ```
+     */
+    reset(): Promise<"RESET">;
     /**
      * Overwrites part of the string stored at `key`, starting at the specified byte `offset`,
      * for the entire length of `value`. If the `offset` is larger than the current length of the string at `key`,

package/build-ts/BaseClient.js

@@ -212,6 +212,9 @@ function getRequestErrorClass(type) {
     if (type === ProtobufMessage_1.response.RequestErrorType.Timeout) {
         return _1.TimeoutError;
     }
+    if (type === ProtobufMessage_1.response.RequestErrorType.CircuitBreakerOpen) {
+        return _1.CircuitBreakerError;
+    }
     if (type === ProtobufMessage_1.response.RequestErrorType.Unspecified) {
         return _1.RequestError;
     }
@@ -234,6 +237,7 @@ class BaseClient {
     pendingPushNotification = [];
     inflightRequestsLimit;
     config;
+    addressResolverKey;
     configurePubsub(options, configuration) {
         if (options.pubsubSubscriptions) {
             if (options.protocol == ProtocolVersion.RESP2) {
@@ -1228,6 +1232,36 @@ class BaseClient {
     async copy(source, destination, options) {
         return this.createWritePromise((0, _1.createCopy)(source, destination, options));
     }
+    /**
+     * Atomically transfers a key from a source Valkey instance to a destination Valkey instance.
+     * Once the key is successfully transferred, it is deleted from the source instance
+     * unless `copy` is set to `true` in options.
+     *
+     * @see {@link https://valkey.io/commands/migrate/|valkey.io} for details.
+     *
+     * @param host - The host of the destination Valkey instance.
+     * @param port - The port of the destination Valkey instance.
+     * @param key - The key to migrate.
+     * @param destinationDB - The database index on the destination instance.
+     * @param timeout - The maximum idle time in milliseconds for the bulk-transfer.
+     * @param options - Optional migration options.
+     * @returns `"OK"` on success, or `"NOKEY"` if the key does not exist.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.migrate("127.0.0.1", 6379, "mykey", 0, 5000);
+     * console.log(result); // Output: "OK" - "mykey" was migrated to the destination instance.
+     * ```
+     * @example
+     * ```typescript
+     * // Migrate with copy (keep source key) and replace (overwrite destination)
+     * const result = await client.migrate("127.0.0.1", 6379, "mykey", 0, 5000, { copy: true, replace: true });
+     * console.log(result); // Output: "OK" - "mykey" was copied to the destination instance.
+     * ```
+     */
+    async migrate(host, port, key, destinationDB, timeout, options) {
+        return this.createWritePromise((0, _1.createMigrate)(host, port, key, destinationDB, timeout, options));
+    }
     /** Decrements the number stored at `key` by one. If `key` does not exist, it is set to 0 before performing the operation.
      *
      * @see {@link https://valkey.io/commands/decr/|valkey.io} for details.
@@ -6701,6 +6735,26 @@ class BaseClient {
     async wait(numreplicas, timeout) {
         return this.createWritePromise((0, _1.createWait)(numreplicas, timeout));
     }
+    /**
+     * Resets the connection state.
+     *
+     * @see {@link https://valkey.io/commands/reset/|valkey.io} for more details.
+     *
+     * @remarks Resets the database index, client name, protocol, and pubsub subscriptions.
+     *
+     * @returns "RESET" when the connection state is successfully reset.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.reset();
+     * console.log(result); // Output: "RESET"
+     * ```
+     */
+    async reset() {
+        return this.createWritePromise((0, _1.createReset)(), {
+            decoder: Decoder.String,
+        });
+    }
     /**
      * Overwrites part of the string stored at `key`, starting at the specified byte `offset`,
      * for the entire length of `value`. If the `offset` is larger than the current length of the string at `key`,
@@ -7054,6 +7108,7 @@ class BaseClient {
                 entryTtlMs: cache.entryTtlMs,
                 evictionPolicy: cache.evictionPolicy,
                 enableMetrics: cache.enableMetrics,
+                serverAssisted: cache.serverAssisted,
             });
         }
         const request = {
@@ -7078,6 +7133,35 @@ class BaseClient {
             (0, _1.validateCompressionConfiguration)(options.compression);
             request.compressionConfig = (0, _1.compressionConfigToProtobuf)(options.compression, ProtobufMessage_1.connection_request);
         }
+        if (options.clientCircuitBreaker) {
+            const cb = options.clientCircuitBreaker;
+            if (cb.windowSizeMs !== undefined && cb.windowSizeMs <= 0) {
+                throw new _1.ConfigurationError("windowSizeMs must be positive");
+            }
+            if (cb.failureRateThreshold !== undefined &&
+                (cb.failureRateThreshold <= 0.0 ||
+                    cb.failureRateThreshold > 1.0)) {
+                throw new _1.ConfigurationError("failureRateThreshold must be between 0.0 (exclusive) and 1.0 (inclusive)");
+            }
+            if (cb.minErrors !== undefined && cb.minErrors <= 0) {
+                throw new _1.ConfigurationError("minErrors must be positive");
+            }
+            if (cb.openTimeoutMs !== undefined && cb.openTimeoutMs <= 0) {
+                throw new _1.ConfigurationError("openTimeoutMs must be positive");
+            }
+            if (cb.consecutiveSuccesses !== undefined &&
+                cb.consecutiveSuccesses <= 0) {
+                throw new _1.ConfigurationError("consecutiveSuccesses must be positive");
+            }
+            request.clientCircuitBreaker = {
+                windowSizeMs: cb.windowSizeMs,
+                failureRateThreshold: cb.failureRateThreshold,
+                minErrors: cb.minErrors,
+                openTimeoutMs: cb.openTimeoutMs,
+                countTimeouts: cb.countTimeouts,
+                consecutiveSuccesses: cb.consecutiveSuccesses,
+            };
+        }
         return request;
     }
     /**
@@ -7120,12 +7204,29 @@ class BaseClient {
      */
     connectToServer(options) {
         return new Promise((resolve, reject) => {
+            // Register address resolver in the global registry before sending
+            // the connection request, so the socket listener can pick it up.
+            if (options.addressResolver) {
+                this.addressResolverKey = (0, _1.registerAddressResolver)(options.addressResolver);
+            }
             this.promiseCallbackFunctions[0] = [
                 resolve,
-                reject,
+                (err) => {
+                    // Clean up the resolver from the registry if connection fails
+                    if (this.addressResolverKey) {
+                        (0, _1.removeAddressResolver)(this.addressResolverKey);
+                        this.addressResolverKey = undefined;
+                    }
+                    reject(err);
+                },
                 options?.defaultDecoder,
             ];
-            const message = ProtobufMessage_1.connection_request.ConnectionRequest.create(this.createClientRequest(options));
+            const request = this.createClientRequest(options);
+            // Set the address resolver key in the protobuf request
+            if (this.addressResolverKey) {
+                request.addressResolverKey = this.addressResolverKey;
+            }
+            const message = ProtobufMessage_1.connection_request.ConnectionRequest.create(request);
             this.writeOrBufferRequest(message, (message, writer) => {
                 ProtobufMessage_1.connection_request.ConnectionRequest.encodeDelimited(message, writer);
             });
@@ -7145,6 +7246,11 @@ class BaseClient {
         this.pubsubFutures.forEach(([, reject]) => {
             reject(new _1.ClosingError(errorMessage || ""));
         });
+        // Clean up address resolver from the global registry
+        if (this.addressResolverKey) {
+            (0, _1.removeAddressResolver)(this.addressResolverKey);
+            this.addressResolverKey = undefined;
+        }
         _1.Logger.log("info", "Client lifetime", "disposing of client");
         this.socket.end();
     }

package/build-ts/Batch.d.ts

@@ -13,7 +13,7 @@ FunctionRestorePolicy, // eslint-disable-line @typescript-eslint/no-unused-vars
 GeoAddOptions, // eslint-disable-line @typescript-eslint/no-unused-vars
 GeoSearchResultOptions, GeoSearchShape, GeoSearchStoreResultOptions, GeoUnit, GeospatialData, // eslint-disable-line @typescript-eslint/no-unused-vars
 GlideRecord, GlideString, HExpireOptions, HGetExOptions, HScanOptions, HSetExOptions, HashDataType, InfoOptions, InsertPosition, KeyWeight, LPosOptions, ListDirection, LolwutOptions, // eslint-disable-line @typescript-eslint/no-unused-vars
-RangeByIndex, RangeByLex, RangeByScore, // eslint-disable-line @typescript-eslint/no-unused-vars
+MigrateOptions, RangeByIndex, RangeByLex, RangeByScore, // eslint-disable-line @typescript-eslint/no-unused-vars
 RestoreOptions, Score, ScoreFilter, SearchOrigin, SetOptions, SortOptions, StreamAddOptions, StreamClaimOptions, StreamGroupOptions, StreamPendingOptions, StreamReadGroupOptions, StreamReadOptions, StreamTrimOptions, TimeUnit, ZAddOptions, ZScanOptions } from ".";
 import { command_request } from "../build-ts/ProtobufMessage";
 /**
@@ -141,6 +141,21 @@ export declare class BaseBatch<T extends BaseBatch<T>> {
         destinationDB?: number;
         replace?: boolean;
     }): T;
+    /**
+     * Atomically transfers a key from a source Valkey instance to a destination Valkey instance.
+     *
+     * @see {@link https://valkey.io/commands/migrate/|valkey.io} for details.
+     *
+     * @param host - The host of the destination Valkey instance.
+     * @param port - The port of the destination Valkey instance.
+     * @param key - The key to migrate.
+     * @param destinationDB - The database index on the destination instance.
+     * @param timeout - The maximum idle time in milliseconds for the bulk-transfer.
+     * @param options - Optional migration options.
+     *
+     * Command Response - "OK" on success, or "NOKEY" if the key was not found.
+     */
+    migrate(host: string, port: number, key: GlideString, destinationDB: number, timeout: number, options?: MigrateOptions): T;
     /**
      * Gets information and statistics about the server.
      *
@@ -2486,6 +2501,17 @@ export declare class BaseBatch<T extends BaseBatch<T>> {
      *     current connection.
      */
     wait(numreplicas: number, timeout: number): T;
+    /**
+     * Resets the connection state.
+     *
+     * @see {@link https://valkey.io/commands/reset/|valkey.io} for more details.
+     *
+     * @remarks RESET cannot be used inside an atomic batch (MULTI/EXEC transaction).
+     *     Use a non-atomic batch (`new Batch(false)`) instead.
+     *
+     * Command Response - "RESET" when the connection state is successfully reset.
+     */
+    reset(): T;
     /**
      * Invokes a previously loaded function.
      *
@@ -3128,6 +3154,22 @@ export declare class Batch extends BaseBatch<Batch> {
      * Command Response - A simple `"OK"` response.
      */
     select(index: number): Batch;
+    /**
+     * Atomically transfers one or more keys from a source Valkey instance to a destination Valkey instance.
+     * Extends {@link BaseBatch.migrate} with multi-key support using the KEYS subcommand.
+     *
+     * @see {@link https://valkey.io/commands/migrate/|valkey.io} for details.
+     *
+     * @param host - The host of the destination Valkey instance.
+     * @param port - The port of the destination Valkey instance.
+     * @param key - The key to migrate, or an array of keys to migrate.
+     * @param destinationDB - The database index on the destination instance.
+     * @param timeout - The maximum idle time in milliseconds for the bulk-transfer.
+     * @param options - Optional migration options.
+     *
+     * Command Response - "OK" on success, or "NOKEY" if no keys were found.
+     */
+    migrate(host: string, port: number, key: GlideString | GlideString[], destinationDB: number, timeout: number, options?: MigrateOptions): Batch;
     /** Publish a message on pubsub channel.
      *
      * @see {@link https://valkey.io/commands/publish/|valkey.io} for more details.

package/build-ts/Batch.js

@@ -160,6 +160,23 @@ class BaseBatch {
     copy(source, destination, options) {
         return this.addAndReturn((0, _1.createCopy)(source, destination, options));
     }
+    /**
+     * Atomically transfers a key from a source Valkey instance to a destination Valkey instance.
+     *
+     * @see {@link https://valkey.io/commands/migrate/|valkey.io} for details.
+     *
+     * @param host - The host of the destination Valkey instance.
+     * @param port - The port of the destination Valkey instance.
+     * @param key - The key to migrate.
+     * @param destinationDB - The database index on the destination instance.
+     * @param timeout - The maximum idle time in milliseconds for the bulk-transfer.
+     * @param options - Optional migration options.
+     *
+     * Command Response - "OK" on success, or "NOKEY" if the key was not found.
+     */
+    migrate(host, port, key, destinationDB, timeout, options) {
+        return this.addAndReturn((0, _1.createMigrate)(host, port, key, destinationDB, timeout, options));
+    }
     /**
      * Gets information and statistics about the server.
      *
@@ -2841,6 +2858,19 @@ class BaseBatch {
     wait(numreplicas, timeout) {
         return this.addAndReturn((0, _1.createWait)(numreplicas, timeout));
     }
+    /**
+     * Resets the connection state.
+     *
+     * @see {@link https://valkey.io/commands/reset/|valkey.io} for more details.
+     *
+     * @remarks RESET cannot be used inside an atomic batch (MULTI/EXEC transaction).
+     *     Use a non-atomic batch (`new Batch(false)`) instead.
+     *
+     * Command Response - "RESET" when the connection state is successfully reset.
+     */
+    reset() {
+        return this.addAndReturn((0, _1.createReset)());
+    }
     /**
      * Invokes a previously loaded function.
      *
@@ -3561,6 +3591,24 @@ class Batch extends BaseBatch {
     select(index) {
         return this.addAndReturn((0, _1.createSelect)(index));
     }
+    /**
+     * Atomically transfers one or more keys from a source Valkey instance to a destination Valkey instance.
+     * Extends {@link BaseBatch.migrate} with multi-key support using the KEYS subcommand.
+     *
+     * @see {@link https://valkey.io/commands/migrate/|valkey.io} for details.
+     *
+     * @param host - The host of the destination Valkey instance.
+     * @param port - The port of the destination Valkey instance.
+     * @param key - The key to migrate, or an array of keys to migrate.
+     * @param destinationDB - The database index on the destination instance.
+     * @param timeout - The maximum idle time in milliseconds for the bulk-transfer.
+     * @param options - Optional migration options.
+     *
+     * Command Response - "OK" on success, or "NOKEY" if no keys were found.
+     */
+    migrate(host, port, key, destinationDB, timeout, options) {
+        return this.addAndReturn((0, _1.createMigrate)(host, port, key, destinationDB, timeout, options));
+    }
     /** Publish a message on pubsub channel.
      *
      * @see {@link https://valkey.io/commands/publish/|valkey.io} for more details.

package/build-ts/ClientSideCache.d.ts

@@ -26,6 +26,14 @@ export interface ClientSideCacheConfig {
      * Defaults to false if not specified.
      */
     enableMetrics?: boolean;
+    /**
+     * Whether to enable server-assisted client-side caching.
+     *
+     * When enabled, GLIDE sends CLIENT TRACKING ON BCAST during connection setup
+     * and the server sends invalidation messages when tracked keys are modified.
+     * Requires RESP3 protocol. Defaults to false if not specified.
+     */
+    serverAssisted?: boolean;
 }
 /**
  * Optional configuration options for the static create method.
@@ -39,6 +47,10 @@ export interface ClientSideCacheOptions {
      * Whether to enable metrics collection for this cache.
      */
     enableMetrics?: boolean;
+    /**
+     * Whether to enable server-assisted client-side caching.
+     */
+    serverAssisted?: boolean;
 }
 /**
  * Configuration class for client-side caching.
@@ -79,6 +91,10 @@ export declare class ClientSideCache {
      * Whether metrics collection is enabled for this cache.
      */
     readonly enableMetrics: boolean;
+    /**
+     * Whether server-assisted client-side caching is enabled.
+     */
+    readonly serverAssisted: boolean;
     /**
      * Creates a new ClientSideCache instance.
      *

package/build-ts/ClientSideCache.js

@@ -49,6 +49,10 @@ class ClientSideCache {
      * Whether metrics collection is enabled for this cache.
      */
     enableMetrics;
+    /**
+     * Whether server-assisted client-side caching is enabled.
+     */
+    serverAssisted;
     /**
      * Creates a new ClientSideCache instance.
      *
@@ -68,6 +72,7 @@ class ClientSideCache {
         this.entryTtlMs = config.entryTtlMs;
         this.evictionPolicy = config.evictionPolicy;
         this.enableMetrics = config.enableMetrics ?? false;
+        this.serverAssisted = config.serverAssisted ?? false;
     }
     /**
      * Factory method to create a ClientSideCache with auto-generated cache ID.
@@ -97,6 +102,7 @@ class ClientSideCache {
             entryTtlMs,
             evictionPolicy: options?.evictionPolicy,
             enableMetrics: options?.enableMetrics,
+            serverAssisted: options?.serverAssisted,
         });
     }
 }