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

package/package.json

@@ -1,30 +1,29 @@
 {
   "name": "@trieb.work/nextjs-turbo-redis-cache",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "homepage": "https://trwk.de/case-studies/nextjs-turbo-redis-cache",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/trieb-work/nextjs-turbo-redis-cache.git"
   },
   "scripts": {
-    "dev": "pnpm test",
-    "run-dev-server": "pnpm run-dev-server-15-4-7",
-    "run-dev-server-15-3-2": "cd ./test/integration/next-app-15-3-2 && pnpm dev",
-    "run-dev-server-15-0-3": "cd ./test/integration/next-app-15-0-3 && pnpm dev",
-    "run-dev-server-15-4-7": "cd ./test/integration/next-app-15-4-7 && pnpm dev",
+    "dev": "pnpm test:unit",
     "build": "tsup",
     "lint": "eslint -c eslint.config.mjs --fix",
     "format": "prettier --write 'src/**/*.ts' 'src/*.ts'",
-    "test": "vitest --coverage --config vite.config.ts",
-    "test:ci": "vitest --run --coverage --config vite.config.ts src/**/*.test.ts src/**/*.test.tsx test/integration/nextjs-cache-handler.integration.test.ts",
-    "test:integration:build-id-prefix": "vitest --run --coverage --config vite.config.ts test/integration/build-id-prefix.integration.test.ts",
-    "test:ui": "vitest --ui  --config vite.config.ts",
-    "test:unit": "vitest --config vite.config.ts src/**/*.test.ts src/**/*.test.tsx",
-    "test:integration": "vitest --config vite.config.ts ./test/integration/nextjs-cache-handler.integration.test.ts",
-    "test:cache-components": "vitest --run --config vitest.cache-components.config.ts",
     "prepare": "./scripts/prepare.sh",
-    "test:browser": "vitest --config=vitest.browser.config.ts",
-    "test:e2e": "playwright test"
+    "test": "vitest --coverage --config vite.config.ts",
+    "test:ui": "vitest --ui --config vite.config.ts",
+    "test:unit": "vitest --run --config vite.config.ts test/vitest/unit",
+    "test:unit:watch": "vitest --config vite.config.ts test/vitest/unit",
+    "test:unit:coverage": "vitest --run --coverage --config vite.config.ts test/vitest/unit",
+    "test:integration": "vitest --run --config vite.config.ts test/vitest/integration/nextjs-cache-handler.integration.test.ts",
+    "test:integration:build-id-prefix": "vitest --run --config vite.config.ts test/vitest/integration/build-id-prefix.integration.test.ts",
+    "test:integration:pages": "vitest --run --config vite.config.ts test/vitest/integration/pages-router.integration.test.ts",
+    "test:integration:cache-components": "vitest --run --config vitest.cache-components.config.ts",
+    "test:e2e": "playwright test",
+    "run-dev-server": "pnpm run-dev-server-15-4-11",
+    "run-dev-server-15-4-11": "cd ./test/nextjs-test-projects/next-app-15-4-11 && pnpm dev"
   },
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -78,7 +77,7 @@
   "devDependencies": {
     "@commitlint/cli": "^19.6.0",
     "@commitlint/config-conventional": "^19.6.0",
-    "@playwright/test": "^1.56.1",
+    "@playwright/test": "^1.62.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^12.0.2",

package/playwright.config.ts

@@ -1,14 +1,16 @@
 import { defineConfig } from '@playwright/test';
 
+const testApp =
+  process.env.PLAYWRIGHT_TEST_APP || 'next-app-16-2-6-cache-components';
+
 export default defineConfig({
-  testDir: 'tests',
+  testDir: 'test/playwright',
   use: {
     baseURL: process.env.PLAYWRIGHT_BASE_URL || 'http://localhost:3101',
     trace: 'on-first-retry',
   },
   webServer: {
-    command:
-      'pnpm -C test/integration/next-app-16-2-3-cache-components dev -p 3101',
+    command: `pnpm -C test/nextjs-test-projects/${testApp} dev -p 3101`,
     url: 'http://localhost:3101',
     reuseExistingServer: true,
     timeout: 120_000,

package/src/CacheComponentsHandler.ts

@@ -6,6 +6,7 @@ import {
   redisErrorHandler,
 } from './RedisStringsHandler';
 import { SyncedMap } from './SyncedMap';
+import { DeduplicatedRequestHandler } from './DeduplicatedRequestHandler';
 import { debug } from './utils/debug';
 import { resolveKeyPrefix } from './utils/prefix';
 
@@ -87,8 +88,19 @@ class RedisCacheComponentsHandler implements CacheComponentsHandler {
   private client: Client;
   private revalidatedTagsMap: SyncedMap<number>;
   private sharedTagsMap: SyncedMap<string[]>;
+  private inMemoryDeduplicationCache: SyncedMap<
+    Promise<ReturnType<Client['get']>>
+  >;
   private keyPrefix: string;
   private getTimeoutMs: number;
+  private redisGet: Client['get'];
+  private redisDeduplicationHandler: DeduplicatedRequestHandler<
+    Client['get'],
+    string | Buffer | null
+  >;
+  private deduplicatedRedisGet: (key: string) => Client['get'];
+  private redisGetDeduplication: boolean;
+  private inMemoryCachingTime: number;
 
   constructor({
     redisUrl = process.env.REDIS_URL
@@ -103,6 +115,8 @@ class RedisCacheComponentsHandler implements CacheComponentsHandler {
       : 500,
     revalidateTagQuerySize = 250,
     avgResyncIntervalMs = 60 * 60 * 1_000,
+    redisGetDeduplication = true,
+    inMemoryCachingTime = 10_000,
     socketOptions,
     clientOptions,
     killContainerOnErrorThreshold = process.env
@@ -118,6 +132,8 @@ class RedisCacheComponentsHandler implements CacheComponentsHandler {
         env: process.env,
       });
       this.getTimeoutMs = getTimeoutMs;
+      this.redisGetDeduplication = redisGetDeduplication;
+      this.inMemoryCachingTime = inMemoryCachingTime;
 
       this.client = createClient({
         url: redisUrl,
@@ -208,6 +224,29 @@ class RedisCacheComponentsHandler implements CacheComponentsHandler {
           avgResyncIntervalMs / 10 +
           Math.random() * (avgResyncIntervalMs / 10),
       });
+
+      this.inMemoryDeduplicationCache = new SyncedMap({
+        client: this.client,
+        keyPrefix: this.keyPrefix,
+        redisKey: '__cacheComponents_inMemoryDeduplicationCache__',
+        database,
+        querySize: revalidateTagQuerySize,
+        filterKeys,
+        customizedSync: {
+          withoutRedisHashmap: true,
+          withoutSetSync: true,
+        },
+      });
+
+      const redisGet: Client['get'] = this.client.get.bind(this.client);
+      this.redisDeduplicationHandler = new DeduplicatedRequestHandler(
+        redisGet,
+        inMemoryCachingTime,
+        this.inMemoryDeduplicationCache,
+      );
+      this.redisGet = redisGet;
+      this.deduplicatedRedisGet =
+        this.redisDeduplicationHandler.deduplicatedFunction;
     } catch (error) {
       console.error('RedisCacheComponentsHandler constructor error', error);
       throw error;
@@ -253,12 +292,18 @@ class RedisCacheComponentsHandler implements CacheComponentsHandler {
     try {
       await this.assertClientIsReady();
 
+      const clientGet = this.redisGetDeduplication
+        ? this.deduplicatedRedisGet(cacheKey)
+        : this.redisGet;
+
       const serialized = await redisErrorHandler(
-        'RedisCacheComponentsHandler.get(), operation: get ' +
+        'RedisCacheComponentsHandler.get(), operation: get' +
+          (this.redisGetDeduplication ? ' deduplicated' : '') +
+          ' ' +
           this.getTimeoutMs +
           'ms ' +
           redisKey,
-        this.client.get(
+        clientGet(
           commandOptions({ signal: AbortSignal.timeout(this.getTimeoutMs) }),
           redisKey,
         ),
@@ -355,6 +400,10 @@ class RedisCacheComponentsHandler implements CacheComponentsHandler {
         throw jsonError;
       }
 
+      if (this.redisGetDeduplication) {
+        this.redisDeduplicationHandler.seedRequestReturn(cacheKey, serialized);
+      }
+
       // expire is already a duration in seconds, use it directly
       const ttlSeconds =
         Number.isFinite(stored.expire) && stored.expire > 0
@@ -450,6 +499,12 @@ class RedisCacheComponentsHandler implements CacheComponentsHandler {
         this.client.unlink(fullRedisKeys),
       );
 
+      if (this.redisGetDeduplication && this.inMemoryCachingTime > 0) {
+        for (const key of keysToDelete) {
+          this.inMemoryDeduplicationCache.delete(key);
+        }
+      }
+
       // Delete from sharedTagsMap
       const deleteTagsOperation = this.sharedTagsMap.delete(cacheKeys);
       await deleteTagsOperation;

package/src/RedisStringsHandler.ts

@@ -13,6 +13,84 @@ export type CacheEntry = {
   tags: string[];
 };
 
+/** Discriminated union of the `ctx` argument Next.js passes to
+ * {@link RedisStringsHandler.get}. The Pages Router (`PAGES`) has no PPR
+ * concept, so `isRoutePPREnabled` is optional for it.
+ *
+ * Note: `REDIRECT` is intentionally absent. Next.js always calls `get()` with
+ * `kind: 'PAGES'` for Pages Router routes, even when the stored value has
+ * `kind: 'REDIRECT'`. The handler returns whatever value is cached and Next.js
+ * interprets it accordingly. */
+export type GetContext =
+  | {
+      kind: 'APP_ROUTE' | 'APP_PAGE';
+      isRoutePPREnabled: boolean;
+      isFallback: boolean;
+    }
+  | {
+      kind: 'PAGES';
+      isRoutePPREnabled?: boolean;
+      isFallback: boolean;
+    }
+  | {
+      kind: 'FETCH';
+      revalidate: number;
+      fetchUrl: string;
+      fetchIdx: number;
+      tags: string[];
+      softTags: string[];
+      isFallback: boolean;
+    };
+
+/** Discriminated union of cache payloads accepted by
+ * {@link RedisStringsHandler.set}. `null` is a valid payload: the Pages Router
+ * stores `notFound: true` results as a cache entry with a null value. */
+export type SetCacheValue =
+  | {
+      kind: 'APP_PAGE';
+      status?: number;
+      headers: {
+        'x-nextjs-stale-time': string; // timestamp in ms
+        'x-next-cache-tags': string; // comma separated paths (tags)
+      };
+      html: string;
+      rscData: Buffer;
+      segmentData: unknown;
+      postboned: unknown;
+    }
+  | {
+      kind: 'APP_ROUTE';
+      status: number;
+      headers: {
+        'cache-control'?: string;
+        'x-nextjs-stale-time': string; // timestamp in ms
+        'x-next-cache-tags': string; // comma separated paths (tags)
+      };
+      body: Buffer;
+    }
+  | {
+      kind: 'PAGES';
+      html: string;
+      pageData: Record<string, unknown>;
+      headers?: Record<string, number | string | string[] | undefined>;
+      status?: number;
+    }
+  | {
+      kind: 'REDIRECT';
+      props: Record<string, unknown>;
+    }
+  | {
+      kind: 'FETCH';
+      data: {
+        headers: Record<string, string>;
+        body: string; // base64 encoded
+        status: number;
+        url: string;
+      };
+      revalidate: number | false;
+    }
+  | null;
+
 export function redisErrorHandler<T extends Promise<unknown>>(
   debugInfo: string,
   redisCommandResult: T,
@@ -144,6 +222,24 @@ const NEXT_CACHE_IMPLICIT_TAG_ID = '_N_T_';
 // This helps track when specific tags were last invalidated
 const REVALIDATED_TAGS_KEY = '__revalidated_tags__';
 
+// Cache kinds this handler is designed and tested for. Kept as the single
+// source of truth for both payload validation and the warning message, so
+// adding a kind is a one-line change here instead of edits scattered across
+// the type union, the guard chain, and the log string.
+const SUPPORTED_GET_KINDS = [
+  'APP_ROUTE',
+  'APP_PAGE',
+  'PAGES',
+  'FETCH',
+] as const;
+const SUPPORTED_SET_KINDS = [
+  'APP_ROUTE',
+  'APP_PAGE',
+  'PAGES',
+  'REDIRECT',
+  'FETCH',
+] as const;
+
 let killContainerOnErrorCount: number = 0;
 export default class RedisStringsHandler {
   private client: Client;
@@ -371,35 +467,14 @@ export default class RedisStringsHandler {
     }
   }
 
-  public async get(
-    key: string,
-    ctx:
-      | {
-          kind: 'APP_ROUTE' | 'APP_PAGE';
-          isRoutePPREnabled: boolean;
-          isFallback: boolean;
-        }
-      | {
-          kind: 'FETCH';
-          revalidate: number;
-          fetchUrl: string;
-          fetchIdx: number;
-          tags: string[];
-          softTags: string[];
-          isFallback: boolean;
-        },
-  ): Promise<CacheEntry | null> {
+  public async get(key: string, ctx: GetContext): Promise<CacheEntry | null> {
     try {
-      if (
-        ctx.kind !== 'APP_ROUTE' &&
-        ctx.kind !== 'APP_PAGE' &&
-        ctx.kind !== 'FETCH'
-      ) {
+      if (!(SUPPORTED_GET_KINDS as readonly string[]).includes(ctx.kind)) {
         console.warn(
           'RedisStringsHandler.get() called with',
           key,
           ctx,
-          ' this cache handler is only designed and tested for kind APP_ROUTE and APP_PAGE and not for kind ',
+          `this cache handler is only designed and tested for kinds ${SUPPORTED_GET_KINDS.join(', ')} and not for kind`,
           (ctx as { kind: string })?.kind,
         );
       }
@@ -479,7 +554,10 @@ export default class RedisStringsHandler {
           'cacheEntry is mall formed (missing tags)',
         );
       }
-      if (!cacheEntry?.value) {
+      // value === null is a legitimate entry: the Pages Router stores
+      // `notFound: true` results as a cache entry with a null value.
+      // Only an absent value indicates a malformed entry.
+      if (cacheEntry?.value === undefined) {
         console.warn(
           'RedisStringsHandler.get() called with',
           key,
@@ -589,71 +667,49 @@ export default class RedisStringsHandler {
   }
   public async set(
     key: string,
-    data:
-      | {
-          kind: 'APP_PAGE';
-          status?: number;
-          headers: {
-            'x-nextjs-stale-time': string; // timestamp in ms
-            'x-next-cache-tags': string; // comma separated paths (tags)
-          };
-          html: string;
-          rscData: Buffer;
-          segmentData: unknown;
-          postboned: unknown;
-        }
-      | {
-          kind: 'APP_ROUTE';
-          status: number;
-          headers: {
-            'cache-control'?: string;
-            'x-nextjs-stale-time': string; // timestamp in ms
-            'x-next-cache-tags': string; // comma separated paths (tags)
-          };
-          body: Buffer;
-        }
-      | {
-          kind: 'FETCH';
-          data: {
-            headers: Record<string, string>;
-            body: string; // base64 encoded
-            status: number;
-            url: string;
-          };
-          revalidate: number | false;
-        },
+    data: SetCacheValue,
     ctx: {
       isRoutePPREnabled: boolean;
       isFallback: boolean;
       tags?: string[];
       // Different versions of Next.js use different arguments for the same functionality
       revalidate?: number | false; // Version 15.0.3
-      cacheControl?: { revalidate: 5; expire: undefined }; // Version 15.0.3
+      cacheControl?: { revalidate: number | false; expire: number | undefined }; // Version 15.0.3+
     },
   ) {
     try {
       if (
-        data.kind !== 'APP_ROUTE' &&
-        data.kind !== 'APP_PAGE' &&
-        data.kind !== 'FETCH'
+        data !== null &&
+        !(SUPPORTED_SET_KINDS as readonly string[]).includes(data.kind)
       ) {
         console.warn(
           'RedisStringsHandler.set() called with',
           key,
           ctx,
           data,
-          ' this cache handler is only designed and tested for kind APP_ROUTE and APP_PAGE and not for kind ',
+          `this cache handler is only designed and tested for kinds ${SUPPORTED_SET_KINDS.join(', ')} and not for kind`,
           (data as { kind: string })?.kind,
         );
       }
 
       await this.assertClientIsReady();
 
-      if (data.kind === 'APP_PAGE' || data.kind === 'APP_ROUTE') {
+      if (data?.kind === 'APP_PAGE' || data?.kind === 'APP_ROUTE') {
         const tags = data.headers['x-next-cache-tags']?.split(',');
         ctx.tags = [...(ctx.tags || []), ...(tags || [])];
       }
 
+      // Pages Router entries (PAGES, REDIRECT and null/notFound results) do not
+      // carry an x-next-cache-tags header. Attach the implicit path tag
+      // (_N_T_/<path>) so that revalidatePath()/revalidateTag('_N_T_/<path>')
+      // invalidates them the same way as App Router entries.
+      if (data === null || data.kind === 'PAGES' || data.kind === 'REDIRECT') {
+        const implicitTag = NEXT_CACHE_IMPLICIT_TAG_ID + key;
+        if (!ctx.tags?.includes(implicitTag)) {
+          ctx.tags = [...(ctx.tags || []), implicitTag];
+        }
+      }
+
       // Constructing and serializing the value for storing it in redis
       const cacheEntry: CacheEntry = {
         lastModified: Date.now(),
@@ -676,10 +732,13 @@ export default class RedisStringsHandler {
       // Constructing the expire time for the cache entry
       const revalidate =
         // For fetch requests in newest versions, the revalidate context property is never used, and instead the revalidate property of the passed-in data is used
-        (data.kind === 'FETCH' && data.revalidate) ||
+        (data?.kind === 'FETCH' && data.revalidate) ||
         ctx.revalidate ||
         ctx.cacheControl?.revalidate ||
-        (data as { revalidate?: number | false })?.revalidate;
+        // Legacy fallback: older Next.js versions attached `revalidate` directly
+        // to the data payload. FETCH is already handled above, so this only
+        // matters for those older, non-discriminated shapes.
+        (data as { revalidate?: number | false } | null)?.revalidate;
       const expireAt =
         revalidate && Number.isSafeInteger(revalidate) && revalidate > 0
           ? this.estimateExpireAge(revalidate)

package/src/SyncedMap.ts

@@ -41,6 +41,7 @@ export class SyncedMap<V> {
 
   private setupLock: Promise<void>;
   private setupLockResolve!: () => void;
+  private isReconnecting = false;
 
   constructor(options: SyncedMapOptions) {
     this.client = options.client;
@@ -209,6 +210,16 @@ export class SyncedMap<V> {
     };
 
     try {
+      // Attach error handler BEFORE subscribing so that errors during
+      // subscribe or after connection loss are always caught and trigger
+      // a reconnection. Previously this was attached after the subscribe()
+      // calls, which meant if subscribe threw during an outage the handler
+      // was never attached and the subscriber was permanently dead.
+      this.subscriberClient.on('error', async (err) => {
+        console.error('Subscriber client error:', err);
+        await this.reconnectSubscriber();
+      });
+
       const connectIfNeeded = async () => {
         // Avoid overlapping connect() calls which can lead to
         // "Socket already opened" errors when a connect is already in progress
@@ -241,7 +252,9 @@ export class SyncedMap<V> {
           throw new Error(
             'Keyspace event configuration is set to "' +
               keyspaceEventConfig +
-              "\" but has to include 'E' for Keyevent events, published with __keyevent@<db>__ prefix. We recommend to set it to 'Exe' like so `redis-cli -h localhost config set notify-keyspace-events Exe`",
+              " but has to include 'E' for Keyevent events, " +
+              'published with __keyevent@<db>__ prefix. We recommend to set it to ' +
+              "'Exe' like so `redis-cli -h localhost config set notify-keyspace-events Exe`",
           );
         }
         if (
@@ -254,7 +267,9 @@ export class SyncedMap<V> {
           throw new Error(
             'Keyspace event configuration is set to "' +
               keyspaceEventConfig +
-              "\" but has to include 'A' or 'x' and 'e' for expired and evicted events. We recommend to set it to 'Exe' like so `redis-cli -h localhost config set notify-keyspace-events Exe`",
+              " but has to include 'A' or 'x' and 'e' for expired and " +
+              'evicted events. We recommend to set it to ' +
+              "'Exe' like so `redis-cli -h localhost config set notify-keyspace-events Exe`",
           );
         }
       }
@@ -275,24 +290,58 @@ export class SyncedMap<V> {
           keyEventHandler,
         ),
       ]);
+    } catch (error) {
+      console.error('Error setting up pub/sub client:', error);
+      throw error;
+    }
+  }
 
-      // Error handling for reconnection
-      this.subscriberClient.on('error', async (err) => {
-        console.error('Subscriber client error:', err);
+  /**
+   * Reconnect the subscriber client with exponential backoff.
+   * Guarded by `isReconnecting` to prevent concurrent reconnection
+   * attempts when multiple error events fire during an outage.
+   * Retries indefinitely (with capped delay) so the subscriber
+   * eventually recovers once Redis is available again.
+   */
+  private async reconnectSubscriber(): Promise<void> {
+    if (this.isReconnecting) return;
+    this.isReconnecting = true;
+
+    try {
+      let attempt = 0;
+      while (true) {
         try {
-          await this.subscriberClient.quit();
+          // Forcibly tear down the old subscriber so its internal reconnect
+          // loop cannot come back to life once Redis recovers. `quit()` waits
+          // for the server and can silently fail during an outage, leaving a
+          // zombie client that still fires our error handler. Remove that
+          // handler first so a delayed error from the old socket cannot tear
+          // down the replacement subscriber we are about to create.
+          try {
+            this.subscriberClient.removeAllListeners('error');
+            await this.subscriberClient.disconnect();
+          } catch {
+            // expected during outage
+          }
+          // Create a fresh subscriber client
           this.subscriberClient = this.client.duplicate();
           await this.setupPubSub();
-        } catch (reconnectError) {
+          return; // success
+        } catch (error) {
+          const delay = Math.min(
+            500 * Math.pow(2, Math.min(attempt, 5)),
+            10_000,
+          );
+          attempt++;
           console.error(
-            'Failed to reconnect subscriber client:',
-            reconnectError,
+            `Subscriber reconnect attempt ${attempt} failed, retrying in ${delay}ms`,
+            error,
           );
+          await new Promise((r) => setTimeout(r, delay));
         }
-      });
-    } catch (error) {
-      console.error('Error setting up pub/sub client:', error);
-      throw error;
+      }
+    } finally {
+      this.isReconnecting = false;
     }
   }