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

package/src/CacheComponentsHandler.ts

@@ -530,5 +530,38 @@ export function getRedisCacheComponentsHandler(
   return singletonHandler;
 }
 
-export const redisCacheHandler: CacheComponentsHandler =
-  getRedisCacheComponentsHandler();
+// Lazily resolve the default Cache Components handler.
+//
+// Constructing a RedisCacheComponentsHandler opens a Redis connection in its
+// constructor. Building the singleton at module-eval time therefore means that simply
+// *importing this package* — e.g. only for `RedisStringsHandler` (the legacy
+// `cacheHandler`), with Cache Components never enabled — eagerly connects to Redis,
+// defaulting to `redis://localhost:6379` when neither `REDIS_URL` nor `REDISHOST` is
+// set. In a deployment whose Redis is not on localhost that yields a non-stop
+// `RedisCacheComponentsHandler client error ECONNREFUSED 127.0.0.1:6379` reconnect
+// loop, and it also makes a consumer's later `getRedisCacheComponentsHandler(options)`
+// a no-op, because the singleton was already built with defaults (see #84).
+//
+// Defer construction to first use via a Proxy: importing the package never connects, a
+// consumer that configures the handler via `getRedisCacheComponentsHandler(options)`
+// before it is first used has that configuration honored, and a consumer that never
+// touches Cache Components never opens a Redis connection at all.
+let resolvedHandler: CacheComponentsHandler | undefined;
+
+export const redisCacheHandler: CacheComponentsHandler = new Proxy(
+  {} as CacheComponentsHandler,
+  {
+    get(_target, prop) {
+      if (!resolvedHandler) {
+        resolvedHandler = getRedisCacheComponentsHandler();
+      }
+      const value = resolvedHandler[prop as keyof CacheComponentsHandler];
+      return typeof value === 'function'
+        ? (value as (...args: unknown[]) => unknown).bind(resolvedHandler)
+        : value;
+    },
+    has(_target, prop) {
+      return prop in RedisCacheComponentsHandler.prototype;
+    },
+  },
+);

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/test/README.md

@@ -28,12 +28,13 @@ test/
 
 Fast tests with no external dependencies. Mocks are used where needed.
 
-| File                                      | What it tests                                                                    |
-| ----------------------------------------- | -------------------------------------------------------------------------------- |
-| `serializer.test.ts`                      | `CacheValueSerializer` interface, JSON round-trips, singleton stability          |
-| `index.test.ts`                           | `RedisStringsHandler` constructor options, default behaviors                     |
-| `utils/prefix.test.ts`                    | `resolveKeyPrefix` logic (BUILD_ID fallback, env var precedence)                 |
-| `reconnect-socket-already-opened.test.ts` | Regression: reconnect logic doesn't call `connect()` when socket is already open |
+| File                                      | What it tests                                                                                  |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `serializer.test.ts`                      | `CacheValueSerializer` interface, JSON round-trips, singleton stability                        |
+| `index.test.ts`                           | `RedisStringsHandler` constructor options, default behaviors                                   |
+| `utils/prefix.test.ts`                    | `resolveKeyPrefix` logic (BUILD_ID fallback, env var precedence)                               |
+| `reconnect-socket-already-opened.test.ts` | Regression: reconnect logic doesn't call `connect()` when socket is already open               |
+| `pages-router-kinds.test.ts`              | Pages Router cache kinds (`PAGES`, `REDIRECT`, `null`/notFound), implicit tags, TTL derivation |
 
 ```bash
 pnpm test:unit          # single run
@@ -60,6 +61,16 @@ Full cache lifecycle: static pages, fetch caching, revalidation, tag invalidatio
 pnpm test:integration
 ```
 
+### Pages Router (`pages-router.integration.test.ts`)
+
+Pages Router cache lifecycle against the `next-pages-16-2-6` app: `PAGES` entry format, TTL derivation from `getStaticProps` `revalidate`, `fallback: 'blocking'` first hits, `notFound: true` (null cache entries), `redirect:` results, and `revalidate: false` TTL fallback.
+
+Starts **two** `next start` instances of the same build sharing one Redis and proves that on-demand revalidation (`res.revalidate(path)`) triggered on instance A is served fresh by instance B (HTML and `/_next/data` pageData JSON) — the multi-instance ISR scenario behind a load balancer.
+
+```bash
+pnpm test:integration:pages
+```
+
 ### BUILD_ID Prefix (`build-id-prefix.integration.test.ts`)
 
 Verifies that when neither `KEY_PREFIX` nor `VERCEL_URL` is set, the handler falls back to `.next/BUILD_ID` as the Redis key prefix. Runs in its own CI job because it needs a clean environment without those env vars.
@@ -136,6 +147,7 @@ Minimal Next.js applications used as fixtures. They are not test runners — the
 | `next-app-15-4-11`                  | 15.4.11 | Integration (matrix, default for local), build-id-prefix       |
 | `next-app-16-0-11`                  | 16.0.11 | Integration (matrix)                                           |
 | `next-app-16-2-6`                   | 16.2.6  | Integration (matrix)                                           |
+| `next-pages-16-2-6`                 | 16.2.6  | Integration (Pages Router, two-instance revalidation)          |
 | `next-app-16-0-11-cache-components` | 16.0.11 | Integration (cache-components matrix), E2E (Playwright matrix) |
 | `next-app-16-2-6-cache-components`  | 16.2.6  | Integration (cache-components matrix), E2E (Playwright matrix) |
 | `next-app-customized`               | —       | Example of custom config (referenced in project README)        |
@@ -149,6 +161,7 @@ The CI workflow (`.github/workflows/ci.yml`) is structured as:
 ```
 lint-and-unit                        → Lint + Unit Tests + Coverage
   ├── integration                    → Matrix: 3 Next.js versions (15.4–16.2)
+  ├── integration-pages              → Pages Router (two-instance revalidation)
   ├── integration-build-id-prefix    → Isolated BUILD_ID prefix test
   ├── integration-cache-components   → Matrix: 16.0.11 + 16.2.6 cache-components
   └── e2e                            → Matrix: Playwright against 16.0.11 + 16.2.6
@@ -160,6 +173,7 @@ lint-and-unit                        → Lint + Unit Tests + Coverage
 | ------------------------------ | --------------------------------------------------------- | --------------------------------------------------------------- |
 | `lint-and-unit`                | —                                                         | `pnpm lint` + `pnpm test:unit:coverage`                         |
 | `integration`                  | `next-app-15-4-11`, `next-app-16-0-11`, `next-app-16-2-6` | `pnpm test:integration` (per matrix entry)                      |
+| `integration-pages`            | `next-pages-16-2-6`                                       | `pnpm test:integration:pages`                                   |
 | `integration-build-id-prefix`  | `next-app-15-4-11`                                        | `pnpm test:integration:build-id-prefix`                         |
 | `integration-cache-components` | `next-app-16-{0-3,2-3}-cache-components`                  | `pnpm test:integration:cache-components` + Redis kill/reconnect |
 | `e2e`                          | `next-app-16-{0-3,2-3}-cache-components`                  | `pnpm test:e2e` (Playwright)                                    |
@@ -171,6 +185,7 @@ lint-and-unit                        → Lint + Unit Tests + Coverage
 | Variable                | Used by                        | Description                                                               |
 | ----------------------- | ------------------------------ | ------------------------------------------------------------------------- |
 | `NEXT_TEST_APP`         | Integration                    | Which test app to use (default: `next-app-15-4-11`)                       |
+| `NEXT_PAGES_TEST_APP`   | Integration (Pages Router)     | Which Pages Router test app to use (default: `next-pages-16-2-6`)         |
 | `CACHE_COMPONENTS_APP`  | Integration (cache-components) | Which cache-components app (default: `next-app-16-2-6-cache-components`)  |
 | `PLAYWRIGHT_TEST_APP`   | E2E                            | Which app Playwright starts (default: `next-app-16-2-6-cache-components`) |
 | `PLAYWRIGHT_BASE_URL`   | E2E                            | Override base URL (skips `webServer` auto-start)                          |

package/test/nextjs-test-projects/next-pages-16-2-6/README.md

@@ -0,0 +1,16 @@
+# next-pages-16-2-6
+
+Next.js 16.2.6 **Pages Router** fixture for integration testing the Redis
+cache handler with Pages Router cache entry kinds:
+
+- `PAGES` — ISR pages via `getStaticProps` + `revalidate` and
+  `getStaticPaths` with `fallback: 'blocking'` (`/isr/[slug]`)
+- `REDIRECT` — `getStaticProps` returning `redirect:` (`/isr/redirect`)
+- `null` value entries — `getStaticProps` returning `notFound: true`
+  (`/isr/not-found`)
+- `revalidate: false` TTL fallback (`/static-forever`)
+- On-demand revalidation via `res.revalidate(path)`
+  (`/api/revalidate?path=...`), used by the two-instance cross-server
+  revalidation test
+
+Used by `test/vitest/integration/pages-router.integration.test.ts`.

package/test/nextjs-test-projects/next-pages-16-2-6/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

package/test/nextjs-test-projects/next-pages-16-2-6/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  cacheHandler: require.resolve('@trieb.work/nextjs-turbo-redis-cache'),
+};
+
+export default nextConfig;

package/test/nextjs-test-projects/next-pages-16-2-6/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "next-pages-16-2-6",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "next": "16.2.6",
+    "react": "19.2.0",
+    "react-dom": "19.2.0",
+    "redis": "4.7.0",
+    "@trieb.work/nextjs-turbo-redis-cache": "file:../../../"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.6",
+    "typescript": "^5"
+  }
+}