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

package/src/SyncedMap.ts

@@ -1,496 +0,0 @@
-// 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 = {
-  client: Client;
-  keyPrefix: string;
-  redisKey: string; // Redis Hash key
-  database: number;
-  querySize: number;
-  filterKeys: (key: string) => boolean;
-  resyncIntervalMs?: number;
-  customizedSync?: CustomizedSync;
-};
-
-export type SyncMessage<V> = {
-  type: 'insert' | 'delete';
-  key?: string;
-  value?: V;
-  keys?: string[];
-};
-
-const SYNC_CHANNEL_SUFFIX = ':sync-channel:';
-export class SyncedMap<V> {
-  private client: Client;
-  private subscriberClient: Client;
-  private map: Map<string, V>;
-  private keyPrefix: string;
-  private syncChannel: string;
-  private redisKey: string;
-  private database: number;
-  private querySize: number;
-  private filterKeys: (key: string) => boolean;
-  private resyncIntervalMs?: number;
-  private customizedSync?: CustomizedSync;
-
-  private setupLock: Promise<void>;
-  private setupLockResolve!: () => void;
-  private isReconnecting = false;
-
-  constructor(options: SyncedMapOptions) {
-    this.client = options.client;
-    this.keyPrefix = options.keyPrefix;
-    this.redisKey = options.redisKey;
-    this.syncChannel = `${options.keyPrefix}${SYNC_CHANNEL_SUFFIX}${options.redisKey}`;
-    this.database = options.database;
-    this.querySize = options.querySize;
-    this.filterKeys = options.filterKeys;
-    this.resyncIntervalMs = options.resyncIntervalMs;
-    this.customizedSync = options.customizedSync;
-
-    this.map = new Map<string, V>();
-    this.subscriberClient = this.client.duplicate();
-    this.setupLock = new Promise<void>((resolve) => {
-      this.setupLockResolve = resolve;
-    });
-
-    this.setup().catch((error) => {
-      console.error('Failed to setup SyncedMap:', error);
-      throw error;
-    });
-  }
-
-  private async setup() {
-    if (shouldDeferRedisConnection()) {
-      this.setupLockResolve();
-      return;
-    }
-
-    let setupPromises: Promise<void>[] = [];
-    if (!this.customizedSync?.withoutRedisHashmap) {
-      setupPromises.push(this.initialSync());
-      this.setupPeriodicResync();
-    }
-    setupPromises.push(this.setupPubSub());
-    await Promise.all(setupPromises);
-    this.setupLockResolve();
-  }
-
-  private async initialSync() {
-    let cursor = 0;
-    const hScanOptions = { COUNT: this.querySize };
-
-    try {
-      do {
-        const remoteItems = await redisErrorHandler(
-          'SyncedMap.initialSync(), operation: hScan ' +
-            this.syncChannel +
-            ' ' +
-            this.keyPrefix +
-            ' ' +
-            this.redisKey +
-            ' ' +
-            cursor +
-            ' ' +
-            this.querySize,
-          this.client.hScan(
-            this.keyPrefix + this.redisKey,
-            cursor,
-            hScanOptions,
-          ),
-        );
-        for (const { field, value } of remoteItems.tuples) {
-          if (this.filterKeys(field)) {
-            const parsedValue = JSON.parse(value);
-            this.map.set(field, parsedValue);
-          }
-        }
-        cursor = remoteItems.cursor;
-      } while (cursor !== 0);
-
-      // 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;
-    }
-  }
-
-  private async cleanupKeysNotInRedis() {
-    let cursor = 0;
-    const scanOptions = { COUNT: this.querySize, MATCH: `${this.keyPrefix}*` };
-    let remoteKeys: string[] = [];
-    try {
-      do {
-        const remoteKeysPortion = await redisErrorHandler(
-          'SyncedMap.cleanupKeysNotInRedis(), operation: scan ' +
-            this.keyPrefix,
-          this.client.scan(cursor, scanOptions),
-        );
-        remoteKeys = remoteKeys.concat(remoteKeysPortion.keys);
-        cursor = remoteKeysPortion.cursor;
-      } while (cursor !== 0);
-
-      const remoteKeysSet = new Set(
-        remoteKeys.map((key) => key.substring(this.keyPrefix.length)),
-      );
-
-      const keysToDelete: string[] = [];
-      for (const key of this.map.keys()) {
-        const keyStr = key as unknown as string;
-        if (!remoteKeysSet.has(keyStr) && this.filterKeys(keyStr)) {
-          keysToDelete.push(keyStr);
-        }
-      }
-
-      if (keysToDelete.length > 0) {
-        await this.delete(keysToDelete);
-      }
-    } catch (error) {
-      console.error('Error during cleanup of keys not in Redis:', error);
-      throw error;
-    }
-  }
-
-  private setupPeriodicResync() {
-    if (this.resyncIntervalMs && this.resyncIntervalMs > 0) {
-      setInterval(() => {
-        this.initialSync().catch((error) => {
-          console.error('Error during periodic resync:', error);
-        });
-      }, this.resyncIntervalMs);
-    }
-  }
-
-  private async setupPubSub() {
-    const syncHandler = async (message: string) => {
-      const syncMessage: SyncMessage<V> = JSON.parse(message);
-      if (syncMessage.type === 'insert') {
-        if (syncMessage.key !== undefined && syncMessage.value !== undefined) {
-          this.map.set(syncMessage.key, syncMessage.value);
-        }
-      } else if (syncMessage.type === 'delete') {
-        if (syncMessage.keys) {
-          for (const key of syncMessage.keys) {
-            this.map.delete(key);
-          }
-        }
-      }
-    };
-
-    const keyEventHandler = async (key: string, message: string) => {
-      debug(
-        'yellow',
-        'SyncedMap.keyEventHandler() called with message',
-        this.redisKey,
-        message,
-        key,
-      );
-      // const key = message;
-      if (key.startsWith(this.keyPrefix)) {
-        const keyInMap = key.substring(this.keyPrefix.length);
-        if (this.filterKeys(keyInMap)) {
-          debugVerbose(
-            'SyncedMap.keyEventHandler() key matches filter and will be deleted',
-            this.redisKey,
-            message,
-            key,
-          );
-          await this.delete(keyInMap, true);
-        }
-      } else {
-        debugVerbose(
-          'SyncedMap.keyEventHandler() key does not have prefix',
-          this.redisKey,
-          message,
-          key,
-        );
-      }
-    };
-
-    try {
-      // Attach error handler BEFORE subscribing so that errors during
-      // subscribe or after connection loss are always caught and trigger
-      // a reconnection. Previously this was attached after the subscribe()
-      // calls, which meant if subscribe threw during an outage the handler
-      // was never attached and the subscriber was permanently dead.
-      this.subscriberClient.on('error', async (err) => {
-        console.error('Subscriber client error:', err);
-        await this.reconnectSubscriber();
-      });
-
-      const connectIfNeeded = async () => {
-        // Avoid overlapping connect() calls which can lead to
-        // "Socket already opened" errors when a connect is already in progress
-        // or the socket is still open.
-        if (!this.subscriberClient.isOpen && !this.subscriberClient.isReady) {
-          await this.subscriberClient.connect();
-        }
-      };
-
-      await connectIfNeeded().catch(async (error) => {
-        console.error('Failed to connect subscriber client. Retrying...');
-        try {
-          await connectIfNeeded();
-        } catch (err) {
-          console.error('Failed to connect subscriber client.', err);
-          throw err;
-        }
-        // keep original error in logs for context
-        void error;
-      });
-
-      // Check if keyspace event configuration is set correctly
-      if (
-        (process.env.SKIP_KEYSPACE_CONFIG_CHECK || '').toUpperCase() !== 'TRUE'
-      ) {
-        const keyspaceEventConfig = (
-          await this.subscriberClient.configGet('notify-keyspace-events')
-        )?.['notify-keyspace-events'];
-        if (!keyspaceEventConfig.includes('E')) {
-          throw new Error(
-            'Keyspace event configuration is set to "' +
-              keyspaceEventConfig +
-              " but has to include 'E' for Keyevent events, " +
-              'published with __keyevent@<db>__ prefix. We recommend to set it to ' +
-              "'Exe' like so `redis-cli -h localhost config set notify-keyspace-events Exe`",
-          );
-        }
-        if (
-          !keyspaceEventConfig.includes('A') &&
-          !(
-            keyspaceEventConfig.includes('x') &&
-            keyspaceEventConfig.includes('e')
-          )
-        ) {
-          throw new Error(
-            'Keyspace event configuration is set to "' +
-              keyspaceEventConfig +
-              " but has to include 'A' or 'x' and 'e' for expired and " +
-              'evicted events. We recommend to set it to ' +
-              "'Exe' like so `redis-cli -h localhost config set notify-keyspace-events Exe`",
-          );
-        }
-      }
-
-      await Promise.all([
-        // We use a custom channel for insert/delete For the following reason:
-        // With custom channel we can delete multiple entries in one message. If we would listen to unlink / del we
-        // could get thousands of messages for one revalidateTag (For example revalidateTag("algolia") would send an enormous amount of network packages)
-        // Also we can send the value in the message for insert
-        this.subscriberClient.subscribe(this.syncChannel, syncHandler),
-        // Subscribe to Redis keyevent notifications for evicted and expired keys
-        this.subscriberClient.subscribe(
-          `__keyevent@${this.database}__:evicted`,
-          keyEventHandler,
-        ),
-        this.subscriberClient.subscribe(
-          `__keyevent@${this.database}__:expired`,
-          keyEventHandler,
-        ),
-      ]);
-    } catch (error) {
-      console.error('Error setting up pub/sub client:', error);
-      throw error;
-    }
-  }
-
-  /**
-   * Reconnect the subscriber client with exponential backoff.
-   * Guarded by `isReconnecting` to prevent concurrent reconnection
-   * attempts when multiple error events fire during an outage.
-   * Retries indefinitely (with capped delay) so the subscriber
-   * eventually recovers once Redis is available again.
-   */
-  private async reconnectSubscriber(): Promise<void> {
-    if (this.isReconnecting) return;
-    this.isReconnecting = true;
-
-    try {
-      let attempt = 0;
-      while (true) {
-        try {
-          // Forcibly tear down the old subscriber so its internal reconnect
-          // loop cannot come back to life once Redis recovers. `quit()` waits
-          // for the server and can silently fail during an outage, leaving a
-          // zombie client that still fires our error handler. Remove that
-          // handler first so a delayed error from the old socket cannot tear
-          // down the replacement subscriber we are about to create.
-          try {
-            this.subscriberClient.removeAllListeners('error');
-            await this.subscriberClient.disconnect();
-          } catch {
-            // expected during outage
-          }
-          // Create a fresh subscriber client
-          this.subscriberClient = this.client.duplicate();
-          await this.setupPubSub();
-          return; // success
-        } catch (error) {
-          const delay = Math.min(
-            500 * Math.pow(2, Math.min(attempt, 5)),
-            10_000,
-          );
-          attempt++;
-          console.error(
-            `Subscriber reconnect attempt ${attempt} failed, retrying in ${delay}ms`,
-            error,
-          );
-          await new Promise((r) => setTimeout(r, delay));
-        }
-      }
-    } finally {
-      this.isReconnecting = false;
-    }
-  }
-
-  public async waitUntilReady() {
-    await this.setupLock;
-  }
-
-  public get(key: string): V | undefined {
-    debugVerbose(
-      'SyncedMap.get() called with key',
-      key,
-      JSON.stringify(this.map.get(key))?.substring(0, 100),
-    );
-    return this.map.get(key);
-  }
-
-  public async set(key: string, value: V): Promise<void> {
-    debugVerbose(
-      'SyncedMap.set() called with key',
-      key,
-      JSON.stringify(value)?.substring(0, 100),
-    );
-    this.map.set(key, value);
-    const operations = [];
-
-    // This is needed if we only want to sync delete commands. This is especially useful for non serializable data like a promise map
-    if (this.customizedSync?.withoutSetSync) {
-      return;
-    }
-    if (!this.customizedSync?.withoutRedisHashmap) {
-      operations.push(
-        redisErrorHandler(
-          'SyncedMap.set(), operation: hSet ' +
-            this.syncChannel +
-            ' ' +
-            this.keyPrefix +
-            ' ' +
-            key,
-          this.client.hSet(
-            this.keyPrefix + this.redisKey,
-            key as unknown as string,
-            JSON.stringify(value),
-          ),
-        ),
-      );
-    }
-
-    const insertMessage: SyncMessage<V> = {
-      type: 'insert',
-      key: key as unknown as string,
-      value,
-    };
-    operations.push(
-      redisErrorHandler(
-        'SyncedMap.set(), operation: publish ' +
-          this.syncChannel +
-          ' ' +
-          this.keyPrefix +
-          ' ' +
-          key,
-        this.client.publish(this.syncChannel, JSON.stringify(insertMessage)),
-      ),
-    );
-    await Promise.all(operations);
-  }
-
-  public async delete(
-    keys: string[] | string,
-    withoutSyncMessage = false,
-  ): Promise<void> {
-    debugVerbose(
-      'SyncedMap.delete() called with keys',
-      this.redisKey,
-      keys,
-      withoutSyncMessage,
-    );
-
-    const keysArray = Array.isArray(keys) ? keys : [keys];
-    const operations = [];
-
-    for (const key of keysArray) {
-      this.map.delete(key);
-    }
-
-    if (!this.customizedSync?.withoutRedisHashmap) {
-      operations.push(
-        redisErrorHandler(
-          'SyncedMap.delete(), operation: hDel ' +
-            this.syncChannel +
-            ' ' +
-            this.keyPrefix +
-            ' ' +
-            this.redisKey +
-            ' ' +
-            keysArray,
-          this.client.hDel(this.keyPrefix + this.redisKey, keysArray),
-        ),
-      );
-    }
-
-    if (!withoutSyncMessage) {
-      const deletionMessage: SyncMessage<V> = {
-        type: 'delete',
-        keys: keysArray,
-      };
-      operations.push(
-        redisErrorHandler(
-          'SyncedMap.delete(), operation: publish ' +
-            this.syncChannel +
-            ' ' +
-            this.keyPrefix +
-            ' ' +
-            keysArray,
-          this.client.publish(
-            this.syncChannel,
-            JSON.stringify(deletionMessage),
-          ),
-        ),
-      );
-    }
-
-    await Promise.all(operations);
-    debugVerbose(
-      'SyncedMap.delete() finished operations',
-      this.redisKey,
-      keys,
-      operations.length,
-    );
-  }
-
-  public has(key: string): boolean {
-    return this.map.has(key);
-  }
-
-  public entries(): IterableIterator<[string, V]> {
-    return this.map.entries();
-  }
-}

package/src/ZodHandler.ts

@@ -1,45 +0,0 @@
-/**
- * This handler is used to validate the arguments of the get, set, revalidateTag methods against a zod schema.
- * This is mainly used to test new nextjs versions and to ensure that the arguments are still valid. As we
- * saw in the past, that arguments against the cache handler changed between different nextjs versions very often (even between patch versions).
- */
-
-import RedisStringsHandler, {
-  CreateRedisStringsHandlerOptions,
-} from './RedisStringsHandler';
-import { debugVerbose } from './utils/debug';
-
-let cachedHandler: RedisStringsHandler;
-
-export default class CachedHandler {
-  constructor(options: CreateRedisStringsHandlerOptions) {
-    if (!cachedHandler) {
-      console.log('created development cached handler');
-      cachedHandler = new RedisStringsHandler(options);
-    }
-  }
-  get(
-    ...args: Parameters<RedisStringsHandler['get']>
-  ): ReturnType<RedisStringsHandler['get']> {
-    debugVerbose('CachedHandler.get called with', args);
-    return cachedHandler.get(...args);
-  }
-  set(
-    ...args: Parameters<RedisStringsHandler['set']>
-  ): ReturnType<RedisStringsHandler['set']> {
-    debugVerbose('CachedHandler.set called with', args);
-    return cachedHandler.set(...args);
-  }
-  revalidateTag(
-    ...args: Parameters<RedisStringsHandler['revalidateTag']>
-  ): ReturnType<RedisStringsHandler['revalidateTag']> {
-    debugVerbose('CachedHandler.revalidateTag called with', args);
-    return cachedHandler.revalidateTag(...args);
-  }
-  resetRequestCache(
-    ...args: Parameters<RedisStringsHandler['resetRequestCache']>
-  ): ReturnType<RedisStringsHandler['resetRequestCache']> {
-    // debug("CachedHandler.resetRequestCache called with", args);
-    return cachedHandler.resetRequestCache(...args);
-  }
-}

package/src/index.ts

@@ -1,23 +0,0 @@
-import CachedHandler from './CachedHandler';
-export default CachedHandler;
-
-import RedisStringsHandler from './RedisStringsHandler';
-export { RedisStringsHandler };
-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,
-  getRedisCacheComponentsHandler,
-} from './CacheComponentsHandler';
-export { redisCacheHandler, getRedisCacheComponentsHandler };

package/src/serializer.ts

@@ -1,59 +0,0 @@
-/**
- * Pluggable wire-format codec for Redis string values used by `RedisStringsHandler`.
- *
- * The serializer is the single point at which an in-memory `CacheEntry` becomes the
- * string written to Redis (and back). Plugging in a custom serializer lets you add
- * compression (gzip/brotli), encryption, or any other custom encoding without forking
- * this package or losing the existing dedup / batch / keyspace features.
- *
- * Both `serialize` and `deserialize` may return either a value directly or a `Promise`,
- * which enables non-blocking async codecs such as stream-based compression
- * (`zlib.brotliCompress`) or encryption (`crypto.subtle`). Synchronous implementations
- * continue to work unchanged - awaiting a plain value is a no-op.
- *
- * The default export {@link jsonCacheValueSerializer} is `JSON.stringify` /
- * `JSON.parse` paired with {@link bufferAndMapReplacer} / {@link bufferAndMapReviver},
- * so native `Buffer` and `Map` values inside a `CacheEntry` round-trip transparently
- * (this is required for Next.js RSC payloads).
- *
- * Operational note: changing the serializer (or any of its parameters such as a
- * compression level or encryption key) makes existing Redis keys unreadable, because
- * the deserializer will fail or return `null` for entries written by the previous
- * format. Either flush the affected keys, bump `keyPrefix`, or migrate values
- * out-of-band before deploying a new serializer.
- */
-import type { CacheEntry } from './RedisStringsHandler';
-import { bufferAndMapReplacer, bufferAndMapReviver } from './utils/json';
-
-export type CacheValueSerializer = {
-  /**
-   * Encode an in-memory `CacheEntry` into the string written to Redis.
-   * May return a `Promise` for async codecs (e.g. compression, encryption).
-   */
-  serialize(value: CacheEntry): string | Promise<string>;
-  /**
-   * Decode a string read from Redis back into a `CacheEntry`.
-   * Returning `null` (or a `Promise<null>`) signals "treat as cache miss" -
-   * the handler will return `null` from `get()` without surfacing an error.
-   * May return a `Promise` for async codecs.
-   */
-  deserialize(stored: string): CacheEntry | null | Promise<CacheEntry | null>;
-};
-
-/**
- * Default serializer used by `RedisStringsHandler` when no `valueSerializer` is
- * configured. Wraps `JSON.stringify` / `JSON.parse` with this package's
- * {@link bufferAndMapReplacer} / {@link bufferAndMapReviver} so native `Buffer`
- * and `Map` values inside a `CacheEntry` survive the round-trip.
- *
- * Exported as a singleton so consumers can compare against the default by
- * reference (e.g. to detect that no custom serializer was configured).
- */
-export const jsonCacheValueSerializer: CacheValueSerializer = {
-  serialize(value) {
-    return JSON.stringify(value, bufferAndMapReplacer);
-  },
-  deserialize(stored) {
-    return JSON.parse(stored, bufferAndMapReviver) as CacheEntry | null;
-  },
-};

package/src/utils/cacheTtl.ts

@@ -1,71 +0,0 @@
-export type ResolveCacheEntryTtlContext = {
-  revalidate?: number | false;
-  cacheControl?: { revalidate?: number | false; expire?: number | undefined };
-};
-
-export type ResolveCacheEntryTtlData = {
-  kind?: string;
-  revalidate?: number | false;
-} | null;
-
-export type ResolveCacheEntryTtlOptions = {
-  estimateExpireAge: (staleAge: number) => number;
-  defaultStaleAge: number;
-};
-
-/**
- * Resolves the Redis TTL (seconds) for an ISR / incremental-cache entry.
- *
- * Official Next.js semantics (cache-handler-redis example + self-hosting docs):
- * - Key TTL on `cacheControl.expire`, never on `revalidate` alone.
- * - Past `revalidate` an entry is only stale (SWR); evicting at that boundary
- *   would defeat background refresh.
- * - When no finite `expire` is provided, fall back to `estimateExpireAge(revalidate)`
- *   for legacy Pages Router / pre-cacheLife callers that only pass `revalidate`.
- * - When neither `expire` nor `revalidate` is available, return `undefined` (no TTL;
- *   rely on tag-based invalidation). This is intentional — not a missing
- *   `defaultStaleAge` fallback. `revalidate: false` is a separate branch above
- *   and is covered by unit + Pages Router integration tests (`/static-forever`).
- */
-export function resolveCacheEntryTtlSeconds(
-  ctx: ResolveCacheEntryTtlContext,
-  data: ResolveCacheEntryTtlData,
-  options: ResolveCacheEntryTtlOptions,
-): number | undefined {
-  const expire = ctx.cacheControl?.expire;
-
-  if (Number.isFinite(expire) && expire! > 0) {
-    return Math.max(1, Math.ceil(expire!));
-  }
-
-  const revalidate = resolveRevalidateValue(ctx, data);
-
-  if (revalidate === false) {
-    return options.estimateExpireAge(options.defaultStaleAge);
-  }
-
-  if (revalidate && Number.isSafeInteger(revalidate) && revalidate > 0) {
-    return options.estimateExpireAge(revalidate);
-  }
-
-  return undefined;
-}
-
-function resolveRevalidateValue(
-  ctx: ResolveCacheEntryTtlContext,
-  data: ResolveCacheEntryTtlData,
-): number | false | undefined {
-  if (data?.kind === 'FETCH' && data.revalidate !== undefined) {
-    return data.revalidate;
-  }
-  if (ctx.revalidate !== undefined) {
-    return ctx.revalidate;
-  }
-  if (ctx.cacheControl?.revalidate !== undefined) {
-    return ctx.cacheControl.revalidate;
-  }
-  if (data?.revalidate !== undefined) {
-    return data.revalidate;
-  }
-  return undefined;
-}