@valkey/valkey-glide 2.3.1 → 2.4.0-rc1

package/build-ts/BaseClient.d.ts

@@ -5,7 +5,7 @@ import * as net from "net";
 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, ConnectionError, ExpireOptions, GeoAddOptions, // 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 ".";
 import { command_request, connection_request, response } from "../build-ts/ProtobufMessage";
 type PromiseFunction = (value?: any) => void;
@@ -184,7 +184,23 @@ export type ReadFrom =
  | "AZAffinity"
 /** Spread the read requests among all nodes within the client's Availability Zone (AZ) in a round robin manner,
      prioritizing local replicas, then the local primary, and falling back to any replica or the primary if needed.*/
- | "AZAffinityReplicasAndPrimary";
+ | "AZAffinityReplicasAndPrimary"
+/** Spread the read requests between all nodes (primary and replicas) in a round robin manner.*/
+ | "allNodes";
+/**
+ * Controls how the client discovers node roles and topology in standalone mode.
+ */
+export declare enum NodeDiscoveryMode {
+    /** Default: verify node roles via INFO REPLICATION, use only provided addresses. */
+    Standard = 0,
+    /** Skip role detection entirely. Trust provided addresses as-is; first address is primary.
+     *  Use when connecting through a proxy (e.g., Envoy) or when the topology is known and static.
+     *  Note: Do not set `clientName` when using this mode with a proxy. */
+    Static = 1,
+    /** Discover full topology (primary + all replicas) from any starting node.
+     *  Provide any single node address and the client will find and connect to all other nodes. */
+    DiscoverAll = 2
+}
 /**
  * Configuration settings for creating a client. Shared settings for standalone and cluster clients.
  *
@@ -450,6 +466,54 @@ export interface BaseClientConfiguration {
      * ```
      */
     lazyConnect?: boolean;
+    /**
+     * Configuration for automatic compression of values.
+     * When enabled, values that meet the minimum size threshold will be
+     * automatically compressed before being sent to the server and
+     * decompressed when retrieved.
+     *
+     * @example
+     * ```typescript
+     * const client = await GlideClient.createClient({
+     *   addresses: [{ host: "localhost", port: 6379 }],
+     *   compression: { enabled: true },
+     * });
+     * ```
+     */
+    compression?: CompressionConfiguration;
+    /**
+     * Client-side cache configuration.
+     *
+     * @remarks
+     * When provided, enables client-side caching for cacheable commands (GET, HGETALL, SMEMBERS).
+     * The cache reduces network round-trips and server load by storing frequently accessed data locally.
+     *
+     * - **Memory Management**: The cache respects the configured memory limit and evicts entries based on the specified policy.
+     * - **TTL Support**: Entries can have optional time-to-live values for automatic expiration.
+     * - **Shared Caches**: Multiple clients can share the same cache instance using the same cache ID.
+     * - **Metrics**: Optional metrics collection provides insights into cache performance.
+     *
+     * @example
+     * ```typescript
+     * // Simple cache configuration
+     * const config: BaseClientConfiguration = {
+     *   addresses: [{ host: 'localhost', port: 6379 }],
+     *   clientSideCache: ClientSideCache.create(1024, 0), // 1MB cache, no TTL
+     * };
+     *
+     * // Advanced cache configuration
+     * const advancedConfig: BaseClientConfiguration = {
+     *   addresses: [{ host: 'localhost', port: 6379 }],
+     *   clientSideCache: new ClientSideCache({
+     *     maxCacheKb: 2048,
+     *     entryTtlMs: 300000,
+     *     evictionPolicy: EvictionPolicy.LFU,
+     *     enableMetrics: true,
+     *   }),
+     * };
+     * ```
+     */
+    clientSideCache?: ClientSideCache;
 }
 /**
  * Represents advanced configuration settings for a client, including connection-related options.
@@ -603,6 +667,7 @@ export declare class BaseClient {
     protected ensureClientIsOpen(): void;
     protected createUpdateConnectionPasswordPromise(command: command_request.UpdateConnectionPassword): Promise<GlideString>;
     protected createRefreshIamTokenPromise(command: command_request.RefreshIamToken): Promise<GlideString>;
+    protected createGetCacheMetricsPromise(command: command_request.GetCacheMetrics): Promise<number>;
     protected createScriptInvocationPromise<T = GlideString>(command: command_request.ScriptInvocation, options?: {
         keys?: GlideString[];
         args?: GlideString[];
@@ -2664,7 +2729,7 @@ export declare class BaseClient {
     scard(key: GlideString): Promise<number>;
     /** Gets the intersection of all the given sets.
      *
-     * @see {@link https://valkey.io/docs/latest/commands/sinter/|valkey.io} for more details.
+     * @see {@link https://valkey.io/commands/sinter/|valkey.io} for more details.
      * @remarks When in cluster mode, all `keys` must map to the same hash slot.
      *
      * @param keys - The `keys` of the sets to get the intersection.
@@ -6491,6 +6556,84 @@ export declare class BaseClient {
      * ```
      */
     refreshIamToken(): Promise<GlideString>;
+    /**
+     * Get the cache hit rate (hits / total requests).
+     *
+     * @returns The cache hit rate as a number between 0.0 and 1.0.
+     * @throws RequestError if client-side caching is not enabled or metrics tracking is disabled.
+     * @example
+     * ```typescript
+     * const hitRate = await client.getCacheHitRate();
+     * console.log(`Cache hit rate: ${(hitRate * 100).toFixed(2)}%`);
+     * // Output: Cache hit rate: 85.50%
+     * ```
+     */
+    getCacheHitRate(): Promise<number>;
+    /**
+     * Get the cache miss rate (misses / total requests).
+     *
+     * @returns The cache miss rate as a number between 0.0 and 1.0.
+     * @throws RequestError if client-side caching is not enabled or metrics tracking is disabled.
+     * @example
+     * ```typescript
+     * const missRate = await client.getCacheMissRate();
+     * console.log(`Cache miss rate: ${(missRate * 100).toFixed(2)}%`);
+     * // Output: Cache miss rate: 14.50%
+     * ```
+     */
+    getCacheMissRate(): Promise<number>;
+    /**
+     * Get the current number of entries in the client-side cache.
+     *
+     * @returns The number of entries in the cache.
+     * @throws RequestError if client-side caching is not enabled.
+     * @example
+     * ```typescript
+     * const entryCount = await client.getCacheEntryCount();
+     * console.log(`Cache entry count: ${entryCount}`);
+     * // Output: Cache entry count: 1500
+     * ```
+     */
+    getCacheEntryCount(): Promise<number>;
+    /**
+     * Get the total number of entries evicted from the client-side cache due to memory constraints.
+     *
+     * @returns The number of evictions.
+     * @throws RequestError if client-side caching is not enabled or metrics tracking is disabled.
+     * @example
+     * ```typescript
+     * const evictions = await client.getCacheEvictions();
+     * console.log(`Cache evictions: ${evictions}`);
+     * // Output: Cache evictions: 100
+     * ```
+     */
+    getCacheEvictions(): Promise<number>;
+    /**
+     * Get the total number of entries expired from the client-side cache.
+     *
+     * @returns The number of expirations.
+     * @throws RequestError if client-side caching is not enabled or metrics tracking is disabled.
+     * @example
+     * ```typescript
+     * const expirations = await client.getCacheExpirations();
+     * console.log(`Cache expirations: ${expirations}`);
+     * // Output: Cache expirations: 250
+     * ```
+     */
+    getCacheExpirations(): Promise<number>;
+    /**
+     * Get the total number of cache lookups (hits + misses).
+     *
+     * @returns The total number of cache lookups.
+     * @throws RequestError if client-side caching is not enabled or metrics tracking is disabled.
+     * @example
+     * ```typescript
+     * const totalLookups = await client.getCacheTotalLookups();
+     * console.log(`Total cache lookups: ${totalLookups}`);
+     * // Output: Total cache lookups: 5000
+     * ```
+     */
+    getCacheTotalLookups(): Promise<number>;
     /**
      * Subscribes the client to the specified channels (non-blocking).
      * Returns immediately without waiting for subscription confirmation.

package/build-ts/BaseClient.js

@@ -39,7 +39,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BaseClient = exports.ObjectType = exports.ServiceType = exports.ALL_PATTERNS = exports.ALL_CHANNELS = exports.Decoder = exports.ProtocolVersion = void 0;
+exports.BaseClient = exports.ObjectType = exports.NodeDiscoveryMode = exports.ServiceType = exports.ALL_PATTERNS = exports.ALL_CHANNELS = exports.Decoder = exports.ProtocolVersion = void 0;
 exports.convertGlideRecord = convertGlideRecord;
 exports.convertGlideRecordToRecord = convertGlideRecordToRecord;
 exports.isGlideRecord = isGlideRecord;
@@ -185,6 +185,21 @@ var ServiceType;
     ServiceType["Elasticache"] = "Elasticache";
     ServiceType["MemoryDB"] = "MemoryDB";
 })(ServiceType || (exports.ServiceType = ServiceType = {}));
+/**
+ * Controls how the client discovers node roles and topology in standalone mode.
+ */
+var NodeDiscoveryMode;
+(function (NodeDiscoveryMode) {
+    /** Default: verify node roles via INFO REPLICATION, use only provided addresses. */
+    NodeDiscoveryMode[NodeDiscoveryMode["Standard"] = 0] = "Standard";
+    /** Skip role detection entirely. Trust provided addresses as-is; first address is primary.
+     *  Use when connecting through a proxy (e.g., Envoy) or when the topology is known and static.
+     *  Note: Do not set `clientName` when using this mode with a proxy. */
+    NodeDiscoveryMode[NodeDiscoveryMode["Static"] = 1] = "Static";
+    /** Discover full topology (primary + all replicas) from any starting node.
+     *  Provide any single node address and the client will find and connect to all other nodes. */
+    NodeDiscoveryMode[NodeDiscoveryMode["DiscoverAll"] = 2] = "DiscoverAll";
+})(NodeDiscoveryMode || (exports.NodeDiscoveryMode = NodeDiscoveryMode = {}));
 /**
  * Enum of Valkey data types
  * `STRING`
@@ -556,6 +571,33 @@ class BaseClient {
             });
         });
     }
+    createGetCacheMetricsPromise(command) {
+        this.ensureClientIsOpen();
+        return new Promise((resolve, reject) => {
+            const callbackIdx = this.getCallbackIndex();
+            this.promiseCallbackFunctions[callbackIdx] = [resolve, reject];
+            this.writeOrBufferRequest(new ProtobufMessage_1.command_request.CommandRequest({
+                callbackIdx,
+                getCacheMetrics: command,
+            }), (message, writer) => {
+                ProtobufMessage_1.command_request.CommandRequest.encodeDelimited(message, writer);
+            });
+        });
+    }
+    /**
+     * @internal
+     * Get cache metrics.
+     *
+     * @param metricsType - Type of metric to retrieve (e.g., hit rate, miss rate).
+     * @returns The requested cache metric.
+     * @throws RequestError if client-side caching is not enabled or metrics tracking is disabled.
+     */
+    async getCacheMetrics(metricsType) {
+        const getCacheMetrics = ProtobufMessage_1.command_request.GetCacheMetrics.create({
+            metricsTypes: metricsType,
+        });
+        return await this.createGetCacheMetricsPromise(getCacheMetrics);
+    }
     createScriptInvocationPromise(command, options = {}) {
         this.ensureClientIsOpen();
         return new Promise((resolve, reject) => {
@@ -2950,7 +2992,7 @@ class BaseClient {
     }
     /** Gets the intersection of all the given sets.
      *
-     * @see {@link https://valkey.io/docs/latest/commands/sinter/|valkey.io} for more details.
+     * @see {@link https://valkey.io/commands/sinter/|valkey.io} for more details.
      * @remarks When in cluster mode, all `keys` must map to the same hash slot.
      *
      * @param keys - The `keys` of the sets to get the intersection.
@@ -5559,6 +5601,7 @@ class BaseClient {
         preferReplica: ProtobufMessage_1.connection_request.ReadFrom.PreferReplica,
         AZAffinity: ProtobufMessage_1.connection_request.ReadFrom.AZAffinity,
         AZAffinityReplicasAndPrimary: ProtobufMessage_1.connection_request.ReadFrom.AZAffinityReplicasAndPrimary,
+        allNodes: ProtobufMessage_1.connection_request.ReadFrom.AllNodes,
     };
     /**
      * Returns the number of messages that were successfully acknowledged by the consumer group member of a stream.
@@ -7026,7 +7069,19 @@ class BaseClient {
             !options.clientAz) {
             throw new _1.ConfigurationError(`clientAz must be set when readFrom is set to ${options.readFrom}`);
         }
-        return {
+        // Configure client-side cache if provided
+        let clientSideCache;
+        if (options.clientSideCache) {
+            const cache = options.clientSideCache;
+            clientSideCache = ProtobufMessage_1.connection_request.ClientSideCache.create({
+                cacheId: cache.cacheId,
+                maxCacheKb: cache.maxCacheKb,
+                entryTtlMs: cache.entryTtlMs,
+                evictionPolicy: cache.evictionPolicy,
+                enableMetrics: cache.enableMetrics,
+            });
+        }
+        const request = {
             protocol,
             clientName: options.clientName,
             addresses: options.addresses,
@@ -7042,7 +7097,13 @@ class BaseClient {
             clientAz: options.clientAz ?? null,
             connectionRetryStrategy: options.connectionBackoff,
             lazyConnect: options.lazyConnect ?? false,
+            clientSideCache,
         };
+        if (options.compression) {
+            (0, _1.validateCompressionConfiguration)(options.compression);
+            request.compressionConfig = (0, _1.compressionConfigToProtobuf)(options.compression, ProtobufMessage_1.connection_request);
+        }
+        return request;
     }
     /**
      * @internal
@@ -7221,6 +7282,96 @@ class BaseClient {
         const response = await this.createRefreshIamTokenPromise(refresh);
         return response; // "OK"
     }
+    /**
+     * Get the cache hit rate (hits / total requests).
+     *
+     * @returns The cache hit rate as a number between 0.0 and 1.0.
+     * @throws RequestError if client-side caching is not enabled or metrics tracking is disabled.
+     * @example
+     * ```typescript
+     * const hitRate = await client.getCacheHitRate();
+     * console.log(`Cache hit rate: ${(hitRate * 100).toFixed(2)}%`);
+     * // Output: Cache hit rate: 85.50%
+     * ```
+     */
+    async getCacheHitRate() {
+        return await this.getCacheMetrics(ProtobufMessage_1.command_request.CacheMetricsType.HitRate);
+    }
+    /**
+     * Get the cache miss rate (misses / total requests).
+     *
+     * @returns The cache miss rate as a number between 0.0 and 1.0.
+     * @throws RequestError if client-side caching is not enabled or metrics tracking is disabled.
+     * @example
+     * ```typescript
+     * const missRate = await client.getCacheMissRate();
+     * console.log(`Cache miss rate: ${(missRate * 100).toFixed(2)}%`);
+     * // Output: Cache miss rate: 14.50%
+     * ```
+     */
+    async getCacheMissRate() {
+        return await this.getCacheMetrics(ProtobufMessage_1.command_request.CacheMetricsType.MissRate);
+    }
+    /**
+     * Get the current number of entries in the client-side cache.
+     *
+     * @returns The number of entries in the cache.
+     * @throws RequestError if client-side caching is not enabled.
+     * @example
+     * ```typescript
+     * const entryCount = await client.getCacheEntryCount();
+     * console.log(`Cache entry count: ${entryCount}`);
+     * // Output: Cache entry count: 1500
+     * ```
+     */
+    async getCacheEntryCount() {
+        return await this.getCacheMetrics(ProtobufMessage_1.command_request.CacheMetricsType.EntryCount);
+    }
+    /**
+     * Get the total number of entries evicted from the client-side cache due to memory constraints.
+     *
+     * @returns The number of evictions.
+     * @throws RequestError if client-side caching is not enabled or metrics tracking is disabled.
+     * @example
+     * ```typescript
+     * const evictions = await client.getCacheEvictions();
+     * console.log(`Cache evictions: ${evictions}`);
+     * // Output: Cache evictions: 100
+     * ```
+     */
+    async getCacheEvictions() {
+        return await this.getCacheMetrics(ProtobufMessage_1.command_request.CacheMetricsType.Evictions);
+    }
+    /**
+     * Get the total number of entries expired from the client-side cache.
+     *
+     * @returns The number of expirations.
+     * @throws RequestError if client-side caching is not enabled or metrics tracking is disabled.
+     * @example
+     * ```typescript
+     * const expirations = await client.getCacheExpirations();
+     * console.log(`Cache expirations: ${expirations}`);
+     * // Output: Cache expirations: 250
+     * ```
+     */
+    async getCacheExpirations() {
+        return await this.getCacheMetrics(ProtobufMessage_1.command_request.CacheMetricsType.Expirations);
+    }
+    /**
+     * Get the total number of cache lookups (hits + misses).
+     *
+     * @returns The total number of cache lookups.
+     * @throws RequestError if client-side caching is not enabled or metrics tracking is disabled.
+     * @example
+     * ```typescript
+     * const totalLookups = await client.getCacheTotalLookups();
+     * console.log(`Total cache lookups: ${totalLookups}`);
+     * // Output: Total cache lookups: 5000
+     * ```
+     */
+    async getCacheTotalLookups() {
+        return await this.getCacheMetrics(ProtobufMessage_1.command_request.CacheMetricsType.TotalLookups);
+    }
     /**
      * Subscribes the client to the specified channels (non-blocking).
      * Returns immediately without waiting for subscription confirmation.

package/build-ts/ClientSideCache.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+ */
+import { EvictionPolicy } from "./EvictionPolicy.js";
+/**
+ * Configuration options for creating a ClientSideCache.
+ */
+export interface ClientSideCacheConfig {
+    /**
+     * Maximum memory limit for the cache in kilobytes.
+     * Must be greater than zero.
+     */
+    maxCacheKb: number;
+    /**
+     * Time-To-Live for cache entries in milliseconds.
+     * Set to 0 to disable TTL expiration (entries remain until evicted or invalidated).
+     */
+    entryTtlMs: number;
+    /**
+     * Optional eviction policy to use when cache reaches memory limit.
+     * Defaults to LRU if not specified.
+     */
+    evictionPolicy?: EvictionPolicy;
+    /**
+     * Whether to enable metrics collection for this cache.
+     * Defaults to false if not specified.
+     */
+    enableMetrics?: boolean;
+}
+/**
+ * Optional configuration options for the static create method.
+ */
+export interface ClientSideCacheOptions {
+    /**
+     * Optional eviction policy to use when cache reaches memory limit.
+     */
+    evictionPolicy?: EvictionPolicy;
+    /**
+     * Whether to enable metrics collection for this cache.
+     */
+    enableMetrics?: boolean;
+}
+/**
+ * Configuration class for client-side caching.
+ *
+ * Client-side caching reduces network round-trips and server load by storing
+ * frequently accessed data locally on the client. This class provides
+ * configurable TTL-based expiration, multiple eviction policies, and
+ * comprehensive metrics tracking.
+ *
+ * @example
+ * ```typescript
+ * // Create cache with auto-generated ID
+ * const cache = ClientSideCache.create(1024, 60000); // 1MB cache, 1 min TTL
+ *
+ * // Create cache with custom configuration
+ * const customCache = new ClientSideCache({
+ *   maxCacheKb: 2048,
+ *   entryTtlMs: 300000,
+ *   evictionPolicy: EvictionPolicy.LFU,
+ *   enableMetrics: true
+ * });
+ * ```
+ */
+export declare class ClientSideCache {
+    /**
+     * Maximum memory limit for the cache in kilobytes.
+     */
+    readonly maxCacheKb: number;
+    /**
+     * Time-To-Live for cache entries in milliseconds. 0 means no expiration.
+     */
+    readonly entryTtlMs: number;
+    /**
+     * Optional eviction policy to use when cache reaches memory limit.
+     */
+    readonly evictionPolicy?: EvictionPolicy;
+    /**
+     * Whether metrics collection is enabled for this cache.
+     */
+    readonly enableMetrics: boolean;
+    /**
+     * Creates a new ClientSideCache instance.
+     *
+     * @param config - Configuration options for the cache
+     * @throws {Error} If maxCacheKb is not a positive number
+     * @throws {Error} If entryTtlMs is negative
+     */
+    constructor(config: ClientSideCacheConfig);
+    /**
+     * Factory method to create a ClientSideCache with auto-generated cache ID.
+     *
+     * @param maxCacheKb - Maximum memory limit for the cache in kilobytes
+     * @param entryTtlMs - TTL for cache entries in milliseconds. Use 0 for no expiration.
+     * @param options - Optional configuration options
+     * @returns A new ClientSideCache instance with auto-generated cache ID
+     * @throws {Error} If maxCacheKb is not a positive number
+     * @throws {Error} If entryTtlMs is negative
+     *
+     * @example
+     * ```typescript
+     * // Simple cache with 1MB limit and no TTL
+     * const cache = ClientSideCache.create(1024, 0);
+     *
+     * // Cache with TTL and LFU eviction
+     * const cacheWithOptions = ClientSideCache.create(2048, 300000, {
+     *   evictionPolicy: EvictionPolicy.LFU,
+     *   enableMetrics: false
+     * });
+     * ```
+     */
+    static create(maxCacheKb: number, entryTtlMs: number, options?: ClientSideCacheOptions): ClientSideCache;
+}

package/build-ts/ClientSideCache.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientSideCache = void 0;
+const crypto_1 = require("crypto");
+/**
+ * Configuration class for client-side caching.
+ *
+ * Client-side caching reduces network round-trips and server load by storing
+ * frequently accessed data locally on the client. This class provides
+ * configurable TTL-based expiration, multiple eviction policies, and
+ * comprehensive metrics tracking.
+ *
+ * @example
+ * ```typescript
+ * // Create cache with auto-generated ID
+ * const cache = ClientSideCache.create(1024, 60000); // 1MB cache, 1 min TTL
+ *
+ * // Create cache with custom configuration
+ * const customCache = new ClientSideCache({
+ *   maxCacheKb: 2048,
+ *   entryTtlMs: 300000,
+ *   evictionPolicy: EvictionPolicy.LFU,
+ *   enableMetrics: true
+ * });
+ * ```
+ */
+class ClientSideCache {
+    /**
+     * @internal
+     * Unique identifier for the cache instance. Auto-generated using UUID.
+     */
+    cacheId;
+    /**
+     * Maximum memory limit for the cache in kilobytes.
+     */
+    maxCacheKb;
+    /**
+     * Time-To-Live for cache entries in milliseconds. 0 means no expiration.
+     */
+    entryTtlMs;
+    /**
+     * Optional eviction policy to use when cache reaches memory limit.
+     */
+    evictionPolicy;
+    /**
+     * Whether metrics collection is enabled for this cache.
+     */
+    enableMetrics;
+    /**
+     * Creates a new ClientSideCache instance.
+     *
+     * @param config - Configuration options for the cache
+     * @throws {Error} If maxCacheKb is not a positive number
+     * @throws {Error} If entryTtlMs is negative
+     */
+    constructor(config) {
+        if (config.maxCacheKb <= 0) {
+            throw new Error("maxCacheKb must be a positive number");
+        }
+        if (config.entryTtlMs < 0) {
+            throw new Error("entryTtlMs must be non-negative (0 = no expiration)");
+        }
+        this.cacheId = (0, crypto_1.randomUUID)();
+        this.maxCacheKb = config.maxCacheKb;
+        this.entryTtlMs = config.entryTtlMs;
+        this.evictionPolicy = config.evictionPolicy;
+        this.enableMetrics = config.enableMetrics ?? false;
+    }
+    /**
+     * Factory method to create a ClientSideCache with auto-generated cache ID.
+     *
+     * @param maxCacheKb - Maximum memory limit for the cache in kilobytes
+     * @param entryTtlMs - TTL for cache entries in milliseconds. Use 0 for no expiration.
+     * @param options - Optional configuration options
+     * @returns A new ClientSideCache instance with auto-generated cache ID
+     * @throws {Error} If maxCacheKb is not a positive number
+     * @throws {Error} If entryTtlMs is negative
+     *
+     * @example
+     * ```typescript
+     * // Simple cache with 1MB limit and no TTL
+     * const cache = ClientSideCache.create(1024, 0);
+     *
+     * // Cache with TTL and LFU eviction
+     * const cacheWithOptions = ClientSideCache.create(2048, 300000, {
+     *   evictionPolicy: EvictionPolicy.LFU,
+     *   enableMetrics: false
+     * });
+     * ```
+     */
+    static create(maxCacheKb, entryTtlMs, options) {
+        return new ClientSideCache({
+            maxCacheKb,
+            entryTtlMs,
+            evictionPolicy: options?.evictionPolicy,
+            enableMetrics: options?.enableMetrics,
+        });
+    }
+}
+exports.ClientSideCache = ClientSideCache;

package/build-ts/CompressionConfiguration.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+ */
+/**
+ * Compression backend to use for automatic value compression.
+ */
+export declare enum CompressionBackend {
+    /** Use zstd compression backend. */
+    ZSTD = 0,
+    /** Use lz4 compression backend. */
+    LZ4 = 1
+}
+/**
+ * Configuration for automatic compression of values sent to the server.
+ *
+ * NOTE: This is an experimental feature. The API may change in future releases.
+ *
+ * When compression is enabled, values that meet the minimum size threshold
+ * will be automatically compressed before being sent to the server and
+ * decompressed when retrieved.
+ *
+ * @example
+ * ```typescript
+ * // Enable compression with defaults (ZSTD, 64 byte threshold)
+ * const config: CompressionConfiguration = { enabled: true };
+ *
+ * // Enable compression with LZ4 backend and custom threshold
+ * const config: CompressionConfiguration = {
+ *     enabled: true,
+ *     backend: CompressionBackend.LZ4,
+ *     minCompressionSize: 128,
+ * };
+ *
+ * // Enable compression with custom max decompressed size limit
+ * const config: CompressionConfiguration = {
+ *     enabled: true,
+ *     maxDecompressedSize: 100 * 1024 * 1024, // 100MB limit
+ * };
+ * ```
+ */
+export interface CompressionConfiguration {
+    /**
+     * Whether compression is enabled. Defaults to false.
+     */
+    enabled: boolean;
+    /**
+     * The compression backend to use. Defaults to ZSTD.
+     */
+    backend?: CompressionBackend;
+    /**
+     * The compression level. If not set, the backend's default level is used.
+     * Valid ranges are backend-specific and validated by the Rust core.
+     * ZSTD default is 3, LZ4 default is 0.
+     */
+    compressionLevel?: number;
+    /**
+     * Minimum size in bytes for values to be compressed.
+     * Values smaller than this will not be compressed.
+     * Must be at least 6 bytes. Defaults to 64 bytes.
+     */
+    minCompressionSize?: number;
+    /**
+     * Maximum allowed size in bytes for decompressed data.
+     * This limit prevents decompression bombs (maliciously crafted compressed data
+     * that expands to huge sizes).
+     * If not set, defaults to 512MB (matching Valkey's proto-max-bulk-len).
+     */
+    maxDecompressedSize?: number;
+}