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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trieb.work/nextjs-turbo-redis-cache",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "homepage": "https://trwk.de/case-studies/nextjs-turbo-redis-cache",
   "repository": {
     "type": "git",
@@ -78,10 +78,8 @@
     "@commitlint/cli": "^19.6.0",
     "@commitlint/config-conventional": "^19.6.0",
     "@playwright/test": "^1.62.0",
-    "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^12.0.2",
-    "@semantic-release/npm": "^13.1.3",
+    "@semantic-release/github": "12.0.9",
+    "@semantic-release/npm": "13.1.5",
     "@typescript-eslint/eslint-plugin": "^8.15.0",
     "@typescript-eslint/parser": "^8.15.0",
     "@vitest/coverage-v8": "^4.0.13",
@@ -91,7 +89,7 @@
     "node-fetch": "3",
     "prettier": "^3.3.3",
     "redis": "4.7.0",
-    "semantic-release": "^25.0.2",
+    "semantic-release": "25.0.9",
     "tsup": "^8.4.0",
     "tsx": "^4.21.0",
     "typescript": "^5.6.3",

package/release.config.cjs

@@ -1,31 +1,12 @@
 module.exports = {
   branches: [
-    { name: 'main' }, // Stable releases
-    { name: 'beta', prerelease: true }, // Beta releases
+    { name: 'main' },
+    { name: 'beta', prerelease: true },
   ],
   plugins: [
-    '@semantic-release/commit-analyzer', // Analyze commits to determine the release type
-    '@semantic-release/release-notes-generator', // Generate release notes
-    '@semantic-release/changelog', // Update changelog
-    [
-      '@semantic-release/npm',
-      {
-        npmPublish: false, // Publish to NPM
-        tag: 'beta', // Publish beta releases under the "beta" tag
-      },
-    ],
-    [
-      '@semantic-release/github',
-      {
-        labels: [],
-      },
-    ],
-    [
-      '@semantic-release/git',
-      {
-        assets: ['package.json', 'pnpm-lock.yaml', 'CHANGELOG.md'],
-        message: 'chore(release): ${nextRelease.version} [skip ci]',
-      },
-    ],
+    '@semantic-release/commit-analyzer',
+    '@semantic-release/release-notes-generator',
+    '@semantic-release/npm',
+    '@semantic-release/github',
   ],
 };

package/src/CacheComponentsHandler.ts

@@ -9,6 +9,17 @@ import { SyncedMap } from './SyncedMap';
 import { DeduplicatedRequestHandler } from './DeduplicatedRequestHandler';
 import { debug } from './utils/debug';
 import { resolveKeyPrefix } from './utils/prefix';
+import { shouldDeferRedisConnection } from './utils/redisConnection';
+import { compareAndUnlink } from './utils/compareAndUnlink';
+import {
+  applyTagUpdate,
+  areTagsExpired,
+  areTagsStale,
+  maxExpiredTimestamp,
+  normalizeTagManifest,
+  persistableTagManifest,
+  type TagManifestEntry,
+} from './utils/tagRevalidation';
 
 export interface CacheComponentsEntry {
   value: ReadableStream<Uint8Array>;
@@ -86,7 +97,7 @@ function bufferToReadableStream(
 
 class RedisCacheComponentsHandler implements CacheComponentsHandler {
   private client: Client;
-  private revalidatedTagsMap: SyncedMap<number>;
+  private revalidatedTagsMap: SyncedMap<TagManifestEntry | number>;
   private sharedTagsMap: SyncedMap<string[]>;
   private inMemoryDeduplicationCache: SyncedMap<
     Promise<ReturnType<Client['get']>>
@@ -101,6 +112,7 @@ class RedisCacheComponentsHandler implements CacheComponentsHandler {
   private deduplicatedRedisGet: (key: string) => Client['get'];
   private redisGetDeduplication: boolean;
   private inMemoryCachingTime: number;
+  private redisConnectionDeferred: boolean;
 
   constructor({
     redisUrl = process.env.REDIS_URL
@@ -134,6 +146,7 @@ class RedisCacheComponentsHandler implements CacheComponentsHandler {
       this.getTimeoutMs = getTimeoutMs;
       this.redisGetDeduplication = redisGetDeduplication;
       this.inMemoryCachingTime = inMemoryCachingTime;
+      this.redisConnectionDeferred = shouldDeferRedisConnection();
 
       this.client = createClient({
         url: redisUrl,
@@ -180,32 +193,35 @@ class RedisCacheComponentsHandler implements CacheComponentsHandler {
         }
       });
 
-      this.client
-        .connect()
-        .then(() => {
-          debug('green', 'RedisCacheComponentsHandler client connected.');
-        })
-        .catch(() => {
-          this.client.connect().catch((error) => {
-            console.error(
-              'Failed to connect RedisCacheComponentsHandler client:',
-              error,
-            );
-            this.client.disconnect();
-            throw error;
+      if (!this.redisConnectionDeferred) {
+        this.client
+          .connect()
+          .then(() => {
+            debug('green', 'RedisCacheComponentsHandler client connected.');
+          })
+          .catch(() => {
+            this.client.connect().catch((error) => {
+              console.error(
+                'Failed to connect RedisCacheComponentsHandler client:',
+                error,
+              );
+              this.client.disconnect();
+              throw error;
+            });
           });
-        });
+      }
 
       const filterKeys = (key: string): boolean =>
         key !== REVALIDATED_TAGS_KEY && key !== SHARED_TAGS_KEY;
 
-      this.revalidatedTagsMap = new SyncedMap<number>({
+      this.revalidatedTagsMap = new SyncedMap<TagManifestEntry | number>({
         client: this.client,
         keyPrefix: this.keyPrefix,
         redisKey: REVALIDATED_TAGS_KEY,
         database,
         querySize: revalidateTagQuerySize,
         filterKeys,
+        customizedSync: { withoutOrphanCleanup: true },
         resyncIntervalMs:
           avgResyncIntervalMs +
           avgResyncIntervalMs / 10 +
@@ -254,6 +270,14 @@ class RedisCacheComponentsHandler implements CacheComponentsHandler {
   }
 
   private async assertClientIsReady(): Promise<void> {
+    if (this.redisConnectionDeferred) {
+      await Promise.all([
+        this.revalidatedTagsMap.waitUntilReady(),
+        this.sharedTagsMap.waitUntilReady(),
+      ]);
+      return;
+    }
+
     if (!this.client.isReady && !this.client.isOpen) {
       await this.client.connect().catch((error) => {
         console.error(
@@ -269,21 +293,23 @@ class RedisCacheComponentsHandler implements CacheComponentsHandler {
     ]);
   }
 
-  private async computeMaxRevalidation(tags: string[]): Promise<number> {
-    let max = 0;
-    for (const tag of tags) {
-      const ts = this.revalidatedTagsMap.get(tag);
-      if (ts && ts > max) {
-        max = ts;
-      }
-    }
-    return max;
+  private isClientUnavailable(): boolean {
+    return this.redisConnectionDeferred || !this.client.isReady;
+  }
+
+  private tagManifestFor(tag: string, now = Date.now()): TagManifestEntry {
+    return normalizeTagManifest(this.revalidatedTagsMap.get(tag), now);
   }
 
   async get(
     cacheKey: string,
-    softTags: string[],
+    _softTags: string[],
   ): Promise<CacheComponentsEntry | undefined> {
+    // Soft-tag staleness is handled by Next.js via getExpiration() (implicit
+    // `_N_T_` tags). Explicit cacheTag()s are checked below via the tag
+    // manifest, matching DefaultCacheHandler.get() in Next.js 16.0–16.3.
+    void _softTags;
+
     // Construct the full Redis key
     // For cache components, Next.js provides the full key including environment prefix
     // We prepend our keyPrefix for multi-tenant isolation
@@ -291,63 +317,84 @@ 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' +
-          (this.redisGetDeduplication ? ' deduplicated' : '') +
-          ' ' +
-          this.getTimeoutMs +
-          'ms ' +
-          redisKey,
-        clientGet(
-          commandOptions({ signal: AbortSignal.timeout(this.getTimeoutMs) }),
-          redisKey,
-        ),
-      );
-
-      if (!serialized) {
+      if (this.isClientUnavailable()) {
         return undefined;
       }
 
-      const stored: StoredCacheEntry = JSON.parse(serialized);
-      const now = Date.now();
+      const readSerialized = (useDedup: boolean) =>
+        redisErrorHandler(
+          'RedisCacheComponentsHandler.get(), operation: get' +
+            (useDedup ? ' deduplicated' : '') +
+            ' ' +
+            this.getTimeoutMs +
+            'ms ' +
+            redisKey,
+          (useDedup ? this.deduplicatedRedisGet(cacheKey) : this.redisGet)(
+            commandOptions({ signal: AbortSignal.timeout(this.getTimeoutMs) }),
+            redisKey,
+          ),
+        );
 
-      // expire is a duration in seconds, calculate absolute expiry time
-      const expiryTime = stored.timestamp + stored.expire * 1000;
-      if (
-        Number.isFinite(stored.expire) &&
-        stored.expire > 0 &&
-        now > expiryTime
-      ) {
-        await this.client.unlink(redisKey).catch(() => {});
-        await this.sharedTagsMap.delete(cacheKey).catch(() => {});
-        return undefined;
-      }
+      let usedDedup = this.redisGetDeduplication;
+      let serialized = await readSerialized(usedDedup);
 
-      const maxRevalidation = await this.computeMaxRevalidation([
-        ...(stored.tags || []),
-        ...(softTags || []),
-      ]);
+      for (let attempt = 0; attempt < 2; attempt++) {
+        if (!serialized) {
+          return undefined;
+        }
 
-      if (maxRevalidation > 0 && maxRevalidation > stored.timestamp) {
-        await this.client.unlink(redisKey).catch(() => {});
-        await this.sharedTagsMap.delete(cacheKey).catch(() => {});
-        return undefined;
-      }
+        const stored: StoredCacheEntry = JSON.parse(serialized);
+        const now = Date.now();
+        const tags = stored.tags || [];
+        const expiryTime = stored.timestamp + stored.expire * 1000;
+        const ttlExpired =
+          Number.isFinite(stored.expire) &&
+          stored.expire > 0 &&
+          now > expiryTime;
+        const tagsExpired = areTagsExpired(tags, stored.timestamp, now, (tag) =>
+          this.tagManifestFor(tag, now),
+        );
 
-      const valueBuffer =
-        typeof stored.value === 'string'
-          ? new Uint8Array(Buffer.from(stored.value, 'base64'))
-          : stored.value;
+        if (ttlExpired || tagsExpired) {
+          if (usedDedup) {
+            usedDedup = false;
+            serialized = await readSerialized(false);
+            continue;
+          }
+
+          const dropped = await compareAndUnlink(
+            this.client,
+            redisKey,
+            serialized,
+          );
+          if (dropped) {
+            await this.sharedTagsMap.delete(cacheKey).catch(() => {});
+          }
+          return undefined;
+        }
 
-      return {
-        ...stored,
-        value: bufferToReadableStream(valueBuffer),
-      };
+        const valueBuffer =
+          typeof stored.value === 'string'
+            ? new Uint8Array(Buffer.from(stored.value, 'base64'))
+            : stored.value;
+
+        const entry: CacheComponentsEntry = {
+          ...stored,
+          value: bufferToReadableStream(valueBuffer),
+        };
+
+        if (
+          areTagsStale(tags, stored.timestamp, (tag) =>
+            this.tagManifestFor(tag, now),
+          )
+        ) {
+          entry.revalidate = -1;
+        }
+
+        return entry;
+      }
+
+      return undefined;
     } catch (error) {
       console.error(
         'RedisCacheComponentsHandler.get() Error occurred while getting cache entry. Returning undefined so site can continue to serve content while cache is disabled. The original error was:',
@@ -364,6 +411,9 @@ class RedisCacheComponentsHandler implements CacheComponentsHandler {
   ): Promise<void> {
     try {
       await this.assertClientIsReady();
+      if (this.isClientUnavailable()) {
+        return;
+      }
 
       const entry = await pendingEntry;
 
@@ -451,7 +501,7 @@ class RedisCacheComponentsHandler implements CacheComponentsHandler {
   async getExpiration(tags: string[]): Promise<number> {
     try {
       await this.assertClientIsReady();
-      return this.computeMaxRevalidation(tags || []);
+      return maxExpiredTimestamp(tags || [], (tag) => this.tagManifestFor(tag));
     } catch (error) {
       console.error(
         'RedisCacheComponentsHandler.getExpiration() Error occurred while getting expiration for tags. The original error was:',
@@ -463,51 +513,31 @@ class RedisCacheComponentsHandler implements CacheComponentsHandler {
 
   async updateTags(
     tags: string[],
-    _durations?: { expire?: number },
+    durations?: { expire?: number },
   ): Promise<void> {
     try {
-      // Mark optional argument as used to satisfy lint rules while keeping the signature
-      void _durations;
       await this.assertClientIsReady();
-      const now = Date.now();
-
-      const tagsSet = new Set(tags || []);
-
-      for (const tag of tagsSet) {
-        await this.revalidatedTagsMap.set(tag, now);
-      }
-
-      const keysToDelete: Set<string> = new Set();
-
-      for (const [key, storedTags] of this.sharedTagsMap.entries()) {
-        if (storedTags.some((tag) => tagsSet.has(tag))) {
-          keysToDelete.add(key);
-        }
-      }
-
-      if (keysToDelete.size === 0) {
+      if (this.isClientUnavailable()) {
         return;
       }
 
-      const cacheKeys = Array.from(keysToDelete);
-
-      // Construct full Redis keys (same format as in get/set)
-      const fullRedisKeys = cacheKeys.map((key) => `${this.keyPrefix}${key}`);
-
-      await redisErrorHandler(
-        'RedisCacheComponentsHandler.updateTags(), operation: unlink',
-        this.client.unlink(fullRedisKeys),
-      );
+      const now = Date.now();
+      const updated = new Set(tags || []);
+      for (const tag of updated) {
+        const next = applyTagUpdate(this.tagManifestFor(tag), durations, now);
+        await this.revalidatedTagsMap.set(
+          tag,
+          persistableTagManifest(next, now),
+        );
+      }
 
       if (this.redisGetDeduplication && this.inMemoryCachingTime > 0) {
-        for (const key of keysToDelete) {
-          this.inMemoryDeduplicationCache.delete(key);
+        for (const [key, sharedTags] of this.sharedTagsMap.entries()) {
+          if (sharedTags.some((tag) => updated.has(tag))) {
+            await this.inMemoryDeduplicationCache.delete(key, true);
+          }
         }
       }
-
-      // Delete from sharedTagsMap
-      const deleteTagsOperation = this.sharedTagsMap.delete(cacheKeys);
-      await deleteTagsOperation;
     } catch (error) {
       console.error(
         'RedisCacheComponentsHandler.updateTags() Error occurred while updating tags. The original error was:',

package/src/RedisStringsHandler.ts

@@ -3,6 +3,8 @@ import { SyncedMap } from './SyncedMap';
 import { DeduplicatedRequestHandler } from './DeduplicatedRequestHandler';
 import { debug } from './utils/debug';
 import { CacheValueSerializer, jsonCacheValueSerializer } from './serializer';
+import { resolveCacheEntryTtlSeconds } from './utils/cacheTtl';
+import { shouldDeferRedisConnection } from './utils/redisConnection';
 
 export type CommandOptions = ReturnType<typeof commandOptions>;
 export type Client = ReturnType<typeof createClient>;
@@ -262,6 +264,7 @@ export default class RedisStringsHandler {
   private estimateExpireAge: (staleAge: number) => number;
   private killContainerOnErrorThreshold: number;
   private valueSerializer: CacheValueSerializer;
+  private redisConnectionDeferred: boolean;
 
   constructor({
     redisUrl = process.env.REDIS_URL
@@ -301,6 +304,7 @@ export default class RedisStringsHandler {
       this.killContainerOnErrorThreshold = killContainerOnErrorThreshold;
       this.getTimeoutMs = getTimeoutMs;
       this.valueSerializer = valueSerializer;
+      this.redisConnectionDeferred = shouldDeferRedisConnection();
 
       try {
         // Create Redis client with properly typed configuration
@@ -348,15 +352,17 @@ export default class RedisStringsHandler {
           }
         });
 
-        this.client
-          .connect()
-          .then(() => {
-            debug('green', 'Redis client connected.');
-          })
-          .catch((error) => {
-            console.error('Failed to connect Redis client:', error);
-            throw error;
-          });
+        if (!this.redisConnectionDeferred) {
+          this.client
+            .connect()
+            .then(() => {
+              debug('green', 'Redis client connected.');
+            })
+            .catch((error) => {
+              console.error('Failed to connect Redis client:', error);
+              throw error;
+            });
+        }
       } catch (error: unknown) {
         console.error('Failed to initialize Redis client');
         throw error;
@@ -385,6 +391,7 @@ export default class RedisStringsHandler {
         database,
         querySize: revalidateTagQuerySize,
         filterKeys,
+        customizedSync: { withoutOrphanCleanup: true },
         resyncIntervalMs:
           avgResyncIntervalMs +
           avgResyncIntervalMs / 10 +
@@ -472,12 +479,19 @@ export default class RedisStringsHandler {
     }
     this.clientReadyCalls = 0;
     if (!this.client.isReady) {
+      if (this.redisConnectionDeferred) {
+        return;
+      }
       throw new Error(
         'assertClientIsReady: Redis client is not ready yet or connection is lost.',
       );
     }
   }
 
+  private isClientUnavailable(): boolean {
+    return this.redisConnectionDeferred || !this.client.isReady;
+  }
+
   public async get(key: string, ctx: GetContext): Promise<CacheEntry | null> {
     try {
       if (!(SUPPORTED_GET_KINDS as readonly string[]).includes(ctx.kind)) {
@@ -492,6 +506,9 @@ export default class RedisStringsHandler {
 
       debug('green', 'RedisStringsHandler.get() called with', key, ctx);
       await this.assertClientIsReady();
+      if (this.isClientUnavailable()) {
+        return null;
+      }
 
       const clientGet = this.redisGetDeduplication
         ? this.deduplicatedRedisGet(key)
@@ -704,6 +721,9 @@ export default class RedisStringsHandler {
       }
 
       await this.assertClientIsReady();
+      if (this.isClientUnavailable()) {
+        return;
+      }
 
       if (data?.kind === 'APP_PAGE' || data?.kind === 'APP_ROUTE') {
         const tags = data.headers['x-next-cache-tags']?.split(',');
@@ -739,21 +759,10 @@ export default class RedisStringsHandler {
         );
       }
 
-      // TODO: implement expiration based on cacheControl.expire argument, -> probably relevant for cacheLife and "use cache" etc.: https://nextjs.org/docs/app/api-reference/functions/cacheLife
-      // 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) ||
-        ctx.revalidate ||
-        ctx.cacheControl?.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)
-          : this.estimateExpireAge(this.defaultStaleAge);
+      const expireAt = resolveCacheEntryTtlSeconds(ctx, data, {
+        estimateExpireAge: this.estimateExpireAge,
+        defaultStaleAge: this.defaultStaleAge,
+      });
 
       // Setting the cache entry in redis
       const setOperation: Promise<string | null> = redisErrorHandler(
@@ -762,7 +771,7 @@ export default class RedisStringsHandler {
           ' ' +
           key,
         this.client.set(this.keyPrefix + key, serializedCacheEntry, {
-          EX: expireAt,
+          ...(expireAt ? { EX: expireAt } : {}),
         }),
       );
 
@@ -838,6 +847,9 @@ export default class RedisStringsHandler {
       );
       const tags = new Set([tagOrTags || []].flat());
       await this.assertClientIsReady();
+      if (this.isClientUnavailable()) {
+        return;
+      }
 
       // find all keys that are related to this tag
       const keysToDelete: Set<string> = new Set();

package/src/SyncedMap.ts

@@ -1,10 +1,16 @@
 // SyncedMap.ts
 import { Client, redisErrorHandler } from './RedisStringsHandler';
 import { debugVerbose, debug } from './utils/debug';
+import { shouldDeferRedisConnection } from './utils/redisConnection';
 
 type CustomizedSync = {
   withoutRedisHashmap?: boolean;
   withoutSetSync?: boolean;
+  /**
+   * Skip SCAN-based orphan cleanup. Required for maps whose keys are not Redis
+   * string keys (tag manifests). Otherwise startup/resync HDELs every tag.
+   */
+  withoutOrphanCleanup?: boolean;
 };
 
 type SyncedMapOptions = {
@@ -67,6 +73,11 @@ export class SyncedMap<V> {
   }
 
   private async setup() {
+    if (shouldDeferRedisConnection()) {
+      this.setupLockResolve();
+      return;
+    }
+
     let setupPromises: Promise<void>[] = [];
     if (!this.customizedSync?.withoutRedisHashmap) {
       setupPromises.push(this.initialSync());
@@ -109,8 +120,11 @@ export class SyncedMap<V> {
         cursor = remoteItems.cursor;
       } while (cursor !== 0);
 
-      // Clean up keys not in Redis
-      await this.cleanupKeysNotInRedis();
+      // sharedTagsMap keys are cache keys (Redis strings). Tag-manifest maps
+      // use tag names as hash fields — those never appear in SCAN.
+      if (!this.customizedSync?.withoutOrphanCleanup) {
+        await this.cleanupKeysNotInRedis();
+      }
     } catch (error) {
       console.error('Error during initial sync:', error);
       throw error;

package/src/index.ts

@@ -8,6 +8,13 @@ export type { CreateRedisStringsHandlerOptions } from './RedisStringsHandler';
 export { jsonCacheValueSerializer } from './serializer';
 export type { CacheValueSerializer } from './serializer';
 export { bufferAndMapReplacer, bufferAndMapReviver } from './utils/json';
+export { resolveCacheEntryTtlSeconds } from './utils/cacheTtl';
+export type {
+  ResolveCacheEntryTtlContext,
+  ResolveCacheEntryTtlData,
+  ResolveCacheEntryTtlOptions,
+} from './utils/cacheTtl';
+export { shouldDeferRedisConnection } from './utils/redisConnection';
 
 import {
   redisCacheHandler,