@valkey/valkey-glide 2.3.1 → 2.4.0-rc2

package/build-ts/CompressionConfiguration.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompressionBackend = void 0;
+exports.validateCompressionConfiguration = validateCompressionConfiguration;
+exports.compressionConfigToProtobuf = compressionConfigToProtobuf;
+const Errors_1 = require("./Errors");
+/**
+ * Compression backend to use for automatic value compression.
+ */
+var CompressionBackend;
+(function (CompressionBackend) {
+    /** Use zstd compression backend. */
+    CompressionBackend[CompressionBackend["ZSTD"] = 0] = "ZSTD";
+    /** Use lz4 compression backend. */
+    CompressionBackend[CompressionBackend["LZ4"] = 1] = "LZ4";
+})(CompressionBackend || (exports.CompressionBackend = CompressionBackend = {}));
+/** Minimum allowed value for minCompressionSize (header size + 1). */
+const MIN_COMPRESSED_SIZE = 6;
+/** Default minimum size in bytes for values to be compressed. */
+const DEFAULT_MIN_COMPRESSION_SIZE = 64;
+/**
+ * Validates a CompressionConfiguration and throws ConfigurationError if invalid.
+ * @internal
+ */
+function validateCompressionConfiguration(config) {
+    const minSize = config.minCompressionSize ?? DEFAULT_MIN_COMPRESSION_SIZE;
+    if (minSize < MIN_COMPRESSED_SIZE) {
+        throw new Errors_1.ConfigurationError(`minCompressionSize must be at least ${MIN_COMPRESSED_SIZE} bytes`);
+    }
+    if (config.compressionLevel !== undefined &&
+        !Number.isInteger(config.compressionLevel)) {
+        throw new Errors_1.ConfigurationError("compressionLevel must be an integer");
+    }
+    if (config.maxDecompressedSize !== undefined &&
+        config.maxDecompressedSize <= 0) {
+        throw new Errors_1.ConfigurationError("maxDecompressedSize must be positive");
+    }
+}
+/**
+ * Converts a CompressionConfiguration to the protobuf format.
+ * @internal
+ */
+function compressionConfigToProtobuf(config, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+connection_request) {
+    validateCompressionConfiguration(config);
+    const proto = {
+        enabled: config.enabled,
+        backend: config.backend ?? CompressionBackend.ZSTD,
+        minCompressionSize: config.minCompressionSize ?? DEFAULT_MIN_COMPRESSION_SIZE,
+    };
+    if (config.compressionLevel !== undefined) {
+        proto.compressionLevel = config.compressionLevel;
+    }
+    // Handle maxDecompressedSize:
+    // - undefined = don't set field, let Rust use its default (512MB)
+    // - number > 0 = use that value
+    if (config.maxDecompressedSize !== undefined) {
+        proto.maxDecompressedSize = config.maxDecompressedSize;
+    }
+    return connection_request.CompressionConfig.create(proto);
+}

package/build-ts/EvictionPolicy.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+ */
+/**
+ * Enum representing cache eviction policies.
+ *
+ * Eviction policies determine which entries are removed from the cache
+ * when the cache reaches its maximum memory limit.
+ */
+export declare enum EvictionPolicy {
+    /**
+     * Least Recently Used eviction policy.
+     * Removes the entries that have been accessed least recently.
+     */
+    LRU = 0,
+    /**
+     * Least Frequently Used eviction policy.
+     * Removes the entries that have been accessed least frequently.
+     */
+    LFU = 1
+}

package/build-ts/EvictionPolicy.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvictionPolicy = void 0;
+/**
+ * Enum representing cache eviction policies.
+ *
+ * Eviction policies determine which entries are removed from the cache
+ * when the cache reaches its maximum memory limit.
+ */
+var EvictionPolicy;
+(function (EvictionPolicy) {
+    /**
+     * Least Recently Used eviction policy.
+     * Removes the entries that have been accessed least recently.
+     */
+    EvictionPolicy[EvictionPolicy["LRU"] = 0] = "LRU";
+    /**
+     * Least Frequently Used eviction policy.
+     * Removes the entries that have been accessed least frequently.
+     */
+    EvictionPolicy[EvictionPolicy["LFU"] = 1] = "LFU";
+})(EvictionPolicy || (exports.EvictionPolicy = EvictionPolicy = {}));

package/build-ts/GlideClient.d.ts

@@ -1,7 +1,7 @@
 /**
  * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
  */
-import { AdvancedBaseClientConfiguration, BaseClient, BaseClientConfiguration, DecoderOption, GlideReturnType, GlideString, PubSubMsg } from "./BaseClient";
+import { AdvancedBaseClientConfiguration, BaseClient, BaseClientConfiguration, DecoderOption, GlideReturnType, GlideString, PubSubMsg, NodeDiscoveryMode } from "./BaseClient";
 import { Batch } from "./Batch";
 import { BatchOptions, FlushMode, FunctionListOptions, FunctionListResponse, FunctionRestorePolicy, FunctionStatsFullResponse, InfoOptions, LolwutOptions, ScanOptions } from "./Commands";
 export declare namespace GlideClientConfiguration {
@@ -75,12 +75,14 @@ export interface StandalonePubSubState {
  * This configuration allows you to tailor the client's behavior when connecting to a standalone Valkey Glide server.
  *
  * - **Database Selection**: Use `databaseId` (inherited from BaseClientConfiguration) to specify which logical database to connect to.
+ * - **Client-Side Caching**: Use `clientSideCache` (inherited from BaseClientConfiguration) to enable local caching for improved performance.
  * - **Pub/Sub Subscriptions**: Predefine Pub/Sub channels and patterns to subscribe to upon connection establishment.
  *
  * @example
  * ```typescript
  * const config: GlideClientConfiguration = {
  *   databaseId: 1, // Inherited from BaseClientConfiguration
+ *   clientSideCache: ClientSideCache.create(1024, 60000), // 1MB cache, 1 min TTL
  *   pubsubSubscriptions: {
  *     channelsAndPatterns: {
  *       [GlideClientConfiguration.PubSubChannelModes.Pattern]: new Set(['news.*']),
@@ -120,6 +122,12 @@ export type GlideClientConfiguration = BaseClientConfiguration & {
      * Defaults to false.
      */
     readOnly?: boolean;
+    /**
+     * Controls how the client discovers node roles and topology in standalone mode.
+     *
+     * @see {@link NodeDiscoveryMode} for available modes.
+     */
+    nodeDiscoveryMode?: NodeDiscoveryMode;
 };
 /**
  * Represents advanced configuration settings for creating a {@link GlideClient | GlideClient} used in {@link GlideClientConfiguration | GlideClientConfiguration}.

package/build-ts/GlideClient.js

@@ -45,6 +45,10 @@ class GlideClient extends BaseClient_1.BaseClient {
         if (options.readOnly !== undefined) {
             configuration.readOnly = options.readOnly;
         }
+        if (options.nodeDiscoveryMode !== undefined) {
+            configuration.nodeDiscoveryMode =
+                options.nodeDiscoveryMode;
+        }
         return configuration;
     }
     /**

package/build-ts/GlideClusterClient.d.ts

@@ -130,6 +130,7 @@ export interface ClusterPubSubState {
  *   - `"enabledDefaultConfigs"`: Enables periodic checks with default configurations.
  *   - `"disabled"`: Disables periodic topology checks.
  *   - `{ duration_in_sec: number }`: Manually configure the interval for periodic checks.
+ * - **Client-Side Caching**: Use `clientSideCache` (inherited from BaseClientConfiguration) to enable local caching for improved performance.
  * - **Pub/Sub Subscriptions**: Predefine Pub/Sub channels and patterns to subscribe to upon connection establishment.
  *   - Supports exact channels, patterns, and sharded channels (available since Valkey version 7.0).
  *
@@ -141,6 +142,7 @@ export interface ClusterPubSubState {
  *     { host: 'cluster-node-2.example.com', port: 6379 },
  *   ],
  *   databaseId: 5, // Connect to database 5 (requires Valkey 9.0+ with multi-database cluster mode)
+ *   clientSideCache: ClientSideCache.create(2048, 0), // Enable 2MB client-side cache, no TTL
  *   periodicChecks: {
  *     duration_in_sec: 30, // Perform periodic checks every 30 seconds
  *   },

package/build-ts/ProtobufMessage.d.ts

@@ -1378,6 +1378,85 @@ export namespace command_request {
         public static getTypeUrl(typeUrlPrefix?: string): string;
     }
 
+    /** Properties of a GetCacheMetrics. */
+    interface IGetCacheMetrics {
+
+        /** GetCacheMetrics metricsTypes */
+        metricsTypes?: (command_request.CacheMetricsType|null);
+    }
+
+    /** Represents a GetCacheMetrics. */
+    class GetCacheMetrics implements IGetCacheMetrics {
+
+        /**
+         * Constructs a new GetCacheMetrics.
+         * @param [properties] Properties to set
+         */
+        constructor(properties?: command_request.IGetCacheMetrics);
+
+        /** GetCacheMetrics metricsTypes. */
+        public metricsTypes: command_request.CacheMetricsType;
+
+        /**
+         * Creates a new GetCacheMetrics instance using the specified properties.
+         * @param [properties] Properties to set
+         * @returns GetCacheMetrics instance
+         */
+        public static create(properties?: command_request.IGetCacheMetrics): command_request.GetCacheMetrics;
+
+        /**
+         * Encodes the specified GetCacheMetrics message. Does not implicitly {@link command_request.GetCacheMetrics.verify|verify} messages.
+         * @param message GetCacheMetrics message or plain object to encode
+         * @param [writer] Writer to encode to
+         * @returns Writer
+         */
+        public static encode(message: command_request.IGetCacheMetrics, writer?: $protobuf.Writer): $protobuf.Writer;
+
+        /**
+         * Encodes the specified GetCacheMetrics message, length delimited. Does not implicitly {@link command_request.GetCacheMetrics.verify|verify} messages.
+         * @param message GetCacheMetrics message or plain object to encode
+         * @param [writer] Writer to encode to
+         * @returns Writer
+         */
+        public static encodeDelimited(message: command_request.IGetCacheMetrics, writer?: $protobuf.Writer): $protobuf.Writer;
+
+        /**
+         * Decodes a GetCacheMetrics message from the specified reader or buffer.
+         * @param reader Reader or buffer to decode from
+         * @param [length] Message length if known beforehand
+         * @returns GetCacheMetrics
+         * @throws {Error} If the payload is not a reader or valid buffer
+         * @throws {$protobuf.util.ProtocolError} If required fields are missing
+         */
+        public static decode(reader: ($protobuf.Reader|Uint8Array), length?: number): command_request.GetCacheMetrics;
+
+        /**
+         * Decodes a GetCacheMetrics message from the specified reader or buffer, length delimited.
+         * @param reader Reader or buffer to decode from
+         * @returns GetCacheMetrics
+         * @throws {Error} If the payload is not a reader or valid buffer
+         * @throws {$protobuf.util.ProtocolError} If required fields are missing
+         */
+        public static decodeDelimited(reader: ($protobuf.Reader|Uint8Array)): command_request.GetCacheMetrics;
+
+        /**
+         * Gets the default type url for GetCacheMetrics
+         * @param [typeUrlPrefix] your custom typeUrlPrefix(default "type.googleapis.com")
+         * @returns The default type url
+         */
+        public static getTypeUrl(typeUrlPrefix?: string): string;
+    }
+
+    /** CacheMetricsType enum. */
+    enum CacheMetricsType {
+        HitRate = 0,
+        MissRate = 1,
+        EntryCount = 2,
+        Evictions = 3,
+        Expirations = 4,
+        TotalLookups = 5
+    }
+
     /** Properties of a CommandRequest. */
     interface ICommandRequest {
 
@@ -1405,6 +1484,9 @@ export namespace command_request {
         /** CommandRequest refreshIamToken */
         refreshIamToken?: (command_request.IRefreshIamToken|null);
 
+        /** CommandRequest getCacheMetrics */
+        getCacheMetrics?: (command_request.IGetCacheMetrics|null);
+
         /** CommandRequest route */
         route?: (command_request.IRoutes|null);
 
@@ -1445,6 +1527,9 @@ export namespace command_request {
         /** CommandRequest refreshIamToken. */
         public refreshIamToken?: (command_request.IRefreshIamToken|null);
 
+        /** CommandRequest getCacheMetrics. */
+        public getCacheMetrics?: (command_request.IGetCacheMetrics|null);
+
         /** CommandRequest route. */
         public route?: (command_request.IRoutes|null);
 
@@ -1452,7 +1537,7 @@ export namespace command_request {
         public rootSpanPtr?: (number|Long|null);
 
         /** CommandRequest command. */
-        public command?: ("singleCommand"|"batch"|"scriptInvocation"|"scriptInvocationPointers"|"clusterScan"|"updateConnectionPassword"|"refreshIamToken");
+        public command?: ("singleCommand"|"batch"|"scriptInvocation"|"scriptInvocationPointers"|"clusterScan"|"updateConnectionPassword"|"refreshIamToken"|"getCacheMetrics");
 
         /**
          * Creates a new CommandRequest instance using the specified properties.
@@ -1589,7 +1674,8 @@ export namespace connection_request {
         PreferReplica = 1,
         LowestLatency = 2,
         AZAffinity = 3,
-        AZAffinityReplicasAndPrimary = 4
+        AZAffinityReplicasAndPrimary = 4,
+        AllNodes = 5
     }
 
     /** TlsMode enum. */
@@ -1924,6 +2010,13 @@ export namespace connection_request {
         LZ4 = 1
     }
 
+    /** NodeDiscoveryMode enum. */
+    enum NodeDiscoveryMode {
+        Standard = 0,
+        Static = 1,
+        DiscoverAll = 2
+    }
+
     /** Properties of a CompressionConfig. */
     interface ICompressionConfig {
 
@@ -1938,6 +2031,9 @@ export namespace connection_request {
 
         /** CompressionConfig minCompressionSize */
         minCompressionSize?: (number|null);
+
+        /** CompressionConfig maxDecompressedSize */
+        maxDecompressedSize?: (number|Long|null);
     }
 
     /** Represents a CompressionConfig. */
@@ -1961,6 +2057,9 @@ export namespace connection_request {
         /** CompressionConfig minCompressionSize. */
         public minCompressionSize: number;
 
+        /** CompressionConfig maxDecompressedSize. */
+        public maxDecompressedSize?: (number|Long|null);
+
         /**
          * Creates a new CompressionConfig instance using the specified properties.
          * @param [properties] Properties to set
@@ -2149,6 +2248,105 @@ export namespace connection_request {
         public static getTypeUrl(typeUrlPrefix?: string): string;
     }
 
+    /** Properties of a ClientSideCache. */
+    interface IClientSideCache {
+
+        /** ClientSideCache cacheId */
+        cacheId?: (string|null);
+
+        /** ClientSideCache maxCacheKb */
+        maxCacheKb?: (number|Long|null);
+
+        /** ClientSideCache entryTtlMs */
+        entryTtlMs?: (number|Long|null);
+
+        /** ClientSideCache evictionPolicy */
+        evictionPolicy?: (connection_request.EvictionPolicy|null);
+
+        /** ClientSideCache enableMetrics */
+        enableMetrics?: (boolean|null);
+    }
+
+    /** Represents a ClientSideCache. */
+    class ClientSideCache implements IClientSideCache {
+
+        /**
+         * Constructs a new ClientSideCache.
+         * @param [properties] Properties to set
+         */
+        constructor(properties?: connection_request.IClientSideCache);
+
+        /** ClientSideCache cacheId. */
+        public cacheId: string;
+
+        /** ClientSideCache maxCacheKb. */
+        public maxCacheKb: (number|Long);
+
+        /** ClientSideCache entryTtlMs. */
+        public entryTtlMs: (number|Long);
+
+        /** ClientSideCache evictionPolicy. */
+        public evictionPolicy?: (connection_request.EvictionPolicy|null);
+
+        /** ClientSideCache enableMetrics. */
+        public enableMetrics: boolean;
+
+        /**
+         * Creates a new ClientSideCache instance using the specified properties.
+         * @param [properties] Properties to set
+         * @returns ClientSideCache instance
+         */
+        public static create(properties?: connection_request.IClientSideCache): connection_request.ClientSideCache;
+
+        /**
+         * Encodes the specified ClientSideCache message. Does not implicitly {@link connection_request.ClientSideCache.verify|verify} messages.
+         * @param message ClientSideCache message or plain object to encode
+         * @param [writer] Writer to encode to
+         * @returns Writer
+         */
+        public static encode(message: connection_request.IClientSideCache, writer?: $protobuf.Writer): $protobuf.Writer;
+
+        /**
+         * Encodes the specified ClientSideCache message, length delimited. Does not implicitly {@link connection_request.ClientSideCache.verify|verify} messages.
+         * @param message ClientSideCache message or plain object to encode
+         * @param [writer] Writer to encode to
+         * @returns Writer
+         */
+        public static encodeDelimited(message: connection_request.IClientSideCache, writer?: $protobuf.Writer): $protobuf.Writer;
+
+        /**
+         * Decodes a ClientSideCache message from the specified reader or buffer.
+         * @param reader Reader or buffer to decode from
+         * @param [length] Message length if known beforehand
+         * @returns ClientSideCache
+         * @throws {Error} If the payload is not a reader or valid buffer
+         * @throws {$protobuf.util.ProtocolError} If required fields are missing
+         */
+        public static decode(reader: ($protobuf.Reader|Uint8Array), length?: number): connection_request.ClientSideCache;
+
+        /**
+         * Decodes a ClientSideCache message from the specified reader or buffer, length delimited.
+         * @param reader Reader or buffer to decode from
+         * @returns ClientSideCache
+         * @throws {Error} If the payload is not a reader or valid buffer
+         * @throws {$protobuf.util.ProtocolError} If required fields are missing
+         */
+        public static decodeDelimited(reader: ($protobuf.Reader|Uint8Array)): connection_request.ClientSideCache;
+
+        /**
+         * Gets the default type url for ClientSideCache
+         * @param [typeUrlPrefix] your custom typeUrlPrefix(default "type.googleapis.com")
+         * @returns The default type url
+         */
+        public static getTypeUrl(typeUrlPrefix?: string): string;
+    }
+
+    /** EvictionPolicy enum. */
+    enum EvictionPolicy {
+        LRU = 0,
+        LFU = 1
+    }
+
     /** Properties of a ConnectionRequest. */
     interface IConnectionRequest {
 
@@ -2229,6 +2427,12 @@ export namespace connection_request {
 
         /** ConnectionRequest readOnly */
         readOnly?: (boolean|null);
+
+        /** ConnectionRequest clientSideCache */
+        clientSideCache?: (connection_request.IClientSideCache|null);
+
+        /** ConnectionRequest nodeDiscoveryMode */
+        nodeDiscoveryMode?: (connection_request.NodeDiscoveryMode|null);
     }
 
     /** Represents a ConnectionRequest. */
@@ -2318,6 +2522,12 @@ export namespace connection_request {
         /** ConnectionRequest readOnly. */
         public readOnly?: (boolean|null);
 
+        /** ConnectionRequest clientSideCache. */
+        public clientSideCache?: (connection_request.IClientSideCache|null);
+
+        /** ConnectionRequest nodeDiscoveryMode. */
+        public nodeDiscoveryMode: connection_request.NodeDiscoveryMode;
+
         /** ConnectionRequest periodicChecks. */
         public periodicChecks?: ("periodicChecksManualInterval"|"periodicChecksDisabled");