@trieb.work/nextjs-turbo-redis-cache 1.14.0 → 1.15.0

package/.github/workflows/ci.yml

@@ -76,7 +76,7 @@ jobs:
         run: cd test/integration/${{ matrix.next-test-app }} && pnpm build
 
       - name: Run tests
-        run: pnpm test
+        run: pnpm test:ci
         env:
           SKIP_BUILD: true
           NEXT_TEST_APP: ${{ matrix.next-test-app }}
@@ -121,3 +121,50 @@ jobs:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} # NPM token for publishing
         run: |
           npx semantic-release --dry-run
+
+  build-id-prefix:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install pnpm
+        run: corepack enable
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --ignore-scripts
+
+      - name: Run lint
+        run: pnpm lint
+
+      - name: Build project
+        run: pnpm build
+
+      - name: Start Redis
+        uses: supercharge/redis-github-action@1.8.0
+        with:
+          redis-version: '7'
+          redis-port: 6379
+
+      - name: Install redis-cli
+        run: sudo apt-get update && sudo apt-get install -y redis-tools
+
+      - name: Configure Redis Keyspace Notifications
+        run: redis-cli config set notify-keyspace-events Exe
+
+      - name: Install Integration Test Project
+        run: cd test/integration/next-app-15-4-7 && pnpm install
+
+      - name: Build Integration Test Project
+        run: cd test/integration/next-app-15-4-7 && pnpm build
+
+      - name: Run BUILD_ID integration test
+        run: pnpm test:integration:build-id-prefix

package/.github/workflows/pages.yml

@@ -0,0 +1,38 @@
+name: Deploy GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload static site artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: docs
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [1.15.0](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.14.1...v1.15.0) (2026-05-19)
+
+
+### Bug Fixes
+
+* **serializer:** treat deserialize failures as cache misses ([a33b2c8](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/a33b2c8dd5d94686a451ed004b05a7883131f623))
+
+
+### Features
+
+* **serializer:** add pluggable valueSerializer for compression and custom encoding ([f55d0a3](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/f55d0a3ccb9f007d231826e27bca04785bcd2c50))
+
+## [1.14.1](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.14.0...v1.14.1) (2026-05-15)
+
+
+### Bug Fixes
+
+* treat Redis GET abort as cache miss ([#65](https://github.com/trieb-work/nextjs-turbo-redis-cache/issues/65)) ([52faf38](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/52faf38e267db3188a09a8495750d77c3b693ba8))
+
 # [1.14.0](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.13.0...v1.14.0) (2026-05-08)
 
 

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:
 
@@ -30,7 +30,7 @@ Tested versions are:
 - Nextjs 16.2.3 + redis client 4.7.0 (cacheComponents: false)
 - Nextjs 16.2.3 + 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.
 
@@ -153,6 +153,153 @@ A working example of above can be found in the `test/integration/next-app-custom
 | 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
 
@@ -226,6 +373,13 @@ To run all tests you can use the following command:
 pnpm build && pnpm test
 ```
 
+For CI, we use dedicated scripts:
+
+```bash
+pnpm test:ci
+pnpm test:integration:build-id-prefix
+```
+
 Folder layout / runners:
 
 - **Vitest** (unit + integration) lives in `src/**/*.test.ts(x)` and `test/**`.
@@ -248,6 +402,12 @@ To run integration tests you can use the following command:
 pnpm build && pnpm test:integration
 ```
 
+To run the BUILD_ID integration test independently:
+
+```bash
+pnpm build && pnpm test:integration:build-id-prefix
+```
+
 ### E2E tests (Playwright)
 
 To run Playwright tests (`tests/**`) you can use:

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 };

package/dist/index.js

@@ -31,8 +31,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   RedisStringsHandler: () => RedisStringsHandler,
+  bufferAndMapReplacer: () => bufferAndMapReplacer,
+  bufferAndMapReviver: () => bufferAndMapReviver,
   default: () => index_default,
   getRedisCacheComponentsHandler: () => getRedisCacheComponentsHandler,
+  jsonCacheValueSerializer: () => jsonCacheValueSerializer,
   redisCacheHandler: () => redisCacheHandler
 });
 module.exports = __toCommonJS(index_exports);
@@ -487,6 +490,16 @@ function bufferAndMapReplacer(_, value) {
   return value;
 }
 
+// src/serializer.ts
+var jsonCacheValueSerializer = {
+  serialize(value) {
+    return JSON.stringify(value, bufferAndMapReplacer);
+  },
+  deserialize(stored) {
+    return JSON.parse(stored, bufferAndMapReviver);
+  }
+};
+
 // src/RedisStringsHandler.ts
 function redisErrorHandler(debugInfo, redisCommandResult) {
   const beforeTimestamp = performance.now();
@@ -501,6 +514,11 @@ function redisErrorHandler(debugInfo, redisCommandResult) {
     throw error;
   });
 }
+function isAbortError(error) {
+  if (!error || typeof error !== "object") return false;
+  const err = error;
+  return err.name === "AbortError" || err.code === "ABORT_ERR";
+}
 if (process.env.DEBUG_CACHE_HANDLER) {
   setInterval(() => {
     const start = performance.now();
@@ -533,7 +551,8 @@ var RedisStringsHandler = class {
     estimateExpireAge = (staleAge) => process.env.VERCEL_ENV === "production" ? staleAge * 2 : staleAge * 1.2,
     killContainerOnErrorThreshold = process.env.KILL_CONTAINER_ON_ERROR_THRESHOLD ? Number.parseInt(process.env.KILL_CONTAINER_ON_ERROR_THRESHOLD) ?? 0 : 0,
     socketOptions,
-    clientOptions
+    clientOptions,
+    valueSerializer = jsonCacheValueSerializer
   }) {
     this.clientReadyCalls = 0;
     try {
@@ -544,6 +563,7 @@ var RedisStringsHandler = class {
       this.estimateExpireAge = estimateExpireAge;
       this.killContainerOnErrorThreshold = killContainerOnErrorThreshold;
       this.getTimeoutMs = getTimeoutMs;
+      this.valueSerializer = valueSerializer;
       try {
         this.client = (0, import_redis.createClient)({
           url: redisUrl,
@@ -692,12 +712,18 @@ var RedisStringsHandler = class {
       debug("green", "RedisStringsHandler.get() called with", key, ctx);
       await this.assertClientIsReady();
       const clientGet = this.redisGetDeduplication ? this.deduplicatedRedisGet(key) : this.redisGet;
+      const redisGetOperation = clientGet(
+        (0, import_redis.commandOptions)({ signal: AbortSignal.timeout(this.getTimeoutMs) }),
+        this.keyPrefix + key
+      ).catch((error) => {
+        if (isAbortError(error)) {
+          return null;
+        }
+        throw error;
+      });
       const serializedCacheEntry = await redisErrorHandler(
         "RedisStringsHandler.get(), operation: get" + (this.redisGetDeduplication ? "deduplicated" : "") + " " + this.getTimeoutMs + "ms " + this.keyPrefix + " " + key,
-        clientGet(
-          (0, import_redis.commandOptions)({ signal: AbortSignal.timeout(this.getTimeoutMs) }),
-          this.keyPrefix + key
-        )
+        redisGetOperation
       );
       debug(
         "green",
@@ -707,10 +733,17 @@ var RedisStringsHandler = class {
       if (!serializedCacheEntry) {
         return null;
       }
-      const cacheEntry = JSON.parse(
-        serializedCacheEntry,
-        bufferAndMapReviver
-      );
+      let cacheEntry;
+      try {
+        cacheEntry = await this.valueSerializer.deserialize(serializedCacheEntry);
+      } catch (err) {
+        console.warn(
+          "RedisStringsHandler.get() valueSerializer.deserialize failed, treating as cache miss",
+          this.keyPrefix + key,
+          err
+        );
+        return null;
+      }
       debug(
         "green",
         "RedisStringsHandler.get() finished with result (cacheEntry)",
@@ -820,10 +853,7 @@ var RedisStringsHandler = class {
         tags: ctx?.tags || [],
         value: data
       };
-      const serializedCacheEntry = JSON.stringify(
-        cacheEntry,
-        bufferAndMapReplacer
-      );
+      const serializedCacheEntry = await this.valueSerializer.serialize(cacheEntry);
       if (this.redisGetDeduplication) {
         this.redisDeduplicationHandler.seedRequestReturn(
           key,
@@ -1359,7 +1389,10 @@ var index_default = CachedHandler;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   RedisStringsHandler,
+  bufferAndMapReplacer,
+  bufferAndMapReviver,
   getRedisCacheComponentsHandler,
+  jsonCacheValueSerializer,
   redisCacheHandler
 });
 //# sourceMappingURL=index.js.map