@trieb.work/nextjs-turbo-redis-cache 1.14.1 → 1.15.1

package/README.md

@@ -1,9 +1,9 @@
-# nextjs-turbo-redis-cache
+# nextjs-turbo-redis-cache - Next.js Cache Handler
 
 [![npm version](https://img.shields.io/npm/v/@trieb.work/nextjs-turbo-redis-cache.svg)](https://www.npmjs.com/package/@trieb.work/nextjs-turbo-redis-cache)
 ![Turbo redis cache image](https://github.com/user-attachments/assets/4103191e-4f4d-4139-a519-0b5bfab3e8b4)
 
-The ultimate Redis caching solution for Next.js 15 / 16 and the app router. Built for production-ready, large-scale projects, it delivers unparalleled performance and efficiency with features tailored for high-traffic applications. This package has been created after extensibly testing the @neshca package and finding several major issues with it.
+The ultimate Redis Cache Handler for Next.js 15 / 16 and the app router. Built for production-ready, large-scale projects, it delivers unparalleled performance and efficiency with features tailored for high-traffic applications. This package has been created after extensibly testing the @neshca package and finding several major issues with it.
 
 Key Features:
 
@@ -15,6 +15,8 @@ Key Features:
 
 This library offers you an easy and high performant caching solution for docker, Kubernetes or Google Cloud Run deployments of Next.js. Read more on how it originated at [TRWK> Case Study](https://trwk.de/case-studies/nextjs-turbo-redis-cache).
 
+For a deep dive into the internal architecture (shared hash maps, SyncedMap, request deduplication, and how `get`/`set`/`revalidateTag` work under the hood), see [ARCHITECTURE.md](./ARCHITECTURE.md).
+
 ## Compatibility
 
 This package is compatible with Next.js 15.0.3 and above while using App Router. It is not compatible with Next.js 14.x. or 15-canary or if you are using Pages Router.
@@ -25,12 +27,12 @@ Tested versions are:
 - Nextjs 15.0.3 + redis client 4.7.0
 - Nextjs 15.2.4 + redis client 4.7.0
 - Nextjs 15.3.2 + redis client 4.7.0
-- Nextjs 15.4.7 + redis client 4.7.0
-- Nextjs 16.0.3 + redis client 4.7.0 (cacheComponents: false)
-- Nextjs 16.2.3 + redis client 4.7.0 (cacheComponents: false)
-- Nextjs 16.2.3 + redis client 4.7.0 (cacheComponents: true)
+- Nextjs 15.4.11 + redis client 4.7.0
+- Nextjs 16.0.11 + redis client 4.7.0 (cacheComponents: false)
+- Nextjs 16.2.6 + redis client 4.7.0 (cacheComponents: false)
+- Nextjs 16.2.6 + redis client 4.7.0 (cacheComponents: true)
 
-Currently PPR, 'use cache', cacheLife and cacheTag are not tested. Use these operations with caution and your own risk. [Cache Components](https://nextjs.org/docs/app/getting-started/cache-components) are supported experimentally (Next.js 16+).
+_Cache Components_ (Next.js 16+) are fully supported. Automated test coverage includes `'use cache'`, `cacheTag`, and `cacheLife` flows in the Cache Components integration suite.
 
 For Cache Components, see the "Cache Components handler (Next.js 16+)" section below.
 
@@ -133,26 +135,172 @@ const nextConfig = {
 }
 ```
 
-A working example of above can be found in the `test/integration/next-app-customized` folder.
+A working example of above can be found in the `test/nextjs-test-projects/next-app-customized` folder.
 
 ## Available Options
 
-| Option                        | Description                                                                                                                                                | Default Value                                                                                                                                                                                                                |
-| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| redisUrl                      | Redis connection url                                                                                                                                       | `process.env.REDIS_URL? process.env.REDIS_URL : process.env.REDISHOST ? redis://${process.env.REDISHOST}:${process.env.REDISPORT} : 'redis://localhost:6379'`                                                                |
-| database                      | Redis database number to use. Uses DB 0 for production, DB 1 otherwise                                                                                     | `process.env.VERCEL_ENV === 'production' ? 0 : 1`                                                                                                                                                                            |
-| keyPrefix                     | Prefix added to all Redis keys                                                                                                                             | `RedisStringsHandler` default: `process.env.KEY_PREFIX \|\| process.env.VERCEL_URL \|\| 'UNDEFINED_URL_'`<br> Next handlers resolve: `options.keyPrefix \|\| KEY_PREFIX \|\| VERCEL_URL \|\| BUILD_ID \|\| 'UNDEFINED_URL_'` |
-| sharedTagsKey                 | Key used to store shared tags hash map in Redis                                                                                                            | `'__sharedTags__'`                                                                                                                                                                                                           |
-| getTimeoutMs                  | Timeout in milliseconds for time critical Redis operations. If Redis get is not fulfilled within this time, returns null to avoid blocking site rendering. | `process.env.REDIS_COMMAND_TIMEOUT_MS ? (Number.parseInt(process.env.REDIS_COMMAND_TIMEOUT_MS) ?? 500) : 500`                                                                                                                |
-| revalidateTagQuerySize        | Number of entries to query in one batch during full sync of shared tags hash map                                                                           | `250`                                                                                                                                                                                                                        |
-| avgResyncIntervalMs           | Average interval in milliseconds between tag map full re-syncs                                                                                             | `3600000` (1 hour)                                                                                                                                                                                                           |
-| redisGetDeduplication         | Enable deduplication of Redis get requests via internal in-memory cache.                                                                                   | `true`                                                                                                                                                                                                                       |
-| inMemoryCachingTime           | Time in milliseconds to cache Redis get results in memory. Set this to 0 to disable in-memory caching completely.                                          | `10000`                                                                                                                                                                                                                      |
-| defaultStaleAge               | Default stale age in seconds for cached items                                                                                                              | `1209600` (14 days)                                                                                                                                                                                                          |
-| estimateExpireAge             | Function to calculate expire age (redis TTL value) from stale age                                                                                          | Production: `staleAge * 2`<br> Other: `staleAge * 1.2`                                                                                                                                                                       |
-| socketOptions                 | Redis client socket options for TLS/SSL configuration (e.g., `{ tls: true, rejectUnauthorized: false }`)                                                   | `{ connectTimeout: timeoutMs }`                                                                                                                                                                                              |
-| clientOptions                 | Additional Redis client options (e.g., username, password)                                                                                                 | `undefined`                                                                                                                                                                                                                  |
-| killContainerOnErrorThreshold | Number of consecutive errors before the container is killed. Set to 0 to disable.                                                                          | `Number.parseInt(process.env.KILL_CONTAINER_ON_ERROR_THRESHOLD) ?? 0 : 0`                                                                                                                                                    |
+| Option                        | Description                                                                                                                                                                     | Default Value                                                                                                                                                                                                                |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| redisUrl                      | Redis connection url                                                                                                                                                            | `process.env.REDIS_URL? process.env.REDIS_URL : process.env.REDISHOST ? redis://${process.env.REDISHOST}:${process.env.REDISPORT} : 'redis://localhost:6379'`                                                                |
+| database                      | Redis database number to use. Uses DB 0 for production, DB 1 otherwise                                                                                                          | `process.env.VERCEL_ENV === 'production' ? 0 : 1`                                                                                                                                                                            |
+| keyPrefix                     | Prefix added to all Redis keys                                                                                                                                                  | `RedisStringsHandler` default: `process.env.KEY_PREFIX \|\| process.env.VERCEL_URL \|\| 'UNDEFINED_URL_'`<br> Next handlers resolve: `options.keyPrefix \|\| KEY_PREFIX \|\| VERCEL_URL \|\| BUILD_ID \|\| 'UNDEFINED_URL_'` |
+| sharedTagsKey                 | Key used to store shared tags hash map in Redis                                                                                                                                 | `'__sharedTags__'`                                                                                                                                                                                                           |
+| getTimeoutMs                  | Timeout in milliseconds for time critical Redis operations. If Redis get is not fulfilled within this time, returns null to avoid blocking site rendering.                      | `process.env.REDIS_COMMAND_TIMEOUT_MS ? (Number.parseInt(process.env.REDIS_COMMAND_TIMEOUT_MS) ?? 500) : 500`                                                                                                                |
+| revalidateTagQuerySize        | Number of entries to query in one batch during full sync of shared tags hash map                                                                                                | `250`                                                                                                                                                                                                                        |
+| avgResyncIntervalMs           | Average interval in milliseconds between tag map full re-syncs                                                                                                                  | `3600000` (1 hour)                                                                                                                                                                                                           |
+| redisGetDeduplication         | Enable deduplication of Redis get requests via internal in-memory cache.                                                                                                        | `true`                                                                                                                                                                                                                       |
+| inMemoryCachingTime           | Time in milliseconds to cache Redis get results in memory. Set this to 0 to disable in-memory caching completely.                                                               | `10000`                                                                                                                                                                                                                      |
+| defaultStaleAge               | Default stale age in seconds for cached items                                                                                                                                   | `1209600` (14 days)                                                                                                                                                                                                          |
+| estimateExpireAge             | Function to calculate expire age (redis TTL value) from stale age                                                                                                               | Production: `staleAge * 2`<br> Other: `staleAge * 1.2`                                                                                                                                                                       |
+| socketOptions                 | Redis client socket options for TLS/SSL configuration (e.g., `{ tls: true, rejectUnauthorized: false }`)                                                                        | `{ connectTimeout: timeoutMs }`                                                                                                                                                                                              |
+| clientOptions                 | Additional Redis client options (e.g., username, password)                                                                                                                      | `undefined`                                                                                                                                                                                                                  |
+| killContainerOnErrorThreshold | Number of consecutive errors before the container is killed. Set to 0 to disable.                                                                                               | `Number.parseInt(process.env.KILL_CONTAINER_ON_ERROR_THRESHOLD) ?? 0 : 0`                                                                                                                                                    |
+| valueSerializer               | Pluggable wire-format codec for Redis string values (compression, encryption, custom encoding). See [Custom value serializer](#custom-value-serializer-compression-encryption). | `jsonCacheValueSerializer` (`JSON.stringify` with built-in `Buffer` and `Map` encoding)                                                                                                                                      |
+
+## Custom value serializer (compression, encryption)
+
+By default cache entries are stored as `JSON.stringify(...)` with built-in
+`Buffer` and `Map` encoding. For workloads where the encoded payload is large
+(big RSC trees, large fetch responses) or sensitive (PII), you can plug in a
+custom codec - gzip, brotli, AES, anything - via the `valueSerializer` option,
+without forking this package or losing the existing dedup / batch / keyspace
+features.
+
+### Contract
+
+- `serialize(entry)` is called on every `set()` with the in-memory `CacheEntry`. It must return the string written to Redis, or a `Promise<string>` for async codecs.
+- `deserialize(stored)` is called on every cache hit with the exact string read from Redis. It must return a `CacheEntry`, `null`, or a `Promise` of either. Returning `null` is treated as a cache miss - the handler returns `null` from `get()` without surfacing an error.
+- Both methods may be async, enabling non-blocking codecs such as `zlib.brotliCompress` or `crypto.subtle` that don't block the Node.js event loop. Synchronous implementations continue to work unchanged.
+- Only the main cache-entry storage path is routed through the serializer. Internal structures (`__sharedTags__`, `__revalidated_tags__`, `inMemoryDeduplicationCache`) are not affected.
+
+### Default export for reuse
+
+The default serializer is exported so you can wrap it (e.g. compress + JSON
+fallback) or compare against it by reference to detect that no custom
+serializer was configured. The underlying `Buffer` / `Map` JSON helpers used by
+the default are also exported for use inside custom codecs:
+
+```ts
+import {
+  jsonCacheValueSerializer,
+  bufferAndMapReplacer,
+  bufferAndMapReviver,
+} from '@trieb.work/nextjs-turbo-redis-cache';
+```
+
+> **Important:** a plain `JSON.stringify(value)` does not preserve native
+> `Buffer` or `Map` values inside a cache entry. RSC payloads contain
+> `Buffer`s. If you write a custom codec that doesn't use the exported
+> `bufferAndMapReplacer` / `bufferAndMapReviver` (or doesn't wrap
+> `jsonCacheValueSerializer`), expect those to come back as plain objects.
+
+### Example: gzip (sync)
+
+Wraps `bufferAndMapReplacer` / `bufferAndMapReviver` so native `Buffer` and
+`Map` values inside the cache entry round-trip unchanged. `gzipSync` /
+`gunzipSync` block the event loop - prefer the async brotli example below for
+hot workloads.
+
+```ts
+import { gzipSync, gunzipSync } from 'node:zlib';
+import {
+  RedisStringsHandler,
+  bufferAndMapReplacer,
+  bufferAndMapReviver,
+} from '@trieb.work/nextjs-turbo-redis-cache';
+
+const gzipSerializer = {
+  serialize(value) {
+    const json = JSON.stringify(value, bufferAndMapReplacer);
+    return gzipSync(json).toString('base64');
+  },
+  deserialize(stored) {
+    const buf = Buffer.from(stored, 'base64');
+    return JSON.parse(gunzipSync(buf).toString('utf8'), bufferAndMapReviver);
+  },
+};
+
+export default class CustomizedCacheHandler {
+  constructor() {
+    this.handler = new RedisStringsHandler({
+      valueSerializer: gzipSerializer,
+    });
+  }
+  // ... delegate get/set/revalidateTag/resetRequestCache to this.handler
+}
+```
+
+### Example: brotli (async, non-blocking)
+
+Uses `promisify(brotliCompress)` and `promisify(brotliDecompress)` so
+compression runs on a worker thread and doesn't block the event loop.
+
+```ts
+import { promisify } from 'node:util';
+import { brotliCompress, brotliDecompress } from 'node:zlib';
+import {
+  RedisStringsHandler,
+  bufferAndMapReplacer,
+  bufferAndMapReviver,
+} from '@trieb.work/nextjs-turbo-redis-cache';
+
+const brotliCompressAsync = promisify(brotliCompress);
+const brotliDecompressAsync = promisify(brotliDecompress);
+
+const brotliSerializer = {
+  async serialize(value) {
+    const json = JSON.stringify(value, bufferAndMapReplacer);
+    const compressed = await brotliCompressAsync(Buffer.from(json, 'utf8'));
+    return compressed.toString('base64');
+  },
+  async deserialize(stored) {
+    const buf = Buffer.from(stored, 'base64');
+    const decompressed = await brotliDecompressAsync(buf);
+    return JSON.parse(decompressed.toString('utf8'), bufferAndMapReviver);
+  },
+};
+
+export default class CustomizedCacheHandler {
+  constructor() {
+    this.handler = new RedisStringsHandler({
+      valueSerializer: brotliSerializer,
+    });
+  }
+  // ... delegate get/set/revalidateTag/resetRequestCache to this.handler
+}
+```
+
+### Operational notes
+
+- **Changing the serializer makes existing Redis keys unreadable.** Any change
+  to the codec - swapping JSON for gzip, bumping a compression level, rotating
+  an encryption key - means previously written entries can no longer be
+  decoded. Either flush the affected keys (`FLUSHDB`, or scoped `UNLINK` of
+  `keyPrefix*`) or bump `keyPrefix` before deploying so old and new entries
+  live in disjoint keyspaces.
+- **`Buffer` and `Map` encoding is built into the default.** The default
+  `jsonCacheValueSerializer` uses this package's `bufferAndMapReplacer` /
+  `bufferAndMapReviver` so native `Buffer` and `Map` values inside a
+  `CacheEntry` round-trip transparently. If you write a custom serializer that
+  doesn't reuse those (e.g. plain `JSON.stringify` over a binary payload),
+  expect RSC payload `Buffer`s to come back as plain `{ type: 'Buffer', data:
+[...] }` objects. Reuse the exported default inside your codec, or use the
+  exported `bufferAndMapReplacer` / `bufferAndMapReviver`, to keep that
+  behavior.
+- **The in-memory deduplication cache stores the wire-format string verbatim.**
+  When `redisGetDeduplication` is enabled (default), the value seeded after
+  `set()` and returned to subsequent `get()` calls is the exact string
+  produced by `serialize()`. With a compressing or encrypting codec that
+  means every dedup hit re-runs `deserialize()` (i.e. re-decompresses or
+  re-decrypts). For very hot keys, evaluate whether the per-hit codec cost
+  outweighs the Redis round-trip the dedup is saving.
+- **Other internal trieb structures are not affected by `valueSerializer`.**
+  Only the main cache entries written by `set()` and read by `get()` go
+  through the codec. The shared-tags map and the revalidated-tags map are
+  untouched.
+- **Cache Components handler is out of scope for now.** This option only
+  affects `RedisStringsHandler`. The Next.js 16+ `CacheComponentsHandler` does
+  not currently route through `valueSerializer`; that's a candidate follow-up.
 
 ## TLS Configuration
 
@@ -181,6 +329,8 @@ module.exports = class CustomizedCacheHandler {
 
 ## Consistency of Redis and this caching implementation
 
+> For a detailed description of the shared hash maps (`sharedTagsMap`, `revalidatedTagsMap`), the `SyncedMap` Pub/Sub mechanism, and the `DeduplicatedRequestHandler`, see [ARCHITECTURE.md](./ARCHITECTURE.md).
+
 To understand consistency levels of this caching implementation we first have to understand the consistency of redis itself:
 Redis executes commands in a single-threaded manner. This ensures that all operations are processed sequentially, so clients always see a consistent view of the data.
 But depending on the setup of redis this can change:
@@ -189,23 +339,43 @@ But depending on the setup of redis this can change:
 - Eventual consistency: In a master-replica setup (strong consistency only while there is no failover)
 - Eventual consistency: In Redis Cluster mode
 
-Consistency levels of Caching Handler:
-If Redis is used in a single node setup and Request Deduplication is turned off, only then the caching handler will have strong consistency.
+### Consistency levels of the Caching Handler
+
+Strong consistency is only achievable when **all** of the following conditions are met:
+
+1. Redis is used in a single node setup
+2. Only a **single application instance** is running (no cross-instance Pub/Sub propagation delay)
+3. Request Deduplication is turned off (`redisGetDeduplication: false`)
+
+In practice, most deployments run multiple application instances, which introduces eventual consistency through two mechanisms:
+
+#### Source 1: SyncedMap Pub/Sub propagation (both handlers)
+
+Both `RedisStringsHandler` and `CacheComponentsHandler` maintain in-memory maps (`sharedTagsMap`, `revalidatedTagsMap`) that are synchronized across instances via Redis Pub/Sub (see [SyncedMap in ARCHITECTURE.md](./ARCHITECTURE.md#syncedmap--the-synchronization-primitive)). When a tag is revalidated on instance 1, the Pub/Sub message must propagate to instance 2 before its local maps reflect the change. Until the message arrives, `get()` on instance 2 may still consider a cache entry valid.
+
+This is especially relevant for **implicit tags** (`_N_T_` prefix): when `revalidatePath("/products")` is called, the handler records a timestamp in `revalidatedTagsMap` and lazily invalidates nested fetch entries on the next `get()`. If another instance hasn't received the Pub/Sub update yet, it can serve a stale fetch result.
 
-If using Request Deduplication, the strong consistency is not guaranteed anymore. The following sequence can happen with request deduplication:
+The propagation delay is typically in the order of a few milliseconds (Redis Pub/Sub round-trip).
+
+#### Source 2: Request Deduplication (both handlers)
+
+Both `RedisStringsHandler` and `CacheComponentsHandler` use `DeduplicatedRequestHandler` (enabled by default via `redisGetDeduplication: true`). It caches Redis GET results in memory for `inMemoryCachingTime` (default 10s). The following sequence can occur across instances:
+
+```
 Instance 1: call set A 1
 Instance 1: served set A 1
-Instance 2: call get A
-Instance 1: call delete A
-Instance 2: call get A
-Instance 2: served get A -> 1
-Instance 2: served get A -> 1 (served 1 but should already be deleted)
+Instance 2: call get A           → result cached in dedup cache
+Instance 1: call delete A        → revalidateTag deletes from Redis + publishes Pub/Sub delete
+Instance 2: call get A           → served from dedup cache (stale!) if Pub/Sub delete hasn't arrived
+Instance 2: served get A → 1     (should already be deleted)
 Instance 1: served delete A
+```
+
+When `revalidateTag` / `updateTags` runs, it also deletes the affected keys from the `inMemoryDeduplicationCache` and broadcasts this deletion via Pub/Sub. So the consistency window is bounded by the Pub/Sub propagation time (typically 5–100ms), not the full `inMemoryCachingTime`. Only if the Pub/Sub message is lost would the stale entry persist for the full caching duration.
 
-The time window for this eventual consistency to occur is typically around the length of a single redis command. Depending on your load ranging from 5ms to max 100ms.
-If using local in-memory caching (Enabled by RedisStringsHandler option inMemoryCachingTime), the window for this eventual consistency to occur can be even higher because additionally also synchronization messages have to get delivered. Depending on your load typically ranging around 50ms to max of 120ms.
+#### Practical impact
 
-Since all caching calls in one api/page/server action request is always served by the same instance this problem will not occur inside a single request but rather in a combination of multiple parallel requests. The probability that this will occur for a single user during a request sequence is very low, since typically a single user will not make the follow up request during this small time window of typically 50ms. To further mitigate the Problem and increase performance (increase local in-memory cache hit ratio) make sure that your load balancer will always serve one user to the same instance (sticky sessions).
+Since all caching calls within one API/page/server action request are always served by the same instance, this problem will not occur inside a single request but rather in a combination of multiple parallel requests across instances. The probability that this will affect a single user during a request sequence is very low, since typically a single user will not make a follow-up request during this small time window of typically <100ms. To further mitigate the problem and increase performance (increase local in-memory cache hit ratio) make sure that your load balancer will always serve one user to the same instance (sticky sessions).
 
 By accepting and tolerating this eventual consistency, the performance of the caching handler is significantly increased.
 
@@ -235,9 +405,9 @@ pnpm test:integration:build-id-prefix
 
 Folder layout / runners:
 
-- **Vitest** (unit + integration) lives in `src/**/*.test.ts(x)` and `test/**`.
-- **Playwright** (E2E) lives in `tests/**` (see `playwright.config.ts`).
-- `test/browser/**` contains Vitest tests that hit a running Next.js app over HTTP. Despite the folder name, this is not Playwright and does not use Vitest browser mode.
+- **Vitest** unit tests live in `test/vitest/unit/**`; integration tests in `test/vitest/integration/**`.
+- **Playwright** (E2E) lives in `test/playwright/**` (see `playwright.config.ts`).
+- **Test fixtures** (Next.js apps) live in `test/nextjs-test-projects/`.
 
 ### Unit tests
 
@@ -261,14 +431,6 @@ To run the BUILD_ID integration test independently:
 pnpm build && pnpm test:integration:build-id-prefix
 ```
 
-### E2E tests (Playwright)
-
-To run Playwright tests (`tests/**`) you can use:
-
-```bash
-pnpm test:e2e
-```
-
 The integration tests will start a Next.js server and test the caching handler. You can modify testing behavior by setting the following environment variables:
 
 - SKIP_BUILD: If set to true, the integration tests will not build the Next.js app. Therefore the nextjs app needs to be built before running the tests. Or you execute the test once without skip build and the re-execute `pnpm test:integration` with skip build set to true.
@@ -277,6 +439,14 @@ The integration tests will start a Next.js server and test the caching handler.
 
 Integration tests may have dependencies between test cases, so individual test failures should be evaluated in the context of the full test suite rather than in isolation.
 
+### E2E tests (Playwright)
+
+To run Playwright tests (`test/playwright/**`) you can use:
+
+```bash
+pnpm test:e2e
+```
+
 ## Cache Components handler (Next.js 16+)
 
 This package can be used as a Cache Components handler (Node.js runtime) for Next.js apps that enable Cache Components.
@@ -340,8 +510,8 @@ This repo includes a dedicated Next.js Cache Components integration app with rea
 1. Install + start the Cache Components test app:
 
 ```bash
-pnpm -C test/integration/next-app-16-2-3-cache-components install
-pnpm -C test/integration/next-app-16-2-3-cache-components dev
+pnpm -C test/nextjs-test-projects/next-app-16-2-6-cache-components install
+pnpm -C test/nextjs-test-projects/next-app-16-2-6-cache-components dev
 ```
 
 Then open the Cache Lab pages:
@@ -369,6 +539,8 @@ app/<segment>/page.tsx files will request using the APP_PAGE kind.
 
 Fetch requests (inside app route or page) will request using the FETCH kind.
 
+For details on how these kinds are handled internally (tag maps, deduplication, value transformation), see [ARCHITECTURE.md](./ARCHITECTURE.md).
+
 ## License
 
 This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

package/dist/index.d.mts

@@ -1,5 +1,55 @@
 import { RedisClientOptions } from 'redis';
 
+/**
+ * Pluggable wire-format codec for Redis string values used by `RedisStringsHandler`.
+ *
+ * The serializer is the single point at which an in-memory `CacheEntry` becomes the
+ * string written to Redis (and back). Plugging in a custom serializer lets you add
+ * compression (gzip/brotli), encryption, or any other custom encoding without forking
+ * this package or losing the existing dedup / batch / keyspace features.
+ *
+ * Both `serialize` and `deserialize` may return either a value directly or a `Promise`,
+ * which enables non-blocking async codecs such as stream-based compression
+ * (`zlib.brotliCompress`) or encryption (`crypto.subtle`). Synchronous implementations
+ * continue to work unchanged - awaiting a plain value is a no-op.
+ *
+ * The default export {@link jsonCacheValueSerializer} is `JSON.stringify` /
+ * `JSON.parse` paired with {@link bufferAndMapReplacer} / {@link bufferAndMapReviver},
+ * so native `Buffer` and `Map` values inside a `CacheEntry` round-trip transparently
+ * (this is required for Next.js RSC payloads).
+ *
+ * Operational note: changing the serializer (or any of its parameters such as a
+ * compression level or encryption key) makes existing Redis keys unreadable, because
+ * the deserializer will fail or return `null` for entries written by the previous
+ * format. Either flush the affected keys, bump `keyPrefix`, or migrate values
+ * out-of-band before deploying a new serializer.
+ */
+
+type CacheValueSerializer = {
+    /**
+     * Encode an in-memory `CacheEntry` into the string written to Redis.
+     * May return a `Promise` for async codecs (e.g. compression, encryption).
+     */
+    serialize(value: CacheEntry): string | Promise<string>;
+    /**
+     * Decode a string read from Redis back into a `CacheEntry`.
+     * Returning `null` (or a `Promise<null>`) signals "treat as cache miss" -
+     * the handler will return `null` from `get()` without surfacing an error.
+     * May return a `Promise` for async codecs.
+     */
+    deserialize(stored: string): CacheEntry | null | Promise<CacheEntry | null>;
+};
+/**
+ * Default serializer used by `RedisStringsHandler` when no `valueSerializer` is
+ * configured. Wraps `JSON.stringify` / `JSON.parse` with this package's
+ * {@link bufferAndMapReplacer} / {@link bufferAndMapReviver} so native `Buffer`
+ * and `Map` values inside a `CacheEntry` survive the round-trip.
+ *
+ * Exported as a singleton so consumers can compare against the default by
+ * reference (e.g. to detect that no custom serializer was configured).
+ */
+declare const jsonCacheValueSerializer: CacheValueSerializer;
+
 type CacheEntry = {
     value: unknown;
     lastModified: number;
@@ -66,6 +116,27 @@ type CreateRedisStringsHandlerOptions = {
      * @example { username: 'user', password: 'pass' }
      */
     clientOptions?: Omit<RedisClientOptions, 'url' | 'database' | 'socket'>;
+    /** Pluggable wire-format codec for Redis string values. Lets you plug in
+     * compression (gzip/brotli), encryption, or any other custom encoding without
+     * forking this package or losing the existing dedup / batch / keyspace features.
+     *
+     * Both `serialize` and `deserialize` may return a `Promise`, enabling
+     * non-blocking async codecs (e.g. `zlib.brotliCompress`) that don't block the
+     * Node.js event loop. Synchronous implementations continue to work unchanged.
+     *
+     * Only the main cache-entry storage path is routed through the serializer.
+     * The shared-tags map and the revalidated-tags map are not. The in-memory
+     * deduplication cache stores the wire-format string verbatim - its contents
+     * change with the serializer, but the cache itself is not re-encoded.
+     *
+     * Operational note: changing the serializer (or any of its parameters such as
+     * a compression level or encryption key) makes existing Redis keys unreadable.
+     * Either flush the affected keys or bump `keyPrefix` before deploying.
+     *
+     * @default jsonCacheValueSerializer (JSON.stringify with bufferAndMapReplacer
+     * so native Buffer and Map values inside a CacheEntry round-trip transparently)
+     */
+    valueSerializer?: CacheValueSerializer;
 };
 declare class RedisStringsHandler {
     private client;
@@ -82,7 +153,8 @@ declare class RedisStringsHandler {
     private defaultStaleAge;
     private estimateExpireAge;
     private killContainerOnErrorThreshold;
-    constructor({ redisUrl, database, keyPrefix, sharedTagsKey, getTimeoutMs, revalidateTagQuerySize, avgResyncIntervalMs, redisGetDeduplication, inMemoryCachingTime, defaultStaleAge, estimateExpireAge, killContainerOnErrorThreshold, socketOptions, clientOptions, }: CreateRedisStringsHandlerOptions);
+    private valueSerializer;
+    constructor({ redisUrl, database, keyPrefix, sharedTagsKey, getTimeoutMs, revalidateTagQuerySize, avgResyncIntervalMs, redisGetDeduplication, inMemoryCachingTime, defaultStaleAge, estimateExpireAge, killContainerOnErrorThreshold, socketOptions, clientOptions, valueSerializer, }: CreateRedisStringsHandlerOptions);
     resetRequestCache(): void;
     private clientReadyCalls;
     private assertClientIsReady;
@@ -152,6 +224,9 @@ declare class CachedHandler {
     resetRequestCache(...args: Parameters<RedisStringsHandler['resetRequestCache']>): ReturnType<RedisStringsHandler['resetRequestCache']>;
 }
 
+declare function bufferAndMapReviver(_: string, value: any): any;
+declare function bufferAndMapReplacer(_: string, value: any): any;
+
 interface CacheComponentsEntry {
     value: ReadableStream<Uint8Array>;
     tags: string[];
@@ -175,4 +250,4 @@ type CreateCacheComponentsHandlerOptions = CreateRedisStringsHandlerOptions & {
 declare function getRedisCacheComponentsHandler(options?: CreateCacheComponentsHandlerOptions): CacheComponentsHandler;
 declare const redisCacheHandler: CacheComponentsHandler;
 
-export { type CreateRedisStringsHandlerOptions, RedisStringsHandler, CachedHandler as default, getRedisCacheComponentsHandler, redisCacheHandler };
+export { type CacheValueSerializer, type CreateRedisStringsHandlerOptions, RedisStringsHandler, bufferAndMapReplacer, bufferAndMapReviver, CachedHandler as default, getRedisCacheComponentsHandler, jsonCacheValueSerializer, redisCacheHandler };

package/dist/index.d.ts

@@ -1,5 +1,55 @@
 import { RedisClientOptions } from 'redis';
 
+/**
+ * Pluggable wire-format codec for Redis string values used by `RedisStringsHandler`.
+ *
+ * The serializer is the single point at which an in-memory `CacheEntry` becomes the
+ * string written to Redis (and back). Plugging in a custom serializer lets you add
+ * compression (gzip/brotli), encryption, or any other custom encoding without forking
+ * this package or losing the existing dedup / batch / keyspace features.
+ *
+ * Both `serialize` and `deserialize` may return either a value directly or a `Promise`,
+ * which enables non-blocking async codecs such as stream-based compression
+ * (`zlib.brotliCompress`) or encryption (`crypto.subtle`). Synchronous implementations
+ * continue to work unchanged - awaiting a plain value is a no-op.
+ *
+ * The default export {@link jsonCacheValueSerializer} is `JSON.stringify` /
+ * `JSON.parse` paired with {@link bufferAndMapReplacer} / {@link bufferAndMapReviver},
+ * so native `Buffer` and `Map` values inside a `CacheEntry` round-trip transparently
+ * (this is required for Next.js RSC payloads).
+ *
+ * Operational note: changing the serializer (or any of its parameters such as a
+ * compression level or encryption key) makes existing Redis keys unreadable, because
+ * the deserializer will fail or return `null` for entries written by the previous
+ * format. Either flush the affected keys, bump `keyPrefix`, or migrate values
+ * out-of-band before deploying a new serializer.
+ */
+
+type CacheValueSerializer = {
+    /**
+     * Encode an in-memory `CacheEntry` into the string written to Redis.
+     * May return a `Promise` for async codecs (e.g. compression, encryption).
+     */
+    serialize(value: CacheEntry): string | Promise<string>;
+    /**
+     * Decode a string read from Redis back into a `CacheEntry`.
+     * Returning `null` (or a `Promise<null>`) signals "treat as cache miss" -
+     * the handler will return `null` from `get()` without surfacing an error.
+     * May return a `Promise` for async codecs.
+     */
+    deserialize(stored: string): CacheEntry | null | Promise<CacheEntry | null>;
+};
+/**
+ * Default serializer used by `RedisStringsHandler` when no `valueSerializer` is
+ * configured. Wraps `JSON.stringify` / `JSON.parse` with this package's
+ * {@link bufferAndMapReplacer} / {@link bufferAndMapReviver} so native `Buffer`
+ * and `Map` values inside a `CacheEntry` survive the round-trip.
+ *
+ * Exported as a singleton so consumers can compare against the default by
+ * reference (e.g. to detect that no custom serializer was configured).
+ */
+declare const jsonCacheValueSerializer: CacheValueSerializer;
+
 type CacheEntry = {
     value: unknown;
     lastModified: number;
@@ -66,6 +116,27 @@ type CreateRedisStringsHandlerOptions = {
      * @example { username: 'user', password: 'pass' }
      */
     clientOptions?: Omit<RedisClientOptions, 'url' | 'database' | 'socket'>;
+    /** Pluggable wire-format codec for Redis string values. Lets you plug in
+     * compression (gzip/brotli), encryption, or any other custom encoding without
+     * forking this package or losing the existing dedup / batch / keyspace features.
+     *
+     * Both `serialize` and `deserialize` may return a `Promise`, enabling
+     * non-blocking async codecs (e.g. `zlib.brotliCompress`) that don't block the
+     * Node.js event loop. Synchronous implementations continue to work unchanged.
+     *
+     * Only the main cache-entry storage path is routed through the serializer.
+     * The shared-tags map and the revalidated-tags map are not. The in-memory
+     * deduplication cache stores the wire-format string verbatim - its contents
+     * change with the serializer, but the cache itself is not re-encoded.
+     *
+     * Operational note: changing the serializer (or any of its parameters such as
+     * a compression level or encryption key) makes existing Redis keys unreadable.
+     * Either flush the affected keys or bump `keyPrefix` before deploying.
+     *
+     * @default jsonCacheValueSerializer (JSON.stringify with bufferAndMapReplacer
+     * so native Buffer and Map values inside a CacheEntry round-trip transparently)
+     */
+    valueSerializer?: CacheValueSerializer;
 };
 declare class RedisStringsHandler {
     private client;
@@ -82,7 +153,8 @@ declare class RedisStringsHandler {
     private defaultStaleAge;
     private estimateExpireAge;
     private killContainerOnErrorThreshold;
-    constructor({ redisUrl, database, keyPrefix, sharedTagsKey, getTimeoutMs, revalidateTagQuerySize, avgResyncIntervalMs, redisGetDeduplication, inMemoryCachingTime, defaultStaleAge, estimateExpireAge, killContainerOnErrorThreshold, socketOptions, clientOptions, }: CreateRedisStringsHandlerOptions);
+    private valueSerializer;
+    constructor({ redisUrl, database, keyPrefix, sharedTagsKey, getTimeoutMs, revalidateTagQuerySize, avgResyncIntervalMs, redisGetDeduplication, inMemoryCachingTime, defaultStaleAge, estimateExpireAge, killContainerOnErrorThreshold, socketOptions, clientOptions, valueSerializer, }: CreateRedisStringsHandlerOptions);
     resetRequestCache(): void;
     private clientReadyCalls;
     private assertClientIsReady;
@@ -152,6 +224,9 @@ declare class CachedHandler {
     resetRequestCache(...args: Parameters<RedisStringsHandler['resetRequestCache']>): ReturnType<RedisStringsHandler['resetRequestCache']>;
 }
 
+declare function bufferAndMapReviver(_: string, value: any): any;
+declare function bufferAndMapReplacer(_: string, value: any): any;
+
 interface CacheComponentsEntry {
     value: ReadableStream<Uint8Array>;
     tags: string[];
@@ -175,4 +250,4 @@ type CreateCacheComponentsHandlerOptions = CreateRedisStringsHandlerOptions & {
 declare function getRedisCacheComponentsHandler(options?: CreateCacheComponentsHandlerOptions): CacheComponentsHandler;
 declare const redisCacheHandler: CacheComponentsHandler;
 
-export { type CreateRedisStringsHandlerOptions, RedisStringsHandler, CachedHandler as default, getRedisCacheComponentsHandler, redisCacheHandler };
+export { type CacheValueSerializer, type CreateRedisStringsHandlerOptions, RedisStringsHandler, bufferAndMapReplacer, bufferAndMapReviver, CachedHandler as default, getRedisCacheComponentsHandler, jsonCacheValueSerializer, redisCacheHandler };