Update client-side cache and improve documentation

Author: bobymicroby

README.md

@@ -235,6 +235,24 @@ of sending a `QUIT` command to the server, the client can simply close the netwo
 client.destroy();
 ```
 
+### Client Side Caching
+
+Node Redis v5 adds support for [Client Side Caching](https://redis.io/docs/manual/client-side-caching/), which enables clients to cache query results locally. The Redis server will notify the client when cached results are no longer valid.
+
+```typescript
+// Enable client side caching with RESP3
+const client = createClient({
+  RESP: 3, 
+  clientSideCache: {
+    ttl: 0,             // Time-to-live (0 = no expiration)
+    maxEntries: 0,      // Maximum entries (0 = unlimited)
+    evictPolicy: "LRU"  // Eviction policy: "LRU" or "FIFO"
+  }
+});
+```
+
+See the [V5 documentation](./docs/v5.md#client-side-caching) for more details and advanced usage.
+
 ### Auto-Pipelining
 
 Node Redis will automatically pipeline requests that are made during the same "tick".

docs/v5.md

@@ -89,3 +89,91 @@ await multi.exec(); // Array<ReplyUnion>
 await multi.exec<'typed'>(); // [string]
 await multi.execTyped(); // [string]
 ```
+
+# Client Side Caching
+
+Node Redis v5 adds support for [Client Side Caching](https://redis.io/docs/manual/client-side-caching/), which enables clients to cache query results locally. The server will notify the client when cached results are no longer valid.
+
+Client Side Caching is only supported with RESP3.
+
+## Usage
+
+There are two ways to implement client side caching:
+
+### Anonymous Cache
+
+```javascript
+const client = createClient({
+  RESP: 3, 
+  clientSideCache: {
+    ttl: 0,             // Time-to-live in milliseconds (0 = no expiration)
+    maxEntries: 0,      // Maximum entries to store (0 = unlimited)
+    evictPolicy: "LRU"  // Eviction policy: "LRU" or "FIFO"
+  }
+});
+```
+
+In this instance, the cache is managed internally by the client.
+
+### Controllable Cache
+
+```javascript
+import { BasicClientSideCache } from 'redis';
+
+const cache = new BasicClientSideCache({
+  ttl: 0,
+  maxEntries: 0,
+  evictPolicy: "LRU"
+});
+
+const client = createClient({
+  RESP: 3,
+  clientSideCache: cache
+});
+```
+
+With this approach, you have direct access to the cache object for more control:
+
+```javascript
+// Manually invalidate keys
+cache.invalidate(key);
+
+// Clear the entire cache
+cache.clear();
+
+// Get cache metrics
+const hits = cache.cacheHits();
+const misses = cache.cacheMisses();
+```
+
+## Pooled Caching
+
+Client side caching also works with client pools. For pooled clients, the cache is shared across all clients in the pool:
+
+```javascript
+const client = createClientPool({RESP: 3}, {
+  clientSideCache: {
+    ttl: 0,
+    maxEntries: 0,
+    evictPolicy: "LRU"
+  },
+  minimum: 5
+});
+```
+
+For a controllable pooled cache:
+
+```javascript
+import { BasicPooledClientSideCache } from 'redis';
+
+const cache = new BasicPooledClientSideCache({
+  ttl: 0,
+  maxEntries: 0,
+  evictPolicy: "LRU"
+});
+
+const client = createClientPool({RESP: 3}, {
+  clientSideCache: cache,
+  minimum: 5
+});
+```

package-lock.json

@@ -8,10 +8,31 @@ type CmdFunc = () => Promise<ReplyUnion>;
 
 type EvictionPolicy = "LRU" | "FIFO"
 
+/**
+ * Configuration options for Client Side Cache
+ */
 export interface ClientSideCacheConfig {
+  /**
+   * Time-to-live in milliseconds for cached entries.
+   * Use 0 for no expiration.
+   * @default 0
+   */
   ttl?: number;
+  
+  /**
+   * Maximum number of entries to store in the cache.
+   * Use 0 for unlimited entries.
+   * @default 0
+   */
   maxEntries?: number;
-  evictPolocy?: EvictionPolicy;
+  
+  /**
+   * Eviction policy to use when the cache reaches its capacity.
+   * - "LRU" (Least Recently Used): Evicts least recently accessed entries first
+   * - "FIFO" (First In First Out): Evicts oldest entries first
+   * @default "LRU"
+   */
+  evictPolicy?: EvictionPolicy;
 }
 
 type CacheCreator = {
@@ -109,7 +130,7 @@ export class BasicClientSideCache extends ClientSideCacheProvider {
     this.#keyToCacheKeySetMap = new Map<string, Set<string>>();
     this.ttl = config?.ttl ?? 0;
     this.maxEntries = config?.maxEntries ?? 0;
-    this.lru = config?.evictPolocy !== "FIFO"
+    this.lru = config?.evictPolicy !== "FIFO"
   }
 
   /* logic of how caching works:

packages/client/lib/client/README-cache.md

@@ -78,11 +78,60 @@ export interface RedisClientOptions<
    */
   pingInterval?: number;
   /**
-   * TODO
+   * Default command options to be applied to all commands executed through this client.
+   * 
+   * These options can be overridden on a per-command basis when calling specific commands.
+   * 
+   * @property {symbol} [chainId] - Identifier for chaining commands together
+   * @property {boolean} [asap] - When true, the command is executed as soon as possible
+   * @property {AbortSignal} [abortSignal] - AbortSignal to cancel the command
+   * @property {TypeMapping} [typeMapping] - Custom type mappings between RESP and JavaScript types
+   * 
+   * @example Setting default command options
+   * ```
+   * const client = createClient({
+   *   commandOptions: {
+   *     asap: true,
+   *     typeMapping: {
+   *       // Custom type mapping configuration
+   *     }
+   *   }
+   * });
+   * ```
    */
   commandOptions?: CommandOptions<TYPE_MAPPING>;
   /**
-   * TODO
+   * Client Side Caching configuration.
+   * 
+   * Enables Redis Servers and Clients to work together to cache results from commands 
+   * sent to a server. The server will notify the client when cached results are no longer valid.
+   * 
+   * Note: Client Side Caching is only supported with RESP3.
+   * 
+   * @example Anonymous cache configuration
+   * ```
+   * const client = createClient({
+   *   RESP: 3, 
+   *   clientSideCache: {
+   *     ttl: 0,
+   *     maxEntries: 0,
+   *     evictPolicy: "LRU" 
+   *   }
+   * });
+   * ```
+   * 
+   * @example Using a controllable cache
+   * ```
+   * const cache = new BasicClientSideCache({ 
+   *   ttl: 0, 
+   *   maxEntries: 0, 
+   *   evictPolicy: "LRU" 
+   * });
+   * const client = createClient({
+   *   RESP: 3, 
+   *   clientSideCache: cache
+   * });
+   * ```
    */
   clientSideCache?: ClientSideCacheProvider | ClientSideCacheConfig;
 }

packages/client/lib/client/cache.ts

@@ -24,15 +24,55 @@ export interface RedisPoolOptions {
    */
   acquireTimeout: number;
   /**
-   * TODO
+   * The delay in milliseconds before a cleanup operation is performed on idle clients.
+   * 
+   * After this delay, the pool will check if there are too many idle clients and destroy 
+   * excess ones to maintain optimal pool size.
    */
   cleanupDelay: number;
   /**
-   * TODO
+   * Client Side Caching configuration for the pool.
+   * 
+   * Enables Redis Servers and Clients to work together to cache results from commands 
+   * sent to a server. The server will notify the client when cached results are no longer valid.
+   * In pooled mode, the cache is shared across all clients in the pool.
+   * 
+   * Note: Client Side Caching is only supported with RESP3.
+   * 
+   * @example Anonymous cache configuration
+   * ```
+   * const client = createClientPool({RESP: 3}, {
+   *   clientSideCache: {
+   *     ttl: 0,
+   *     maxEntries: 0,
+   *     evictPolicy: "LRU"
+   *   },
+   *   minimum: 5
+   * });
+   * ```
+   * 
+   * @example Using a controllable cache
+   * ```
+   * const cache = new BasicPooledClientSideCache({
+   *   ttl: 0,
+   *   maxEntries: 0,
+   *   evictPolicy: "LRU"
+   * });
+   * const client = createClientPool({RESP: 3}, {
+   *   clientSideCache: cache,
+   *   minimum: 5
+   * });
+   * ```
    */
   clientSideCache?: PooledClientSideCacheProvider | ClientSideCacheConfig;
   /**
-   * TODO
+   * Enable experimental support for RESP3 module commands.
+   * 
+   * When enabled, allows the use of module commands that have been adapted 
+   * for the RESP3 protocol. This is an unstable feature and may change in 
+   * future versions.
+   * 
+   * @default false
    */
   unstableResp3Modules?: boolean;
 }

packages/client/lib/client/index.ts

@@ -234,6 +234,23 @@ of sending a `QUIT` command to the server, the client can simply close the netwo
 ```typescript
 client.destroy();
 ```
+### Client Side Caching
+
+Node Redis v5 adds support for [Client Side Caching](https://redis.io/docs/manual/client-side-caching/), which enables clients to cache query results locally. The Redis server will notify the client when cached results are no longer valid.
+
+```typescript
+// Enable client side caching with RESP3
+const client = createClient({
+  RESP: 3, 
+  clientSideCache: {
+    ttl: 0,             // Time-to-live (0 = no expiration)
+    maxEntries: 0,      // Maximum entries (0 = unlimited)
+    evictPolicy: "LRU"  // Eviction policy: "LRU" or "FIFO"
+  }
+});
+```
+
+See the [V5 documentation](../../docs/v5.md#client-side-caching) for more details and advanced usage.
 
 ### Auto-Pipelining