Client Side Caching (#2947)

* CSC POC ontop of Parser

* add csc file that weren't merged after patch

* address review comments

* nits to try and fix github

* last change from review

* Update client-side cache and improve documentation

* Add client side caching RESP3 validation

* Add documentation for RESP and unstableResp3 options

* Add comprehensive cache statistics

The `CacheStats` class provides detailed metrics like hit/miss counts,
load success/failure counts, total load time, and eviction counts.
It also offers derived metrics such as hit/miss rates, load failure rate,
and average load penalty. The design is inspired by Caffeine.

`BasicClientSideCache` now uses a `StatsCounter` to accumulate these
statistics, exposed via a new `stats()` method. The previous
`cacheHits()` and `cacheMisses()` methods have been removed.

A `recordStats` option (default: true) in `ClientSideCacheConfig`
allows disabling statistics collection.

---------

Co-authored-by: Shaya Potter <[email protected]>

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,100 @@ 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
+// `cache.stats()` returns a `CacheStats` object with comprehensive statistics.
+const statistics = cache.stats();
+
+// Key metrics:
+const hits = statistics.hitCount;        // Number of cache hits
+const misses = statistics.missCount;      // Number of cache misses
+const hitRate = statistics.hitRate();     // Cache hit rate (0.0 to 1.0)
+
+// Many other metrics are available on the `statistics` object, e.g.:
+// statistics.missRate(), statistics.loadSuccessCount,
+// statistics.averageLoadPenalty(), statistics.requestCount()
+```
+
+## 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
+});
+```

packages/client/index.ts

@@ -34,3 +34,6 @@ export { GEO_REPLY_WITH, GeoReplyWith } from './lib/commands/GEOSEARCH_WITH';
 export { SetOptions } from './lib/commands/SET';
 
 export { REDIS_FLUSH_MODES } from './lib/commands/FLUSHALL';
+
+export { BasicClientSideCache, BasicPooledClientSideCache } from './lib/client/cache';
+

packages/client/lib/RESP/types.ts

@@ -314,11 +314,17 @@ export interface CommanderConfig<
   functions?: F;
   scripts?: S;
   /**
-   * TODO
+   * Specifies the Redis Serialization Protocol version to use.
+   * RESP2 is the default (value 2), while RESP3 (value 3) provides
+   * additional data types and features introduced in Redis 6.0.
    */
   RESP?: RESP;
   /**
-   * TODO
+   * When set to true, enables commands that have unstable RESP3 implementations.
+   * When using RESP3 protocol, commands marked as having unstable RESP3 support
+   * will throw an error unless this flag is explicitly set to true.
+   * This primarily affects modules like Redis Search where response formats
+   * in RESP3 mode may change in future versions.
    */
   unstableResp3?: boolean;
 }