layercache 1.2.2 → 1.2.3

package/README.md

@@ -6,7 +6,7 @@
 [![npm downloads](https://img.shields.io/npm/dw/layercache)](https://www.npmjs.com/package/layercache)
 [![license](https://img.shields.io/npm/l/layercache)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-first-blue)](https://www.typescriptlang.org/)
-[![test coverage](https://img.shields.io/badge/tests-164%20passing-brightgreen)](https://github.com/flyingsquirrel0419/layercache)
+[![test coverage](https://img.shields.io/badge/tests-180%20passing-brightgreen)](https://github.com/flyingsquirrel0419/layercache)
 
 ```
 L1 hit  ~0.01 ms  ← served from memory, zero network
@@ -45,7 +45,7 @@ On a hit, the value is returned from the fastest layer that has it, and automati
 - **Batch tag invalidation** — `invalidateByTags(['tenant:a', 'users'], 'all')` for OR/AND invalidation in one call
 - **Pattern invalidation** — `invalidateByPattern('user:*')`
 - **Prefix invalidation** — efficient `invalidateByPrefix('user:123:')` for hierarchical keys
-- **Generation-based invalidation** — `generation` prefixes keys with `vN:` and `bumpGeneration()` rotates the namespace instantly
+- **Generation-based invalidation** — `generation` prefixes keys with `vN:` and `bumpGeneration()` rotates the namespace instantly, with optional stale-generation cleanup
 - **Per-layer TTL overrides** — different TTLs for memory vs. Redis in one call
 - **TTL policies** — align TTLs to time boundaries (`until-midnight`, `next-hour`, `{ alignTo }`, or a function)
 - **Negative caching** — cache known misses for a short TTL to protect the database
@@ -84,7 +84,7 @@ On a hit, the value is returned from the fastest layer that has it, and automati
 - **Nested namespaces** — `namespace('a').namespace('b')` for composable key prefixes with namespace-scoped metrics
 - **Custom layers** — implement the 5-method `CacheLayer` interface to plug in Memcached, DynamoDB, or anything else
 - **Edge-safe entry point** — `layercache/edge` exports the non-Node helpers for Worker-style runtimes
-- **ESM + CJS** — works with both module systems, Node.js ≥ 18
+- **ESM + CJS** — works with both module systems, Node.js ≥ 20
 
 ---
 
@@ -173,7 +173,7 @@ await cache.set('user:123', user, {
 
 ### `cache.invalidateByTag(tag): Promise<void>`
 
-Deletes every key that was stored with this tag across all layers.
+Deletes every key that was stored with this tag across all layers. In multi-instance deployments, this is only complete when every instance shares the same tag index implementation (for example `RedisTagIndex`).
 
 ```ts
 await cache.set('user:123',       user,  { tags: ['user:123'] })
@@ -193,12 +193,14 @@ await cache.invalidateByTags(['users', 'posts'], 'any')    // keys tagged with e
 
 ### `cache.invalidateByPattern(pattern): Promise<void>`
 
-Glob-style deletion against the tracked key set.
+Glob-style deletion against the tracked key set, plus any layer that can enumerate real keys (for example `MemoryLayer`, `RedisLayer`, or `DiskLayer`).
 
 ```ts
 await cache.invalidateByPattern('user:*') // deletes user:1, user:2, …
 ```
 
+For multi-instance deployments, prefer a shared `RedisTagIndex`. Without it, pattern invalidation still scans real layer keys when available, but that fallback only helps on layers that implement `keys()`, and tag tracking itself remains process-local.
+
 ### `cache.invalidateByPrefix(prefix): Promise<void>`
 
 Prefer this over glob invalidation when your keys are hierarchical.
@@ -280,6 +282,17 @@ await cache.set('user:123', user)
 cache.bumpGeneration() // now reads use v2:user:123
 ```
 
+If you also want old generation keys cleaned up automatically instead of waiting for TTL expiry:
+
+```ts
+const cache = new CacheStack([...], {
+  generation: 1,
+  generationCleanup: { batchSize: 500 }
+})
+```
+
+`bumpGeneration()` only rotates future reads and writes by default. Enable `generationCleanup` when you want previous generations to be pruned automatically instead of aging out by TTL.
+
 ### OpenTelemetry note
 
 `createOpenTelemetryPlugin()` currently wraps a `CacheStack` instance's methods directly. Use one OpenTelemetry plugin per cache instance; if you need to compose multiple wrappers, install them in a fixed order and uninstall them in reverse order.
@@ -482,10 +495,10 @@ const cache = new CacheStack(
 await cache.disconnect() // unsubscribes cleanly on shutdown
 ```
 
-By default, every `set` also broadcasts an invalidation so other servers evict stale memory immediately. To suppress broadcasts on writes (high write-volume services):
+By default, write-triggered L1 invalidation is **off** even when an invalidation bus is configured. This avoids surprising Redis Pub/Sub traffic in write-heavy services. Enable it explicitly when you want every write to evict peer memory caches immediately:
 
 ```ts
-new CacheStack([...], { invalidationBus: bus, publishSetInvalidation: false })
+new CacheStack([...], { invalidationBus: bus, broadcastL1Invalidation: true })
 ```
 
 ### Distributed tag invalidation
@@ -510,6 +523,8 @@ const cache = new CacheStack(
 
 Now `invalidateByTag('user:123')` on any server deletes every tagged key, regardless of which server originally wrote it.
 
+The same recommendation applies to `invalidateByPattern()` and `invalidateByPrefix()` in distributed deployments: a shared tag index gives the most complete view of known keys, while layer key scans act as a fallback only when the shared layer exposes `keys()`.
+
 ### Safe Redis clearing
 
 `RedisLayer.clear()` is intentionally conservative. Without a `prefix`, it throws instead of deleting the whole Redis database.
@@ -622,6 +637,8 @@ await cache.get('leaderboard', fetchLeaderboard, {
 })
 ```
 
+Background refreshes time out after 30 seconds by default so a hung upstream fetch cannot block future refresh attempts forever. Override that with `backgroundRefreshTimeoutMs`.
+
 ---
 
 ## Graceful degradation & circuit breaker
@@ -718,6 +735,8 @@ await cache.persistToFile('./cache-snapshot.json')
 await cache.restoreFromFile('./cache-snapshot.json')
 ```
 
+For safety, file snapshots are restricted to `process.cwd()` by default. Set `snapshotBaseDir` to an explicit directory for application-controlled snapshot storage, or `false` if you intentionally want to disable that restriction.
+
 ---
 
 ## Event hooks
@@ -1019,7 +1038,7 @@ new CacheStack([...], {
 
 ## Requirements
 
-- Node.js ≥ 18
+- Node.js ≥ 20
 - TypeScript ≥ 5.0 (optional — fully typed, ships `.d.ts`)
 - ioredis ≥ 5 (optional peer dependency — only needed for `RedisLayer` / `RedisTagIndex`)
 

package/dist/{chunk-ZMDB5KOK.js → chunk-7V7XAB74.js}

@@ -1,6 +1,29 @@
 // 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 createStoredValueEnvelope(options) {
   const now = options.now ?? Date.now();

package/dist/{chunk-46UH7LNM.js → chunk-KOYGHLVP.js}

@@ -1,7 +1,6 @@
 import {
-  PatternMatcher,
   unwrapStoredValue
-} from "./chunk-ZMDB5KOK.js";
+} from "./chunk-7V7XAB74.js";
 
 // src/layers/MemoryLayer.ts
 var MemoryLayer = class {
@@ -49,16 +48,10 @@ var MemoryLayer = class {
     return entry.value;
   }
   async getMany(keys) {
-    const values = [];
-    for (const key of keys) {
-      values.push(await this.getEntry(key));
-    }
-    return values;
+    return Promise.all(keys.map((key) => this.getEntry(key)));
   }
   async setMany(entries) {
-    for (const entry of entries) {
-      await this.set(entry.key, entry.value, entry.ttl);
-    }
+    await Promise.all(entries.map((entry) => this.set(entry.key, entry.value, entry.ttl)));
   }
   async set(key, value, ttl = this.defaultTtl) {
     this.entries.delete(key);
@@ -197,15 +190,17 @@ var TagIndex = class {
   keyToTags = /* @__PURE__ */ new Map();
   knownKeys = /* @__PURE__ */ new Set();
   maxKnownKeys;
+  nextNodeId = 1;
+  root = this.createTrieNode();
   constructor(options = {}) {
-    this.maxKnownKeys = options.maxKnownKeys;
+    this.maxKnownKeys = options.maxKnownKeys ?? 1e5;
   }
   async touch(key) {
-    this.knownKeys.add(key);
+    this.insertKnownKey(key);
     this.pruneKnownKeysIfNeeded();
   }
   async track(key, tags) {
-    this.knownKeys.add(key);
+    this.insertKnownKey(key);
     this.pruneKnownKeysIfNeeded();
     if (tags.length === 0) {
       return;
@@ -231,18 +226,104 @@ var TagIndex = class {
     return [...this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()];
   }
   async keysForPrefix(prefix) {
-    return [...this.knownKeys].filter((key) => key.startsWith(prefix));
+    const node = this.findNode(prefix);
+    if (!node) {
+      return [];
+    }
+    const matches = [];
+    this.collectFromNode(node, prefix, matches);
+    return matches;
   }
   async tagsForKey(key) {
     return [...this.keyToTags.get(key) ?? /* @__PURE__ */ new Set()];
   }
   async matchPattern(pattern) {
-    return [...this.knownKeys].filter((key) => PatternMatcher.matches(pattern, key));
+    const matches = /* @__PURE__ */ new Set();
+    this.collectPatternMatches(this.root, "", pattern, 0, matches, /* @__PURE__ */ new Set());
+    return [...matches];
   }
   async clear() {
     this.tagToKeys.clear();
     this.keyToTags.clear();
     this.knownKeys.clear();
+    this.root.children.clear();
+    this.root.terminal = false;
+    this.nextNodeId = this.root.id + 1;
+  }
+  createTrieNode() {
+    return {
+      id: this.nextNodeId++,
+      terminal: false,
+      children: /* @__PURE__ */ new Map()
+    };
+  }
+  insertKnownKey(key) {
+    if (this.knownKeys.has(key)) {
+      return;
+    }
+    this.knownKeys.add(key);
+    let node = this.root;
+    for (const character of key) {
+      let child = node.children.get(character);
+      if (!child) {
+        child = this.createTrieNode();
+        node.children.set(character, child);
+      }
+      node = child;
+    }
+    node.terminal = true;
+  }
+  findNode(prefix) {
+    let node = this.root;
+    for (const character of prefix) {
+      node = node.children.get(character);
+      if (!node) {
+        return void 0;
+      }
+    }
+    return node;
+  }
+  collectFromNode(node, prefix, matches) {
+    if (node.terminal) {
+      matches.push(prefix);
+    }
+    for (const [character, child] of node.children) {
+      this.collectFromNode(child, `${prefix}${character}`, matches);
+    }
+  }
+  collectPatternMatches(node, prefix, pattern, patternIndex, matches, visited) {
+    const stateKey = `${node.id}:${patternIndex}`;
+    if (visited.has(stateKey)) {
+      return;
+    }
+    visited.add(stateKey);
+    if (patternIndex === pattern.length) {
+      if (node.terminal) {
+        matches.add(prefix);
+      }
+      return;
+    }
+    const patternChar = pattern[patternIndex];
+    if (patternChar === void 0) {
+      return;
+    }
+    if (patternChar === "*") {
+      this.collectPatternMatches(node, prefix, pattern, patternIndex + 1, matches, visited);
+      for (const [character, child2] of node.children) {
+        this.collectPatternMatches(child2, `${prefix}${character}`, pattern, patternIndex, matches, visited);
+      }
+      return;
+    }
+    if (patternChar === "?") {
+      for (const [character, child2] of node.children) {
+        this.collectPatternMatches(child2, `${prefix}${character}`, pattern, patternIndex + 1, matches, visited);
+      }
+      return;
+    }
+    const child = node.children.get(patternChar);
+    if (child) {
+      this.collectPatternMatches(child, `${prefix}${patternChar}`, pattern, patternIndex + 1, matches, visited);
+    }
   }
   pruneKnownKeysIfNeeded() {
     if (this.maxKnownKeys === void 0 || this.knownKeys.size <= this.maxKnownKeys) {
@@ -259,7 +340,7 @@ var TagIndex = class {
     }
   }
   removeKey(key) {
-    this.knownKeys.delete(key);
+    this.removeKnownKey(key);
     const tags = this.keyToTags.get(key);
     if (!tags) {
       return;
@@ -276,6 +357,34 @@ var TagIndex = class {
     }
     this.keyToTags.delete(key);
   }
+  removeKnownKey(key) {
+    if (!this.knownKeys.delete(key)) {
+      return;
+    }
+    const path = [];
+    let node = this.root;
+    for (const character of key) {
+      const child = node.children.get(character);
+      if (!child) {
+        return;
+      }
+      path.push([node, character]);
+      node = child;
+    }
+    node.terminal = false;
+    for (let index = path.length - 1; index >= 0; index -= 1) {
+      const entry = path[index];
+      if (!entry) {
+        continue;
+      }
+      const [parent, character] = entry;
+      const child = parent.children.get(character);
+      if (!child || child.terminal || child.children.size > 0) {
+        break;
+      }
+      parent.children.delete(character);
+    }
+  }
 };
 
 // src/integrations/hono.ts
@@ -287,7 +396,8 @@ function createHonoCacheMiddleware(cache, options = {}) {
       await next();
       return;
     }
-    const key = options.keyResolver ? options.keyResolver(context.req) : `${method}:${context.req.path ?? context.req.url ?? "/"}`;
+    const rawPath = context.req.path ?? context.req.url ?? "/";
+    const key = options.keyResolver ? options.keyResolver(context.req) : `${method}:${normalizeUrl(rawPath)}`;
     const cached = await cache.get(key, void 0, options);
     if (cached !== null) {
       context.header?.("x-cache", "HIT");
@@ -298,12 +408,26 @@ function createHonoCacheMiddleware(cache, options = {}) {
     const originalJson = context.json.bind(context);
     context.json = (body, status) => {
       context.header?.("x-cache", "MISS");
-      void cache.set(key, body, options);
+      cache.set(key, body, options).catch((err) => {
+        cache.emit("error", {
+          operation: "set",
+          error: err instanceof Error ? err.message : String(err)
+        });
+      });
       return originalJson(body, status);
     };
     await next();
   };
 }
+function normalizeUrl(url) {
+  try {
+    const parsed = new URL(url, "http://localhost");
+    parsed.searchParams.sort();
+    return decodeURIComponent(parsed.pathname) + parsed.search;
+  } catch {
+    return url;
+  }
+}
 
 export {
   MemoryLayer,

package/dist/{chunk-IXCMHVHP.js → chunk-QHWG7QS5.js}

@@ -1,6 +1,6 @@
 import {
   PatternMatcher
-} from "./chunk-ZMDB5KOK.js";
+} from "./chunk-7V7XAB74.js";
 
 // src/invalidation/RedisTagIndex.ts
 var RedisTagIndex = class {

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)) {
@@ -259,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;
@@ -273,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 ?? "*");
@@ -428,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-IXCMHVHP.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-DLpdQN0W.d.ts → edge-B_rUqDy6.d.cts}

@@ -177,6 +177,7 @@ interface CacheStackOptions {
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
     generation?: number;
+    generationCleanup?: boolean | CacheGenerationCleanupOptions;
     broadcastL1Invalidation?: boolean;
     /**
      * @deprecated Use `broadcastL1Invalidation` instead.
@@ -195,11 +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.
@@ -212,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);
@@ -415,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;
 }
@@ -424,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>;
@@ -433,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 {
@@ -505,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;
@@ -513,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);
@@ -523,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.
@@ -581,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,
@@ -608,6 +630,7 @@ declare class CacheStack extends EventEmitter {
     private resolveLayerSeconds;
     private shouldNegativeCache;
     private scheduleBackgroundRefresh;
+    private runBackgroundRefresh;
     private resolveSingleFlightOptions;
     private deleteKeys;
     private publishInvalidation;
@@ -615,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;
@@ -643,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;
 }