layercache 1.2.1 → 1.2.3

package/dist/cli.cjs

@@ -38,7 +38,30 @@ var import_ioredis = __toESM(require("ioredis"), 1);
 
 // src/internal/StoredValue.ts
 function isStoredValueEnvelope(value) {
-  return typeof value === "object" && value !== null && "__layercache" in value && value.__layercache === 1 && "kind" in value;
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const v = value;
+  if (v.__layercache !== 1) {
+    return false;
+  }
+  if (v.kind !== "value" && v.kind !== "empty") {
+    return false;
+  }
+  if (v.freshUntil !== null && typeof v.freshUntil !== "number") {
+    return false;
+  }
+  if (v.staleUntil !== null && typeof v.staleUntil !== "number") {
+    return false;
+  }
+  if (v.errorUntil !== null && typeof v.errorUntil !== "number") {
+    return false;
+  }
+  const maxTimestamp = Date.now() + 10 * 365 * 24 * 60 * 60 * 1e3;
+  if (typeof v.freshUntil === "number" && v.freshUntil > maxTimestamp) {
+    return false;
+  }
+  return true;
 }
 function resolveStoredValue(stored, now = Date.now()) {
   if (!isStoredValueEnvelope(stored)) {
@@ -118,19 +141,21 @@ var RedisTagIndex = class {
   client;
   prefix;
   scanCount;
+  knownKeysShards;
   constructor(options) {
     this.client = options.client;
     this.prefix = options.prefix ?? "layercache:tag-index";
     this.scanCount = options.scanCount ?? 100;
+    this.knownKeysShards = normalizeKnownKeysShards(options.knownKeysShards);
   }
   async touch(key) {
-    await this.client.sadd(this.knownKeysKey(), key);
+    await this.client.sadd(this.knownKeysKeyFor(key), key);
   }
   async track(key, tags) {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
     const pipeline = this.client.pipeline();
-    pipeline.sadd(this.knownKeysKey(), key);
+    pipeline.sadd(this.knownKeysKeyFor(key), key);
     for (const tag of existingTags) {
       pipeline.srem(this.tagKeysKey(tag), key);
     }
@@ -147,7 +172,7 @@ var RedisTagIndex = class {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
     const pipeline = this.client.pipeline();
-    pipeline.srem(this.knownKeysKey(), key);
+    pipeline.srem(this.knownKeysKeyFor(key), key);
     pipeline.del(keyTagsKey);
     for (const tag of existingTags) {
       pipeline.srem(this.tagKeysKey(tag), key);
@@ -159,12 +184,14 @@ var RedisTagIndex = class {
   }
   async keysForPrefix(prefix) {
     const matches = [];
-    let cursor = "0";
-    do {
-      const [nextCursor, keys] = await this.client.sscan(this.knownKeysKey(), cursor, "COUNT", this.scanCount);
-      cursor = nextCursor;
-      matches.push(...keys.filter((key) => key.startsWith(prefix)));
-    } while (cursor !== "0");
+    for (const knownKeysKey of this.knownKeysKeys()) {
+      let cursor = "0";
+      do {
+        const [nextCursor, keys] = await this.client.sscan(knownKeysKey, cursor, "COUNT", this.scanCount);
+        cursor = nextCursor;
+        matches.push(...keys.filter((key) => key.startsWith(prefix)));
+      } while (cursor !== "0");
+    }
     return matches;
   }
   async tagsForKey(key) {
@@ -172,19 +199,21 @@ var RedisTagIndex = class {
   }
   async matchPattern(pattern) {
     const matches = [];
-    let cursor = "0";
-    do {
-      const [nextCursor, keys] = await this.client.sscan(
-        this.knownKeysKey(),
-        cursor,
-        "MATCH",
-        pattern,
-        "COUNT",
-        this.scanCount
-      );
-      cursor = nextCursor;
-      matches.push(...keys.filter((key) => PatternMatcher.matches(pattern, key)));
-    } while (cursor !== "0");
+    for (const knownKeysKey of this.knownKeysKeys()) {
+      let cursor = "0";
+      do {
+        const [nextCursor, keys] = await this.client.sscan(
+          knownKeysKey,
+          cursor,
+          "MATCH",
+          pattern,
+          "COUNT",
+          this.scanCount
+        );
+        cursor = nextCursor;
+        matches.push(...keys.filter((key) => PatternMatcher.matches(pattern, key)));
+      } while (cursor !== "0");
+    }
     return matches;
   }
   async clear() {
@@ -205,8 +234,17 @@ var RedisTagIndex = class {
     } while (cursor !== "0");
     return matches;
   }
-  knownKeysKey() {
-    return `${this.prefix}:keys`;
+  knownKeysKeyFor(key) {
+    if (this.knownKeysShards === 1) {
+      return `${this.prefix}:keys`;
+    }
+    return `${this.prefix}:keys:${simpleHash(key) % this.knownKeysShards}`;
+  }
+  knownKeysKeys() {
+    if (this.knownKeysShards === 1) {
+      return [`${this.prefix}:keys`];
+    }
+    return Array.from({ length: this.knownKeysShards }, (_, index) => `${this.prefix}:keys:${index}`);
   }
   keyTagsKey(key) {
     return `${this.prefix}:key:${encodeURIComponent(key)}`;
@@ -215,6 +253,22 @@ var RedisTagIndex = class {
     return `${this.prefix}:tag:${encodeURIComponent(tag)}`;
   }
 };
+function normalizeKnownKeysShards(value) {
+  if (value === void 0) {
+    return 1;
+  }
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error("RedisTagIndex.knownKeysShards must be a positive integer.");
+  }
+  return value;
+}
+function simpleHash(value) {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = hash * 31 + value.charCodeAt(index) >>> 0;
+  }
+  return hash;
+}
 
 // src/cli.ts
 var CONNECT_TIMEOUT_MS = 5e3;
@@ -228,7 +282,7 @@ async function main(argv = process.argv.slice(2)) {
   const redisUrl = validateRedisUrl(args.redisUrl);
   if (!redisUrl) {
     process.stderr.write(
-      `Error: invalid Redis URL "${args.redisUrl}". Expected format: redis://[user:password@]host[:port][/db]
+      `Error: invalid Redis URL "${maskRedisUrl(args.redisUrl)}". Expected format: redis://[user:password@]host[:port][/db]
 `
     );
     process.exitCode = 1;
@@ -242,7 +296,7 @@ async function main(argv = process.argv.slice(2)) {
   try {
     await redis.connect().catch((error) => {
       const message = error instanceof Error ? error.message : String(error);
-      throw new Error(`Failed to connect to Redis at "${redisUrl}": ${message}`);
+      throw new Error(`Failed to connect to Redis at "${maskRedisUrl(redisUrl)}": ${message}`);
     });
     if (args.command === "stats") {
       const keys = await scanKeys(redis, args.pattern ?? "*");
@@ -397,6 +451,17 @@ function summarizeInspectableValue(value) {
   }
   return value;
 }
+function maskRedisUrl(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.password) {
+      parsed.password = "***";
+    }
+    return parsed.toString();
+  } catch {
+    return url.replace(/:([^@/]+)@/, ":***@");
+  }
+}
 if (process.argv[1]?.includes("cli.")) {
   void main();
 }

package/dist/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import {
   RedisTagIndex
-} from "./chunk-GF47Y3XR.js";
+} from "./chunk-QHWG7QS5.js";
 import {
   isStoredValueEnvelope,
   resolveStoredValue
-} from "./chunk-ZMDB5KOK.js";
+} from "./chunk-7V7XAB74.js";
 
 // src/cli.ts
 import Redis from "ioredis";
@@ -20,7 +20,7 @@ async function main(argv = process.argv.slice(2)) {
   const redisUrl = validateRedisUrl(args.redisUrl);
   if (!redisUrl) {
     process.stderr.write(
-      `Error: invalid Redis URL "${args.redisUrl}". Expected format: redis://[user:password@]host[:port][/db]
+      `Error: invalid Redis URL "${maskRedisUrl(args.redisUrl)}". Expected format: redis://[user:password@]host[:port][/db]
 `
     );
     process.exitCode = 1;
@@ -34,7 +34,7 @@ async function main(argv = process.argv.slice(2)) {
   try {
     await redis.connect().catch((error) => {
       const message = error instanceof Error ? error.message : String(error);
-      throw new Error(`Failed to connect to Redis at "${redisUrl}": ${message}`);
+      throw new Error(`Failed to connect to Redis at "${maskRedisUrl(redisUrl)}": ${message}`);
     });
     if (args.command === "stats") {
       const keys = await scanKeys(redis, args.pattern ?? "*");
@@ -189,6 +189,17 @@ function summarizeInspectableValue(value) {
   }
   return value;
 }
+function maskRedisUrl(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.password) {
+      parsed.password = "***";
+    }
+    return parsed.toString();
+  } catch {
+    return url.replace(/:([^@/]+)@/, ":***@");
+  }
+}
 if (process.argv[1]?.includes("cli.")) {
   void main();
 }

package/dist/{edge-C1sBhTfv.d.ts → edge-B_rUqDy6.d.cts}

@@ -165,6 +165,7 @@ interface CacheSingleFlightExecutionOptions {
     leaseMs: number;
     waitTimeoutMs: number;
     pollIntervalMs: number;
+    renewIntervalMs?: number;
 }
 interface CacheSingleFlightCoordinator {
     execute<T>(key: string, options: CacheSingleFlightExecutionOptions, worker: () => Promise<T>, waiter: () => Promise<T>): Promise<T>;
@@ -176,6 +177,7 @@ interface CacheStackOptions {
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
     generation?: number;
+    generationCleanup?: boolean | CacheGenerationCleanupOptions;
     broadcastL1Invalidation?: boolean;
     /**
      * @deprecated Use `broadcastL1Invalidation` instead.
@@ -194,10 +196,13 @@ interface CacheStackOptions {
     writeStrategy?: 'write-through' | 'write-behind';
     writeBehind?: CacheWriteBehindOptions;
     fetcherRateLimit?: CacheRateLimitOptions;
+    backgroundRefreshTimeoutMs?: number;
     singleFlightCoordinator?: CacheSingleFlightCoordinator;
     singleFlightLeaseMs?: number;
     singleFlightTimeoutMs?: number;
     singleFlightPollMs?: number;
+    singleFlightRenewIntervalMs?: number;
+    snapshotBaseDir?: string | false;
     /**
      * Maximum number of entries in `accessProfiles` and `circuitBreakers` maps
      * before the oldest entries are pruned. Prevents unbounded memory growth.
@@ -210,6 +215,9 @@ interface CacheAdaptiveTtlOptions {
     step?: number | LayerTtlMap;
     maxTtl?: number | LayerTtlMap;
 }
+interface CacheGenerationCleanupOptions {
+    batchSize?: number;
+}
 type CacheTtlPolicy = 'until-midnight' | 'next-hour' | {
     alignTo: number;
 } | ((context: CacheTtlPolicyContext) => number | undefined);
@@ -228,6 +236,8 @@ interface CacheRateLimitOptions {
     maxConcurrent?: number;
     intervalMs?: number;
     maxPerInterval?: number;
+    scope?: 'global' | 'key' | 'fetcher';
+    bucketKey?: string;
 }
 interface CacheWriteBehindOptions {
     flushIntervalMs?: number;
@@ -411,7 +421,7 @@ interface TagIndexOptions {
     /**
      * Maximum number of keys tracked in `knownKeys`. When exceeded, the oldest
      * 10 % of keys are pruned to keep memory bounded.
-     * Defaults to unlimited.
+     * Defaults to 100,000.
      */
     maxKnownKeys?: number;
 }
@@ -420,6 +430,8 @@ declare class TagIndex implements CacheTagIndex {
     private readonly keyToTags;
     private readonly knownKeys;
     private readonly maxKnownKeys;
+    private nextNodeId;
+    private readonly root;
     constructor(options?: TagIndexOptions);
     touch(key: string): Promise<void>;
     track(key: string, tags: string[]): Promise<void>;
@@ -429,8 +441,14 @@ declare class TagIndex implements CacheTagIndex {
     tagsForKey(key: string): Promise<string[]>;
     matchPattern(pattern: string): Promise<string[]>;
     clear(): Promise<void>;
+    private createTrieNode;
+    private insertKnownKey;
+    private findNode;
+    private collectFromNode;
+    private collectPatternMatches;
     private pruneKnownKeysIfNeeded;
     private removeKey;
+    private removeKnownKey;
 }
 
 declare class CacheNamespace {
@@ -501,6 +519,7 @@ declare class CacheStack extends EventEmitter {
     private readonly logger;
     private readonly tagIndex;
     private readonly fetchRateLimiter;
+    private readonly snapshotSerializer;
     private readonly backgroundRefreshes;
     private readonly layerDegradedUntil;
     private readonly ttlResolver;
@@ -509,6 +528,7 @@ declare class CacheStack extends EventEmitter {
     private readonly writeBehindQueue;
     private writeBehindTimer?;
     private writeBehindFlushPromise?;
+    private generationCleanupPromise?;
     private isDisconnecting;
     private disconnectPromise?;
     constructor(layers: CacheLayer[], options?: CacheStackOptions);
@@ -519,6 +539,7 @@ declare class CacheStack extends EventEmitter {
      * and no `fetcher` is provided.
      */
     get<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
+    private getPrepared;
     /**
      * Alias for `get(key, fetcher, options)` — explicit get-or-set pattern.
      * Fetches and caches the value if not already present.
@@ -577,6 +598,11 @@ declare class CacheStack extends EventEmitter {
      */
     getHitRate(): CacheHitRateSnapshot;
     healthCheck(): Promise<CacheHealthCheckResult[]>;
+    /**
+     * Rotates the active generation prefix used for all future cache keys.
+     * Previous-generation keys remain in the underlying layers until they expire,
+     * unless `generationCleanup` is enabled to prune them in the background.
+     */
     bumpGeneration(nextGeneration?: number): number;
     /**
      * Returns detailed metadata about a single cache key: which layers contain it,
@@ -604,6 +630,7 @@ declare class CacheStack extends EventEmitter {
     private resolveLayerSeconds;
     private shouldNegativeCache;
     private scheduleBackgroundRefresh;
+    private runBackgroundRefresh;
     private resolveSingleFlightOptions;
     private deleteKeys;
     private publishInvalidation;
@@ -611,7 +638,14 @@ declare class CacheStack extends EventEmitter {
     private getTagsForKey;
     private formatError;
     private sleep;
+    private withTimeout;
     private shouldBroadcastL1Invalidation;
+    private collectKeysWithPrefix;
+    private collectKeysMatchingPattern;
+    private shouldCleanupGenerations;
+    private generationCleanupBatchSize;
+    private scheduleGenerationCleanup;
+    private cleanupGeneration;
     private initializeWriteBehind;
     private shouldWriteBehind;
     private enqueueWriteBehind;
@@ -627,6 +661,7 @@ declare class CacheStack extends EventEmitter {
     private validateWriteOptions;
     private validateLayerNumberOption;
     private validatePositiveNumber;
+    private validateRateLimitOptions;
     private validateNonNegativeNumber;
     private validateCacheKey;
     private validateTtlPolicy;
@@ -638,12 +673,15 @@ declare class CacheStack extends EventEmitter {
     private applyFreshReadPolicies;
     private shouldSkipLayer;
     private handleLayerFailure;
+    private reportRecoverableLayerFailure;
     private isGracefulDegradationEnabled;
     private recordCircuitFailure;
     private isNegativeStoredValue;
     private emitError;
     private serializeKeyPart;
     private isCacheSnapshotEntries;
+    private sanitizeSnapshotValue;
+    private validateSnapshotFilePath;
     private normalizeForSerialization;
 }
 

package/dist/{edge-C1sBhTfv.d.cts → edge-B_rUqDy6.d.ts}

@@ -165,6 +165,7 @@ interface CacheSingleFlightExecutionOptions {
     leaseMs: number;
     waitTimeoutMs: number;
     pollIntervalMs: number;
+    renewIntervalMs?: number;
 }
 interface CacheSingleFlightCoordinator {
     execute<T>(key: string, options: CacheSingleFlightExecutionOptions, worker: () => Promise<T>, waiter: () => Promise<T>): Promise<T>;
@@ -176,6 +177,7 @@ interface CacheStackOptions {
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
     generation?: number;
+    generationCleanup?: boolean | CacheGenerationCleanupOptions;
     broadcastL1Invalidation?: boolean;
     /**
      * @deprecated Use `broadcastL1Invalidation` instead.
@@ -194,10 +196,13 @@ interface CacheStackOptions {
     writeStrategy?: 'write-through' | 'write-behind';
     writeBehind?: CacheWriteBehindOptions;
     fetcherRateLimit?: CacheRateLimitOptions;
+    backgroundRefreshTimeoutMs?: number;
     singleFlightCoordinator?: CacheSingleFlightCoordinator;
     singleFlightLeaseMs?: number;
     singleFlightTimeoutMs?: number;
     singleFlightPollMs?: number;
+    singleFlightRenewIntervalMs?: number;
+    snapshotBaseDir?: string | false;
     /**
      * Maximum number of entries in `accessProfiles` and `circuitBreakers` maps
      * before the oldest entries are pruned. Prevents unbounded memory growth.
@@ -210,6 +215,9 @@ interface CacheAdaptiveTtlOptions {
     step?: number | LayerTtlMap;
     maxTtl?: number | LayerTtlMap;
 }
+interface CacheGenerationCleanupOptions {
+    batchSize?: number;
+}
 type CacheTtlPolicy = 'until-midnight' | 'next-hour' | {
     alignTo: number;
 } | ((context: CacheTtlPolicyContext) => number | undefined);
@@ -228,6 +236,8 @@ interface CacheRateLimitOptions {
     maxConcurrent?: number;
     intervalMs?: number;
     maxPerInterval?: number;
+    scope?: 'global' | 'key' | 'fetcher';
+    bucketKey?: string;
 }
 interface CacheWriteBehindOptions {
     flushIntervalMs?: number;
@@ -411,7 +421,7 @@ interface TagIndexOptions {
     /**
      * Maximum number of keys tracked in `knownKeys`. When exceeded, the oldest
      * 10 % of keys are pruned to keep memory bounded.
-     * Defaults to unlimited.
+     * Defaults to 100,000.
      */
     maxKnownKeys?: number;
 }
@@ -420,6 +430,8 @@ declare class TagIndex implements CacheTagIndex {
     private readonly keyToTags;
     private readonly knownKeys;
     private readonly maxKnownKeys;
+    private nextNodeId;
+    private readonly root;
     constructor(options?: TagIndexOptions);
     touch(key: string): Promise<void>;
     track(key: string, tags: string[]): Promise<void>;
@@ -429,8 +441,14 @@ declare class TagIndex implements CacheTagIndex {
     tagsForKey(key: string): Promise<string[]>;
     matchPattern(pattern: string): Promise<string[]>;
     clear(): Promise<void>;
+    private createTrieNode;
+    private insertKnownKey;
+    private findNode;
+    private collectFromNode;
+    private collectPatternMatches;
     private pruneKnownKeysIfNeeded;
     private removeKey;
+    private removeKnownKey;
 }
 
 declare class CacheNamespace {
@@ -501,6 +519,7 @@ declare class CacheStack extends EventEmitter {
     private readonly logger;
     private readonly tagIndex;
     private readonly fetchRateLimiter;
+    private readonly snapshotSerializer;
     private readonly backgroundRefreshes;
     private readonly layerDegradedUntil;
     private readonly ttlResolver;
@@ -509,6 +528,7 @@ declare class CacheStack extends EventEmitter {
     private readonly writeBehindQueue;
     private writeBehindTimer?;
     private writeBehindFlushPromise?;
+    private generationCleanupPromise?;
     private isDisconnecting;
     private disconnectPromise?;
     constructor(layers: CacheLayer[], options?: CacheStackOptions);
@@ -519,6 +539,7 @@ declare class CacheStack extends EventEmitter {
      * and no `fetcher` is provided.
      */
     get<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
+    private getPrepared;
     /**
      * Alias for `get(key, fetcher, options)` — explicit get-or-set pattern.
      * Fetches and caches the value if not already present.
@@ -577,6 +598,11 @@ declare class CacheStack extends EventEmitter {
      */
     getHitRate(): CacheHitRateSnapshot;
     healthCheck(): Promise<CacheHealthCheckResult[]>;
+    /**
+     * Rotates the active generation prefix used for all future cache keys.
+     * Previous-generation keys remain in the underlying layers until they expire,
+     * unless `generationCleanup` is enabled to prune them in the background.
+     */
     bumpGeneration(nextGeneration?: number): number;
     /**
      * Returns detailed metadata about a single cache key: which layers contain it,
@@ -604,6 +630,7 @@ declare class CacheStack extends EventEmitter {
     private resolveLayerSeconds;
     private shouldNegativeCache;
     private scheduleBackgroundRefresh;
+    private runBackgroundRefresh;
     private resolveSingleFlightOptions;
     private deleteKeys;
     private publishInvalidation;
@@ -611,7 +638,14 @@ declare class CacheStack extends EventEmitter {
     private getTagsForKey;
     private formatError;
     private sleep;
+    private withTimeout;
     private shouldBroadcastL1Invalidation;
+    private collectKeysWithPrefix;
+    private collectKeysMatchingPattern;
+    private shouldCleanupGenerations;
+    private generationCleanupBatchSize;
+    private scheduleGenerationCleanup;
+    private cleanupGeneration;
     private initializeWriteBehind;
     private shouldWriteBehind;
     private enqueueWriteBehind;
@@ -627,6 +661,7 @@ declare class CacheStack extends EventEmitter {
     private validateWriteOptions;
     private validateLayerNumberOption;
     private validatePositiveNumber;
+    private validateRateLimitOptions;
     private validateNonNegativeNumber;
     private validateCacheKey;
     private validateTtlPolicy;
@@ -638,12 +673,15 @@ declare class CacheStack extends EventEmitter {
     private applyFreshReadPolicies;
     private shouldSkipLayer;
     private handleLayerFailure;
+    private reportRecoverableLayerFailure;
     private isGracefulDegradationEnabled;
     private recordCircuitFailure;
     private isNegativeStoredValue;
     private emitError;
     private serializeKeyPart;
     private isCacheSnapshotEntries;
+    private sanitizeSnapshotValue;
+    private validateSnapshotFilePath;
     private normalizeForSerialization;
 }