@trieb.work/nextjs-turbo-redis-cache 1.2.1 → 1.4.0

package/.github/workflows/ci.yml

@@ -16,6 +16,7 @@ permissions:
   statuses: write
   issues: write
   actions: write
+  discussions: write
 
 jobs:
   build:
@@ -27,28 +28,52 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v3
 
+      - name: Install pnpm
+        run: corepack enable
+
       - name: Setup Node.js
         uses: actions/setup-node@v3
         with:
           node-version: '20'
+          cache: 'pnpm'
 
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install
 
       - name: Run lint
-        run: npm 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-3-2 && pnpm install
+
+      - name: Build Integration Test Project
+        run: cd test/integration/next-app-15-3-2 && pnpm build
 
       - name: Run tests
-        run: npm run test
+        run: pnpm test
+        env:
+          SKIP_BUILD: true
 
       - name: Code Coverage Comments
         uses: kcjpop/coverage-comments@v2.2
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           coverage-file: './coverage/lcov.info'
-
-      - name: Build project
-        run: npm run build
       
       - name: Dry run the release
         env:

package/.github/workflows/release.yml

@@ -14,6 +14,7 @@ permissions:
   statuses: write
   issues: write
   actions: write
+  discussions: write
 
 jobs:
   release:
@@ -23,17 +24,20 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v3
 
+      - name: Install pnpm
+        run: corepack enable
+
       - name: Setup Node.js
         uses: actions/setup-node@v3
         with:
           node-version: '20'
-          cache: 'npm'
+          cache: 'pnpm'
 
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install
 
       - name: Build project
-        run: npm run build
+        run: pnpm run build
 
       - name: Run Semantic Release
         env:

package/.next/trace

@@ -0,0 +1,11 @@
+[{"name":"generate-buildid","duration":140,"timestamp":4515754197453,"id":4,"parentId":1,"tags":{},"startTime":1746464013531,"traceId":"c44ff29d5c06adcb"},{"name":"load-custom-routes","duration":167,"timestamp":4515754197651,"id":5,"parentId":1,"tags":{},"startTime":1746464013531,"traceId":"c44ff29d5c06adcb"},{"name":"next-build","duration":581845,"timestamp":4515753617731,"id":1,"tags":{"buildMode":"default","isTurboBuild":"false","version":"15.0.3"},"startTime":1746464012951,"traceId":"c44ff29d5c06adcb"}]
+[{"name":"generate-buildid","duration":217,"timestamp":4515766041037,"id":4,"parentId":1,"tags":{},"startTime":1746464025375,"traceId":"6cf74253dfcd5659"},{"name":"load-custom-routes","duration":199,"timestamp":4515766041361,"id":5,"parentId":1,"tags":{},"startTime":1746464025375,"traceId":"6cf74253dfcd5659"},{"name":"next-build","duration":97220,"timestamp":4515765945991,"id":1,"tags":{"buildMode":"default","isTurboBuild":"false","version":"15.0.3"},"startTime":1746464025280,"traceId":"6cf74253dfcd5659"}]
+[{"name":"generate-buildid","duration":131,"timestamp":4515813285753,"id":4,"parentId":1,"tags":{},"startTime":1746464072620,"traceId":"fcfa690a3abfa3ea"},{"name":"load-custom-routes","duration":186,"timestamp":4515813285997,"id":5,"parentId":1,"tags":{},"startTime":1746464072620,"traceId":"fcfa690a3abfa3ea"},{"name":"next-build","duration":60933,"timestamp":4515813226764,"id":1,"tags":{"buildMode":"default","isTurboBuild":"false","version":"15.0.3"},"startTime":1746464072561,"traceId":"fcfa690a3abfa3ea"}]
+[{"name":"generate-buildid","duration":120,"timestamp":4515831765983,"id":4,"parentId":1,"tags":{},"startTime":1746464091100,"traceId":"41bfa0fcaa95d6de"},{"name":"load-custom-routes","duration":162,"timestamp":4515831766158,"id":5,"parentId":1,"tags":{},"startTime":1746464091100,"traceId":"41bfa0fcaa95d6de"},{"name":"next-build","duration":64360,"timestamp":4515831703128,"id":1,"tags":{"buildMode":"default","isTurboBuild":"false","version":"15.0.3"},"startTime":1746464091037,"traceId":"41bfa0fcaa95d6de"}]
+[{"name":"generate-buildid","duration":138,"timestamp":4515903825041,"id":4,"parentId":1,"tags":{},"startTime":1746464163159,"traceId":"b39fefc0a6cc67ce"},{"name":"load-custom-routes","duration":168,"timestamp":4515903825245,"id":5,"parentId":1,"tags":{},"startTime":1746464163160,"traceId":"b39fefc0a6cc67ce"},{"name":"next-build","duration":62582,"timestamp":4515903763978,"id":1,"tags":{"buildMode":"default","isTurboBuild":"false","version":"15.0.3"},"startTime":1746464163098,"traceId":"b39fefc0a6cc67ce"}]
+[{"name":"generate-buildid","duration":131,"timestamp":4515927634537,"id":4,"parentId":1,"tags":{},"startTime":1746464186969,"traceId":"a7e49e03eb857d5c"},{"name":"load-custom-routes","duration":363,"timestamp":4515927634726,"id":5,"parentId":1,"tags":{},"startTime":1746464186969,"traceId":"a7e49e03eb857d5c"},{"name":"next-build","duration":68467,"timestamp":4515927568131,"id":1,"tags":{"buildMode":"default","isTurboBuild":"false","version":"15.0.3"},"startTime":1746464186903,"traceId":"a7e49e03eb857d5c"}]
+[{"name":"generate-buildid","duration":109,"timestamp":4516102680149,"id":4,"parentId":1,"tags":{},"startTime":1746464362001,"traceId":"ad1b689177cf0789"},{"name":"load-custom-routes","duration":149,"timestamp":4516102680307,"id":5,"parentId":1,"tags":{},"startTime":1746464362001,"traceId":"ad1b689177cf0789"},{"name":"next-build","duration":56682,"timestamp":4516102625265,"id":1,"tags":{"buildMode":"default","isTurboBuild":"false","version":"15.0.3"},"startTime":1746464361946,"traceId":"ad1b689177cf0789"}]
+[{"name":"generate-buildid","duration":108,"timestamp":4516106451659,"id":4,"parentId":1,"tags":{},"startTime":1746464365773,"traceId":"92f2d146f1781280"},{"name":"load-custom-routes","duration":154,"timestamp":4516106451818,"id":5,"parentId":1,"tags":{},"startTime":1746464365773,"traceId":"92f2d146f1781280"},{"name":"next-build","duration":54163,"timestamp":4516106398853,"id":1,"tags":{"buildMode":"default","isTurboBuild":"false","version":"15.0.3"},"startTime":1746464365720,"traceId":"92f2d146f1781280"}]
+[{"name":"generate-buildid","duration":196,"timestamp":4516139403659,"id":4,"parentId":1,"tags":{},"startTime":1746464398725,"traceId":"a7a541a7bd9a53a0"},{"name":"load-custom-routes","duration":232,"timestamp":4516139403975,"id":5,"parentId":1,"tags":{},"startTime":1746464398725,"traceId":"a7a541a7bd9a53a0"},{"name":"next-build","duration":58401,"timestamp":4516139349232,"id":1,"tags":{"buildMode":"default","isTurboBuild":"false","version":"15.0.3"},"startTime":1746464398670,"traceId":"a7a541a7bd9a53a0"}]
+[{"name":"generate-buildid","duration":103,"timestamp":4516187933744,"id":4,"parentId":1,"tags":{},"startTime":1746464447255,"traceId":"067afd570d8c005a"},{"name":"load-custom-routes","duration":177,"timestamp":4516187933896,"id":5,"parentId":1,"tags":{},"startTime":1746464447255,"traceId":"067afd570d8c005a"},{"name":"next-build","duration":56944,"timestamp":4516187878433,"id":1,"tags":{"buildMode":"default","isTurboBuild":"false","version":"15.0.3"},"startTime":1746464447199,"traceId":"067afd570d8c005a"}]
+[{"name":"generate-buildid","duration":114,"timestamp":4516223927765,"id":4,"parentId":1,"tags":{},"startTime":1746464483249,"traceId":"8b53fbabb9360dbf"},{"name":"load-custom-routes","duration":166,"timestamp":4516223927936,"id":5,"parentId":1,"tags":{},"startTime":1746464483249,"traceId":"8b53fbabb9360dbf"},{"name":"next-build","duration":56140,"timestamp":4516223873187,"id":1,"tags":{"buildMode":"default","isTurboBuild":"false","version":"15.0.3"},"startTime":1746464483194,"traceId":"8b53fbabb9360dbf"}]

package/.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+  "cSpell.words": [
+    "EJSON",
+    "Keyevent",
+    "keyspace",
+    "postboned",
+    "REDISHOST",
+    "REDISPORT"
+  ]
+}

package/CHANGELOG.md

@@ -1,3 +1,74 @@
+# [1.4.0](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.3.0...v1.4.0) (2025-05-09)
+
+
+### Bug Fixes
+
+* add tests ([225fc49](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/225fc49eff26d631c4b8d50a15ef2c864213f36b))
+* comment ([321ddec](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/321ddec4ee9b6a6e2cf1f78062d05d2cc7b45e4c))
+* remove retry ([ca4ff6c](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/ca4ff6c4072e675da42dbcfe36d3ff422dc54f12))
+* remove retry ([3a1cf7d](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/3a1cf7dc5fd315ff3c84460052af20b8e40014ec))
+* remove retry ([207413b](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/207413b81cb51143e04dff9a2310a185d6bba568))
+* tests and ci ([b0841ad](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/b0841ad9bc2c4b3ab9edde7047259cd45fbd5f02))
+
+
+### Features
+
+* add support for nextjs 15.3.2 ([fcd8bb5](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/fcd8bb5469bbefcd88397d3ef86ce3eb0fee7c02))
+
+# [1.3.0](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.2.1...v1.3.0) (2025-05-08)
+
+
+### Bug Fixes
+
+* encoding of data in cache entry ([9f0e747](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/9f0e747b224294905427ba3060185f68fee16f0f))
+* escape characte ([dbd9141](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/dbd91413b777b2a4554597f3ca2b7f1de1163a80))
+* readme ([31dcaa4](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/31dcaa40ac19ea42a7f4d6ca33e4642704ad1f6b))
+* readme ([dfb69c8](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/dfb69c861ddaa4a94411d419854e1c2e1e99152e))
+* test ([13b2cb8](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/13b2cb8020ef7457473b208675bf3fce4161f492))
+* tests ([02357e1](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/02357e1a7a29d997c95dce42399fef26530467d4))
+* tests ([a5587dc](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/a5587dc3701a92069da945f548991aeb0d999285))
+* tests + re-add old implementation ([cb6d36d](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/cb6d36d46008d422b4396fd580d35fa97848edb7))
+* tests improvement ([73a3594](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/73a35946cfcd5e4811c2c09201bb02c9cdea5298))
+* tests, make them independent from each other ([35885e3](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/35885e38a58ac0aa976c86dd964549e2d3426a79))
+
+
+### Features
+
+* add files ([d8a2474](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/d8a24747a6a2a12e2709d017dd36c7b80b2ad49f))
+* add more comments ([fb2f105](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/fb2f10588566fad042d2e8da4999cf7bf591555d))
+* add new invalidation logic for fetch requests + new tests ([9d0d1d2](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/9d0d1d2eafb785dbe91b172358a19494c623cc68))
+* add new tests ([836b882](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/836b88249365ea8745ca839a7dc3a3a4a77732e6))
+* add new tests ([d0e6833](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/d0e68335ce13827f74ed1be5b115f7351beebd47))
+* adding a test page ([d4c8a8c](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/d4c8a8caaba7f4e5003606860babd9e50c6ed99a))
+* adding comfortable cache testing tool on homepage ([340d5cb](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/340d5cbc929ea8dcdbef2a949e1656d014d1f3bb))
+* adding nextjs unit tests ([368ec75](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/368ec755a8532a52526e3364cc02f64b7d4245fa))
+* changed ([8501a4e](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/8501a4ee963975f32661789e31281785cf01519a))
+* changed hook ([92f9d3c](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/92f9d3c4b8d9afd6bbbb9cc3a69138823f4d4f87))
+* changed hook ([6b32f0a](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/6b32f0abcda935046e61242ba633728bcf23a460))
+* extend and fix caching + chore: update readme ([7ef38a8](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/7ef38a8ed2a20957cc78ffa213be3cb334736b19))
+* extend tests ([db9bb85](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/db9bb85e398a7d6e1ba522b990de7e5e241b54b6))
+* improve flaky ms sync delay ([6655884](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/665588474a09f1eb4f4683d2e107ec8b5b36b39a))
+* improve readme ([926493a](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/926493a198d15e32e5e4b5c619375df85c646f1c))
+* improve tests ([3fcfadf](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/3fcfadf49389fe8a7218417fb79ec74445e76cb7))
+* remove unnecessary revalidatedTagsMap ([7b5c313](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/7b5c313e91b5157f113085be75dceba8013c0e81))
+* test is running ([6091471](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/6091471a12f954e3da4bd94db0929b0bd2cfd701))
+* tests ([bd6904e](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/bd6904e94a43cfac183a5ec86cbbea0f4e40a816))
+* tests 2 ([974c952](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/974c952587a9d330934f49b26db84c037b3695f5))
+* update CI with pnpm ([c1b0b33](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/c1b0b33417b416bd7755b6b2f43d0b9bea5c7690))
+* update CI with pnpm ([d850377](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/d85037706876dcb036bb6f952a48937c3e96cba3))
+* update CI with pnpm 10 ([c559936](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/c5599361f15c4c82fa999e16a48fcf78e53355a6))
+* update CI with pnpm 11 ([f83708f](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/f83708f76c3924b8b80dd612965dc49a95d7e18c))
+* update CI with pnpm 2 ([235f0fc](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/235f0fc8cb35dbe532091d8f545791b8dd05b6be))
+* update CI with pnpm 2 ([cb9624e](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/cb9624e900f555bc07c734ff152c4f4a93000e54))
+* update CI with pnpm 3 ([72c25ce](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/72c25cefa2aea6767d5a71b5470955a18f9036b9))
+* update CI with pnpm 4 ([fff355a](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/fff355a8e047d766121d255881d891fa7c5a754e))
+* update CI with pnpm 4 ([facd58b](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/facd58bdefd530d70fdbb2f7d48c9962ca2195e5))
+* update CI with pnpm 5 ([03d9d90](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/03d9d906e852927496a58504dd9c7448e31878a1))
+* update CI with pnpm 6 ([b5e7066](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/b5e7066ec840edfa7d6df6c6ab978c61b356c8b5))
+* update CI with pnpm 8 ([20c3a5b](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/20c3a5be9d465537240cce6ac5346554667cda68))
+* update CI with pnpm 9 ([5160fd3](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/5160fd3e1a010a5b52b99d0e2e0de3b9035d1e88))
+* update docs and tests ([7a46c21](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/7a46c21346d878df88283071551f06a34d71eb9a))
+
 ## [1.2.1](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.2.0...v1.2.1) (2025-03-28)
 
 

package/README.md

@@ -1,50 +1,130 @@
 # nextjs-turbo-redis-cache
 
-The ultimate Redis caching solution for Next.js. Built for production-ready, large-scale projects, it delivers unparalleled performance and efficiency with features tailored for high-traffic applications.
+[![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)
+
+The ultimate Redis caching solution for Next.js. 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:
 
-- _Turbocharged Storage_: Avoids base64 encoding to save ~33% of storage space compared to traditional implementations.
 - _Batch Tag Invalidation_: Groups and optimizes delete operations for minimal Redis stress.
 - _Request Deduplication_: Prevents redundant Redis get calls, ensuring faster response times.
-- _In-Memory Caching_: Includes local caching for Redis get operations to reduce latency further.
+- _In-Memory Caching_: Includes local caching for Redis get operations to reduce latency further. Don't request redis for the same key multiple times.
 - _Efficient Tag Management_: in-memory tags map for lightning-fast revalidate operations with minimal Redis overhead.
 - _Intelligent Key-Space Notifications_: Automatic update of in-memory tags map for expired or evicted keys.
 
-## Describe Options
+## 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.
+Redis need to have Redis Version 2.8.0 or higher and have to be configured with `notify-keyspace-events` to be able to use the key-space notifications feature.
+
+Tested versions are:
+
+- 15.0.3
+- 15.2.4
+- 15.3.2
+  Currently PPR, 'use cache', cacheLife and cacheTag are not tested. Use these operations with caution and your own risk.
 
-TODO
+## Available Options (needs Option B of getting started)
+
+| Option                 | Description                                                                                                       | Default Value                                         |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | --- | ----------------- |
+| 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                                                                                    | `process.env.VERCEL_URL                               |     | 'UNDEFINED*URL*'` |
+| sharedTagsKey          | Key used to store shared tags hash map in Redis                                                                   | `'__sharedTags__'`                                    |
+| timeoutMs              | Timeout in milliseconds for Redis operations                                                                      | `5000`                                                |
+| 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` |
 
 ## Getting started
 
+### Enable redis key-space notifications for Expire and Evict events
+
+```bash
+redis-cli -h localhost config set notify-keyspace-events Exe
+```
+
+### Install package
+
 ```bash
 pnpm install @trieb.work/nextjs-turbo-redis-cache
 ```
 
+### Setup environment variables in your project/deployment
+
+REDISHOST and REDISPORT environment variables are required.
+VERCEL_URL, VERCEL_ENV are optional. VERCEL_URL is used to create a key prefix for the redis keys. VERCEL_ENV is used to determine the database to use. Only VERCEL_ENV=production will show up in DB 0 (redis default db). All other values of VERCEL_ENV will use DB 1, use `redis-cli -n 1` to connect to different DB 1. This is another protection feature to avoid that different environments (e.g. staging and production) will overwrite each other.
+Furthermore there exists the DEBUG_CACHE_HANDLER environment variable to enable debug logging of the caching handler once it is set to true.
+
+### Option A: minimum implementation with default options
+
+extend `next.config.js` with:
+
+```
+const nextConfig = {
+  ...
+  cacheHandler: require.resolve("@trieb.work/nextjs-turbo-redis-cache")
+  ...
+}
+```
+
+### Option B: create a wrapper file to change options
+
+create new file `customized-cache-handler.js` in your project root and add the following code:
+
+```
+const { RedisStringsHandler } = require('@trieb.work/nextjs-turbo-redis-cache');
+
+let cachedHandler;
+
+module.exports = class CustomizedCacheHandler {
+  constructor() {
+    if (!cachedHandler) {
+      cachedHandler = new RedisStringsHandler({
+        database: 0,
+        keyPrefix: 'test',
+        timeoutMs: 2_000,
+        revalidateTagQuerySize: 500,
+        sharedTagsKey: '__sharedTags__',
+        avgResyncIntervalMs: 10_000 * 60,
+        redisGetDeduplication: false,
+        inMemoryCachingTime: 0,
+        defaultStaleAge: 1209600,
+        estimateExpireAge: (staleAge) => staleAge * 2,
+      });
+    }
+  }
+  get(...args) {
+    return cachedHandler.get(...args);
+  }
+  set(...args) {
+    return cachedHandler.set(...args);
+  }
+  revalidateTag(...args) {
+    return cachedHandler.revalidateTag(...args);
+  }
+  resetRequestCache(...args) {
+    return cachedHandler.resetRequestCache(...args);
+  }
+}
+```
+
 extend `next.config.js` with:
+
 ```
 const nextConfig = {
-  cacheHandler:
-    process.env.NODE_ENV === "production" || process.env.DEV_REDIS_CACHE
-      ? new CachedHandler({
-        // Default Options:
-        // maxMemoryCacheSize, // deprecated
-        // database = process.env.VERCEL_ENV === 'production' ? 0 : 1,
-        // keyPrefix = process.env.VERCEL_URL || 'UNDEFINED_URL_',
-        // sharedTagsKey = '__sharedTags__',
-        // timeoutMs = 5000,
-        // revalidateTagQuerySize = 250,
-        // avgResyncIntervalMs = 60 * 60 * 1000,
-        // redisGetDeduplication = true,
-        // inMemoryCachingTime = 10_000,
-        // defaultStaleAge = 60 * 60 * 24 * 14,
-        // estimateExpireAge = (staleAge) =>
-        //   process.env.VERCEL_ENV === 'preview' ? staleAge * 1.2 : staleAge * 2,
-      })
-      : undefined,
+  ...
+  cacheHandler: require.resolve("./customized-cache-handler")
+  ...
+}
 ```
 
-## Consistency
+A working example of above can be found in the `test/integration/next-app-customized` folder.
+
+## Consistency of Redis and this caching implementation
 
 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.
@@ -72,23 +152,63 @@ If using local in-memory caching (Enabled by RedisStringsHandler option inMemory
 
 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).
 
+By accepting and tolerating this eventual consistency, the performance of the caching handler is significantly increased.
+
 ## Development
 
-5. Run `npm install` to install the dependencies
-6. Run `npm run build` to build the project
-7. Run `npm run dev` to develop the project
-8. Run `npm run test` to test the project
-9. Checkout into a new branch (main is protected)
-10. Change code and commit it using conventional commit. Staged code will get checked
-11. Push and create a PR (against main or beta) to run CI
-12. Merge to main or beta to create a release or pre-release
+1. Run `pnpm install` to install the dependencies
+1. Run `pnpm build` to build the project
+1. Run `pnpm lint` to lint the project
+1. Run `pnpm format` to format the project
+1. Run `pnpm run-dev-server` to test and develop the caching handler using the nextjs integration test project
+1. If you make changes to the cache handler, you need to stop `pnpm run-dev-server` and run it again.
+
+## Testing
+
+To run all tests you can use the following command:
+
+```bash
+pnpm test
+```
+
+### Unit tests
+
+To run unit tests you can use the following command:
+
+```bash
+pnpm test:unit
+```
+
+### Integration tests
+
+To run integration tests you can use the following command:
+
+```bash
+pnpm test:integration
+```
+
+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.
+- SKIP_OPTIONAL_LONG_RUNNER_TESTS: If set to true, the integration tests will not run the optional long runner tests.
+- DEBUG_INTEGRATION: If set to true, the integration tests will print debug information of the test itself to the console.
+
+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.
+
+## Some words on nextjs caching internals
+
+Nextjs will use different caching objects for different pages and api routes. Currently supported are kind: APP_ROUTE and APP_PAGE.
+
+app/<segment>/route.ts files will request using the APP_ROUTE kind.
+app/<segment>/page.tsx files will request using the APP_PAGE kind.
+/favicon.ico file will request using the APP_ROUTE kind.
+
+Fetch requests (inside app route or page) will request using the FETCH kind.
 
 ## License
 
 This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
 
-
 ## Sponsor
 
 This project is created and maintained by the Next.js & Payload CMS agency [trieb.work](https://trieb.work)
-

package/dist/index.d.mts

@@ -1,21 +1,51 @@
-import { CacheHandler, IncrementalCache, CacheHandlerValue } from 'next/dist/server/lib/incremental-cache';
-
-type GetParams = Parameters<IncrementalCache['get']>;
-type SetParams = Parameters<IncrementalCache['set']>;
-type RevalidateParams = Parameters<IncrementalCache['revalidateTag']>;
+type CacheEntry = {
+    value: unknown;
+    lastModified: number;
+    tags: string[];
+};
 type CreateRedisStringsHandlerOptions = {
+    /** Redis database number to use. Uses DB 0 for production, DB 1 otherwise
+     * @default process.env.VERCEL_ENV === 'production' ? 0 : 1
+     */
     database?: number;
+    /** Prefix added to all Redis keys
+     * @default process.env.VERCEL_URL || 'UNDEFINED_URL_'
+     */
     keyPrefix?: string;
+    /** Timeout in milliseconds for Redis operations
+     * @default 5000
+     */
     timeoutMs?: number;
+    /** Number of entries to query in one batch during full sync of shared tags hash map
+     * @default 250
+     */
     revalidateTagQuerySize?: number;
+    /** Key used to store shared tags hash map in Redis
+     * @default '__sharedTags__'
+     */
     sharedTagsKey?: string;
+    /** Average interval in milliseconds between tag map full re-syncs
+     * @default 3600000 (1 hour)
+     */
     avgResyncIntervalMs?: number;
+    /** Enable deduplication of Redis get requests via internal in-memory cache
+     * @default true
+     */
     redisGetDeduplication?: boolean;
+    /** Time in milliseconds to cache Redis get results in memory. Set this to 0 to disable in-memory caching completely
+     * @default 10000
+     */
     inMemoryCachingTime?: number;
+    /** Default stale age in seconds for cached items
+     * @default 1209600 (14 days)
+     */
     defaultStaleAge?: number;
+    /** Function to calculate expire age (redis TTL value) from stale age
+     * @default Production: staleAge * 2, Other: staleAge * 1.2
+     */
     estimateExpireAge?: (staleAge: number) => number;
 };
-declare class RedisStringsHandler implements CacheHandler {
+declare class RedisStringsHandler {
     private client;
     private sharedTagsMap;
     private revalidatedTagsMap;
@@ -30,23 +60,69 @@ declare class RedisStringsHandler implements CacheHandler {
     private defaultStaleAge;
     private estimateExpireAge;
     constructor({ database, keyPrefix, sharedTagsKey, timeoutMs, revalidateTagQuerySize, avgResyncIntervalMs, redisGetDeduplication, inMemoryCachingTime, defaultStaleAge, estimateExpireAge, }: CreateRedisStringsHandlerOptions);
-    resetRequestCache(...args: never[]): void;
+    resetRequestCache(): void;
     private assertClientIsReady;
-    get(key: GetParams[0], ctx: GetParams[1]): Promise<(CacheHandlerValue & {
-        lastModified: number;
-    }) | null>;
-    set(key: SetParams[0], data: SetParams[1] & {
-        lastModified: number;
-    }, ctx: SetParams[2]): Promise<void>;
-    revalidateTag(tagOrTags: RevalidateParams[0]): Promise<void>;
+    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>;
+    set(key: string, data: {
+        kind: 'APP_PAGE';
+        status: number;
+        headers: {
+            'x-nextjs-stale-time': string;
+            'x-next-cache-tags': string;
+        };
+        html: string;
+        rscData: Buffer;
+        segmentData: unknown;
+        postboned: unknown;
+    } | {
+        kind: 'APP_ROUTE';
+        status: number;
+        headers: {
+            'cache-control'?: string;
+            'x-nextjs-stale-time': string;
+            'x-next-cache-tags': string;
+        };
+        body: Buffer;
+    } | {
+        kind: 'FETCH';
+        data: {
+            headers: Record<string, string>;
+            body: string;
+            status: number;
+            url: string;
+        };
+        revalidate: number | false;
+    }, ctx: {
+        isRoutePPREnabled: boolean;
+        isFallback: boolean;
+        tags?: string[];
+        revalidate?: number | false;
+        cacheControl?: {
+            revalidate: 5;
+            expire: undefined;
+        };
+    }): Promise<void>;
+    revalidateTag(tagOrTags: string | string[], ...rest: any[]): Promise<void>;
 }
 
-declare class CachedHandler implements CacheHandler {
+declare class CachedHandler {
     constructor(options: CreateRedisStringsHandlerOptions);
-    get(...args: Parameters<RedisStringsHandler["get"]>): ReturnType<RedisStringsHandler["get"]>;
-    set(...args: Parameters<RedisStringsHandler["set"]>): ReturnType<RedisStringsHandler["set"]>;
-    revalidateTag(...args: Parameters<RedisStringsHandler["revalidateTag"]>): ReturnType<RedisStringsHandler["revalidateTag"]>;
-    resetRequestCache(...args: Parameters<RedisStringsHandler["resetRequestCache"]>): ReturnType<RedisStringsHandler["resetRequestCache"]>;
+    get(...args: Parameters<RedisStringsHandler['get']>): ReturnType<RedisStringsHandler['get']>;
+    set(...args: Parameters<RedisStringsHandler['set']>): ReturnType<RedisStringsHandler['set']>;
+    revalidateTag(...args: Parameters<RedisStringsHandler['revalidateTag']>): ReturnType<RedisStringsHandler['revalidateTag']>;
+    resetRequestCache(...args: Parameters<RedisStringsHandler['resetRequestCache']>): ReturnType<RedisStringsHandler['resetRequestCache']>;
 }
 
-export { CachedHandler as default };
+export { RedisStringsHandler, CachedHandler as default };