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

package/src/SyncedMap.ts

@@ -1,482 +0,0 @@
-// SyncedMap.ts
-import { Client, redisErrorHandler } from './RedisStringsHandler';
-import { debugVerbose, debug } from './utils/debug';
-
-type CustomizedSync = {
-  withoutRedisHashmap?: boolean;
-  withoutSetSync?: 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() {
-    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);
-
-      // Clean up keys not in Redis
-      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,16 +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';
-
-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/debug.ts

@@ -1,30 +0,0 @@
-export function debug(
-  color:
-    | 'red'
-    | 'blue'
-    | 'green'
-    | 'yellow'
-    | 'cyan'
-    | 'white'
-    | 'none' = 'none',
-  ...args: unknown[]
-): void {
-  const colorCode = {
-    red: '\x1b[31m',
-    blue: '\x1b[34m',
-    green: '\x1b[32m',
-    yellow: '\x1b[33m',
-    cyan: '\x1b[36m',
-    white: '\x1b[37m',
-    none: '',
-  };
-  if (process.env.DEBUG_CACHE_HANDLER) {
-    console.log(colorCode[color], 'DEBUG CACHE HANDLER: ', ...args);
-  }
-}
-
-export function debugVerbose(color: string, ...args: unknown[]) {
-  if (process.env.DEBUG_CACHE_HANDLER_VERBOSE_VERBOSE) {
-    console.log('\x1b[35m', 'DEBUG SYNCED MAP: ', ...args);
-  }
-}

package/src/utils/json.ts

@@ -1,49 +0,0 @@
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function bufferAndMapReviver(_: string, value: any): any {
-  if (value && typeof value === 'object' && typeof value.$binary === 'string') {
-    return Buffer.from(value.$binary, 'base64');
-  }
-  if (
-    value &&
-    typeof value === 'object' &&
-    typeof value.$map === 'object' &&
-    !!value.$map
-  ) {
-    return new Map(
-      Object.entries(value.$map).map(([key, value]) => {
-        const revivedValue = bufferAndMapReviver('', value);
-        return [key, revivedValue];
-      }),
-    );
-  }
-  return value;
-}
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function bufferAndMapReplacer(_: string, value: any): any {
-  if (Buffer.isBuffer(value)) {
-    return {
-      $binary: value.toString('base64'),
-    };
-  }
-  if (
-    value &&
-    typeof value === 'object' &&
-    value?.type === 'Buffer' &&
-    Array.isArray(value.data)
-  ) {
-    return {
-      $binary: Buffer.from(value.data).toString('base64'),
-    };
-  }
-  if (value && typeof value === 'object' && value instanceof Map) {
-    return {
-      $map: Object.fromEntries(
-        Array.from(value.entries()).map(([key, value]) => {
-          const replacedValue = bufferAndMapReplacer('', value);
-          return [key, replacedValue];
-        }),
-      ),
-    };
-  }
-  return value;
-}