@trieb.work/nextjs-turbo-redis-cache 1.17.0 → 1.18.1

package/src/utils/prefix.ts

@@ -1,44 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-
-export function readBuildId(serverDistDir?: string): string | undefined {
-  try {
-    if (serverDistDir) {
-      const buildIdPath = path.join(serverDistDir, '..', 'BUILD_ID');
-      const buildId = fs.readFileSync(buildIdPath, 'utf8').trim();
-      return buildId || undefined;
-    }
-  } catch {
-    // fall through to cwd-based read
-  }
-  try {
-    const fromCwd = path.join(process.cwd(), '.next', 'BUILD_ID');
-    const buildId = fs.readFileSync(fromCwd, 'utf8').trim();
-    return buildId || undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-export function resolveKeyPrefix({
-  optionKeyPrefix,
-  serverDistDir,
-  env,
-}: {
-  optionKeyPrefix?: string;
-  serverDistDir?: string;
-  env: NodeJS.ProcessEnv;
-}): string {
-  // If the option is explicitly provided, honor it even if it's an empty string
-  if (optionKeyPrefix !== undefined) {
-    return optionKeyPrefix;
-  }
-
-  const keyPrefixEnv =
-    env.KEY_PREFIX && env.KEY_PREFIX.length > 0 ? env.KEY_PREFIX : undefined;
-  const vercelUrl =
-    env.VERCEL_URL && env.VERCEL_URL.length > 0 ? env.VERCEL_URL : undefined;
-  const buildId = readBuildId(serverDistDir);
-
-  return keyPrefixEnv ?? vercelUrl ?? buildId ?? 'UNDEFINED_URL_';
-}

package/test/README.md

@@ -1,194 +0,0 @@
-# Test Structure
-
-```
-test/
-├── playwright/              # E2E tests — browser automation (Playwright)
-├── vitest/                  # Unit + Integration tests (Vitest)
-│   ├── unit/                # Pure unit tests (no external deps)
-│   └── integration/         # Integration tests (Redis + Next.js server)
-│       └── cache-components/  # Cache Components integration (Next.js 16+)
-└── nextjs-test-projects/    # Next.js app fixtures (shared across test types)
-```
-
-## Overview
-
-| Layer           | Runner     | What it validates                                                       | Needs Redis? | Needs Next.js app? |
-| --------------- | ---------- | ----------------------------------------------------------------------- | ------------ | ------------------ |
-| **Unit**        | Vitest     | Logic in isolation (serializer, prefix resolution, reconnect handling)  | No           | No                 |
-| **Integration** | Vitest     | Cache handler ↔ Redis ↔ Next.js HTTP responses (server-side plumbing) | Yes          | Yes                |
-| **E2E**         | Playwright | User-facing behavior in a real browser (Cache Components / `use cache`) | Yes          | Yes                |
-
----
-
-## Unit Tests (`test/vitest/unit/`)
-
-**Runner:** Vitest
-**Command:** `pnpm test:unit`
-**Config:** `vite.config.ts`
-
-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               |
-| `pages-router-kinds.test.ts`              | Pages Router cache kinds (`PAGES`, `REDIRECT`, `null`/notFound), implicit tags, TTL derivation |
-
-```bash
-pnpm test:unit          # single run
-pnpm test:unit:watch    # watch mode
-pnpm test:unit:coverage # with coverage report (used in CI)
-```
-
----
-
-## Integration Tests (`test/vitest/integration/`)
-
-**Runner:** Vitest
-**Command:** `pnpm test:integration`
-**Config:** `vite.config.ts`
-**Requires:** Redis on localhost:6379, pre-built Next.js test app
-
-These tests spawn a real Next.js server as a child process, make `fetch()` requests against it, and verify both HTTP responses and Redis state directly.
-
-### Standard Integration (`nextjs-cache-handler.integration.test.ts`)
-
-Full cache lifecycle: static pages, fetch caching, revalidation, tag invalidation, TTL behavior. In CI this runs against Next.js 15.4, 16.0, 16.2, and 16.3. Nested fetch entries are resolved from their explicit cache tag in Redis's shared-tags map rather than Next.js's internal fetch-key hash, which changed in Next.js 16.3.
-
-```bash
-pnpm test:integration
-```
-
-### Pages Router (`pages-router.integration.test.ts`)
-
-Pages Router cache lifecycle against the `next-pages-16-2-6` and `next-pages-16-3-0` apps: `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.
-
-```bash
-pnpm test:integration:build-id-prefix
-```
-
-### Cache Components (`cache-components/`)
-
-Integration tests specific to Next.js 16 Cache Components (`use cache`). CI runs them against the 16.0, 16.2, and 16.3 Cache Components test apps.
-
-| File                                   | What it tests                                                                                          |
-| -------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `cache-components.integration.test.ts` | `use cache` lifecycle: store, retrieve, tag invalidation, `cacheLife` expiry                           |
-| `redis-kill-reconnect.test.ts`         | Graceful recovery when Redis drops and reconnects (main client ping only)                              |
-| `redis-subscriber-outage.test.ts`      | Issue #86: subscriber PubSub does not recover after Redis outage (expected to fail until bug is fixed) |
-| `redis-quit-vs-disconnect.test.ts`     | `quit()` does not reliably close a subscriber during an outage; `disconnect()` does                    |
-
-`redis-kill-reconnect.test.ts` uses a container runtime and auto-detects `podman` first, then `docker`. You can force runtime selection with `CONTAINER_RUNTIME=podman` or `CONTAINER_RUNTIME=docker`.
-
-```bash
-pnpm test:integration:cache-components
-```
-
-**Prerequisites for all integration tests:**
-
-```bash
-cd test/nextjs-test-projects/<app-name>
-pnpm install && pnpm build
-```
-
----
-
-## E2E Tests (`test/playwright/`)
-
-**Runner:** Playwright
-**Command:** `pnpm test:e2e`
-**Config:** `playwright.config.ts`
-**Requires:** Redis on localhost:6379 (Playwright auto-starts `next-app-16-2-6-cache-components` via `webServer`)
-
-Browser-based tests that validate Cache Components behavior from the user's perspective. Playwright was introduced because the Cache Components (`use cache`) feature in Next.js 16 relies on interactions that `fetch()` alone cannot reproduce:
-
-- **Server Actions** are triggered by form submissions / button clicks — requires a real browser context
-- `**updateTag`\*\* must be called from within a Server Action — needs actual UI interaction to verify
-- **Cookie-based cache keys** depend on the browser sending cookies during navigation
-- **Stale-while-revalidate** effects are only observable through page reloads and DOM diffing
-
-The Vitest cache-components integration tests verify the server-side plumbing (Redis state, HTTP responses). Playwright closes the gap by testing the full user-facing flow.
-
-| File                 | What it tests                                                                                                        |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `cache-lab.spec.ts`  | `use cache` stability, tag invalidation (`updateTag`/`revalidateTag`), runtime cookie-based cache keys, SWR behavior |
-| `update-tag.spec.ts` | `updateTag` via Server Actions (button click → action → UI update)                                                   |
-
-```bash
-pnpm test:e2e
-
-# Test against a specific Next.js version:
-PLAYWRIGHT_TEST_APP=next-app-16-0-11-cache-components pnpm test:e2e
-
-# Or point at an already-running server:
-PLAYWRIGHT_BASE_URL=http://localhost:3001 pnpm test:e2e
-```
-
----
-
-## Next.js Test Projects (`test/nextjs-test-projects/`)
-
-Minimal Next.js applications used as fixtures. They are not test runners — they provide the server that tests run against.
-
-| App                                 | Next.js | Used by                                                        |
-| ----------------------------------- | ------- | -------------------------------------------------------------- |
-| `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)        |
-
----
-
-## CI Jobs
-
-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
-```
-
-`lint-and-unit` runs first as a gate. All other jobs run in parallel after it passes.
-
-| CI Job                         | Test App(s)                                               | What runs                                                       |
-| ------------------------------ | --------------------------------------------------------- | --------------------------------------------------------------- |
-| `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)                                    |
-
----
-
-## Environment Variables
-
-| 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)                          |
-| `SKIP_BUILD`            | Integration                    | Skip Next.js build if app is pre-built                                    |
-| `DEBUG_INTEGRATION`     | Integration                    | Print child process stdout/stderr                                         |
-| `CACHE_COMPONENTS_PORT` | Integration (cache-components) | Port for the server (default: 3065)                                       |

package/test/nextjs-test-projects/next-app-15-4-11/README.md

@@ -1,36 +0,0 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
-
-## Getting Started
-
-First, run the development server:
-
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
-```
-
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
-
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
-
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
-
-## Learn More
-
-To learn more about Next.js, take a look at the following resources:
-
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
-
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
-
-## Deploy on Vercel
-
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
-
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

package/test/nextjs-test-projects/next-app-15-4-11/eslint.config.mjs

@@ -1,16 +0,0 @@
-import { dirname } from "path";
-import { fileURLToPath } from "url";
-import { FlatCompat } from "@eslint/eslintrc";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const compat = new FlatCompat({
-  baseDirectory: __dirname,
-});
-
-const eslintConfig = [
-  ...compat.extends("next/core-web-vitals", "next/typescript"),
-];
-
-export default eslintConfig;

package/test/nextjs-test-projects/next-app-15-4-11/next.config.js

@@ -1,9 +0,0 @@
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  cacheHandler: require.resolve('@trieb.work/nextjs-turbo-redis-cache'),
-  turbopack: {
-    root: __dirname,
-  },
-};
-
-module.exports = nextConfig;