layercache 1.2.5 → 1.2.6

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

@@ -10,19 +10,47 @@ function isStoredValueEnvelope(value) {
   if (v.kind !== "value" && v.kind !== "empty") {
     return false;
   }
-  if (v.freshUntil !== null && typeof v.freshUntil !== "number") {
+  if (v.freshUntil !== null && (!Number.isFinite(v.freshUntil) || typeof v.freshUntil !== "number")) {
     return false;
   }
-  if (v.staleUntil !== null && typeof v.staleUntil !== "number") {
+  if (v.staleUntil !== null && (!Number.isFinite(v.staleUntil) || typeof v.staleUntil !== "number")) {
     return false;
   }
-  if (v.errorUntil !== null && typeof v.errorUntil !== "number") {
+  if (v.errorUntil !== null && (!Number.isFinite(v.errorUntil) || 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;
   }
+  if (typeof v.staleUntil === "number" && v.staleUntil > maxTimestamp) {
+    return false;
+  }
+  if (typeof v.errorUntil === "number" && v.errorUntil > maxTimestamp) {
+    return false;
+  }
+  if (v.freshUntil === null && (v.staleUntil !== null || v.errorUntil !== null)) {
+    return false;
+  }
+  if (typeof v.freshUntil === "number" && typeof v.staleUntil === "number" && v.staleUntil < v.freshUntil) {
+    return false;
+  }
+  if (typeof v.freshUntil === "number" && typeof v.errorUntil === "number" && v.errorUntil < v.freshUntil) {
+    return false;
+  }
+  const maxTtlSeconds = 10 * 365 * 24 * 60 * 60;
+  if (!isValidEnvelopeTtlSeconds(v.freshTtlSeconds, maxTtlSeconds)) {
+    return false;
+  }
+  if (!isValidEnvelopeTtlSeconds(v.staleWhileRevalidateSeconds, maxTtlSeconds)) {
+    return false;
+  }
+  if (!isValidEnvelopeTtlSeconds(v.staleIfErrorSeconds, maxTtlSeconds)) {
+    return false;
+  }
+  if (v.freshTtlSeconds == null && (v.staleWhileRevalidateSeconds != null || v.staleIfErrorSeconds != null)) {
+    return false;
+  }
   return true;
 }
 function createStoredValueEnvelope(options) {
@@ -121,6 +149,12 @@ function normalizePositiveSeconds(value) {
   }
   return value;
 }
+function isValidEnvelopeTtlSeconds(value, maxTtlSeconds) {
+  if (value == null) {
+    return true;
+  }
+  return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= maxTtlSeconds;
+}
 
 // src/invalidation/PatternMatcher.ts
 var PatternMatcher = class _PatternMatcher {

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

@@ -1,6 +1,6 @@
 import {
   PatternMatcher
-} from "./chunk-7V7XAB74.js";
+} from "./chunk-4PPBOOXT.js";
 
 // src/invalidation/RedisTagIndex.ts
 var RedisTagIndex = class {
@@ -48,6 +48,17 @@ var RedisTagIndex = class {
   async keysForTag(tag) {
     return this.client.smembers(this.tagKeysKey(tag));
   }
+  async forEachKeyForTag(tag, visitor) {
+    let cursor = "0";
+    const tagKey = this.tagKeysKey(tag);
+    do {
+      const [nextCursor, keys] = await this.client.sscan(tagKey, cursor, "COUNT", this.scanCount);
+      cursor = nextCursor;
+      for (const key of keys) {
+        await visitor(key);
+      }
+    } while (cursor !== "0");
+  }
   async keysForPrefix(prefix) {
     const matches = [];
     for (const knownKeysKey of this.knownKeysKeys()) {
@@ -60,6 +71,20 @@ var RedisTagIndex = class {
     }
     return matches;
   }
+  async forEachKeyForPrefix(prefix, visitor) {
+    for (const knownKeysKey of this.knownKeysKeys()) {
+      let cursor = "0";
+      do {
+        const [nextCursor, keys] = await this.client.sscan(knownKeysKey, cursor, "COUNT", this.scanCount);
+        cursor = nextCursor;
+        for (const key of keys) {
+          if (key.startsWith(prefix)) {
+            await visitor(key);
+          }
+        }
+      } while (cursor !== "0");
+    }
+  }
   async tagsForKey(key) {
     return this.client.smembers(this.keyTagsKey(key));
   }
@@ -82,6 +107,27 @@ var RedisTagIndex = class {
     }
     return matches;
   }
+  async forEachKeyMatchingPattern(pattern, visitor) {
+    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;
+        for (const key of keys) {
+          if (PatternMatcher.matches(pattern, key)) {
+            await visitor(key);
+          }
+        }
+      } while (cursor !== "0");
+    }
+  }
   async clear() {
     const indexKeys = await this.scanIndexKeys();
     if (indexKeys.length === 0) {

package/dist/{chunk-JC26W3KK.js → chunk-GJBKCFE6.js}

@@ -1,6 +1,6 @@
 import {
   unwrapStoredValue
-} from "./chunk-7V7XAB74.js";
+} from "./chunk-4PPBOOXT.js";
 
 // src/layers/MemoryLayer.ts
 var MemoryLayer = class {
@@ -118,6 +118,12 @@ var MemoryLayer = class {
     this.pruneExpired();
     return [...this.entries.keys()];
   }
+  async forEachKey(visitor) {
+    this.pruneExpired();
+    for (const key of this.entries.keys()) {
+      await visitor(key);
+    }
+  }
   exportState() {
     this.pruneExpired();
     return [...this.entries.entries()].map(([key, entry]) => ({
@@ -226,6 +232,11 @@ var TagIndex = class {
   async keysForTag(tag) {
     return [...this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()];
   }
+  async forEachKeyForTag(tag, visitor) {
+    for (const key of this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()) {
+      await visitor(key);
+    }
+  }
   async keysForPrefix(prefix) {
     const node = this.findNode(prefix);
     if (!node) {
@@ -235,6 +246,13 @@ var TagIndex = class {
     this.collectFromNode(node, prefix, matches);
     return matches;
   }
+  async forEachKeyForPrefix(prefix, visitor) {
+    const node = this.findNode(prefix);
+    if (!node) {
+      return;
+    }
+    await this.visitFromNode(node, prefix, visitor);
+  }
   async tagsForKey(key) {
     return [...this.keyToTags.get(key) ?? /* @__PURE__ */ new Set()];
   }
@@ -243,6 +261,12 @@ var TagIndex = class {
     this.collectPatternMatches(this.root, "", pattern, 0, matches, /* @__PURE__ */ new Set(), 0);
     return [...matches];
   }
+  async forEachKeyMatchingPattern(pattern, visitor) {
+    const matches = await this.matchPattern(pattern);
+    for (const key of matches) {
+      await visitor(key);
+    }
+  }
   async clear() {
     this.tagToKeys.clear();
     this.keyToTags.clear();
@@ -292,6 +316,14 @@ var TagIndex = class {
       this.collectFromNode(child, `${prefix}${character}`, matches);
     }
   }
+  async visitFromNode(node, prefix, visitor) {
+    if (node.terminal) {
+      await visitor(prefix);
+    }
+    for (const [character, child] of node.children) {
+      await this.visitFromNode(child, `${prefix}${character}`, visitor);
+    }
+  }
   collectPatternMatches(node, prefix, pattern, patternIndex, matches, visited, depth) {
     if (depth > MAX_PATTERN_RECURSION_DEPTH) {
       return;
@@ -416,14 +448,17 @@ function createHonoCacheMiddleware(cache, options = {}) {
       await next();
       return;
     }
+    if (!options.keyResolver && options.allowPrivateCaching !== true) {
+      await next();
+      return;
+    }
     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");
       context.header?.("content-type", "application/json; charset=utf-8");
-      context.json(cached);
-      return;
+      return context.json(cached);
     }
     const originalJson = context.json.bind(context);
     context.json = (body, status) => {

package/dist/cli.cjs

@@ -48,19 +48,47 @@ function isStoredValueEnvelope(value) {
   if (v.kind !== "value" && v.kind !== "empty") {
     return false;
   }
-  if (v.freshUntil !== null && typeof v.freshUntil !== "number") {
+  if (v.freshUntil !== null && (!Number.isFinite(v.freshUntil) || typeof v.freshUntil !== "number")) {
     return false;
   }
-  if (v.staleUntil !== null && typeof v.staleUntil !== "number") {
+  if (v.staleUntil !== null && (!Number.isFinite(v.staleUntil) || typeof v.staleUntil !== "number")) {
     return false;
   }
-  if (v.errorUntil !== null && typeof v.errorUntil !== "number") {
+  if (v.errorUntil !== null && (!Number.isFinite(v.errorUntil) || 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;
   }
+  if (typeof v.staleUntil === "number" && v.staleUntil > maxTimestamp) {
+    return false;
+  }
+  if (typeof v.errorUntil === "number" && v.errorUntil > maxTimestamp) {
+    return false;
+  }
+  if (v.freshUntil === null && (v.staleUntil !== null || v.errorUntil !== null)) {
+    return false;
+  }
+  if (typeof v.freshUntil === "number" && typeof v.staleUntil === "number" && v.staleUntil < v.freshUntil) {
+    return false;
+  }
+  if (typeof v.freshUntil === "number" && typeof v.errorUntil === "number" && v.errorUntil < v.freshUntil) {
+    return false;
+  }
+  const maxTtlSeconds = 10 * 365 * 24 * 60 * 60;
+  if (!isValidEnvelopeTtlSeconds(v.freshTtlSeconds, maxTtlSeconds)) {
+    return false;
+  }
+  if (!isValidEnvelopeTtlSeconds(v.staleWhileRevalidateSeconds, maxTtlSeconds)) {
+    return false;
+  }
+  if (!isValidEnvelopeTtlSeconds(v.staleIfErrorSeconds, maxTtlSeconds)) {
+    return false;
+  }
+  if (v.freshTtlSeconds == null && (v.staleWhileRevalidateSeconds != null || v.staleIfErrorSeconds != null)) {
+    return false;
+  }
   return true;
 }
 function resolveStoredValue(stored, now = Date.now()) {
@@ -87,6 +115,12 @@ function unwrapStoredValue(stored) {
   }
   return stored.value ?? null;
 }
+function isValidEnvelopeTtlSeconds(value, maxTtlSeconds) {
+  if (value == null) {
+    return true;
+  }
+  return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= maxTtlSeconds;
+}
 
 // src/invalidation/PatternMatcher.ts
 var PatternMatcher = class _PatternMatcher {
@@ -182,6 +216,17 @@ var RedisTagIndex = class {
   async keysForTag(tag) {
     return this.client.smembers(this.tagKeysKey(tag));
   }
+  async forEachKeyForTag(tag, visitor) {
+    let cursor = "0";
+    const tagKey = this.tagKeysKey(tag);
+    do {
+      const [nextCursor, keys] = await this.client.sscan(tagKey, cursor, "COUNT", this.scanCount);
+      cursor = nextCursor;
+      for (const key of keys) {
+        await visitor(key);
+      }
+    } while (cursor !== "0");
+  }
   async keysForPrefix(prefix) {
     const matches = [];
     for (const knownKeysKey of this.knownKeysKeys()) {
@@ -194,6 +239,20 @@ var RedisTagIndex = class {
     }
     return matches;
   }
+  async forEachKeyForPrefix(prefix, visitor) {
+    for (const knownKeysKey of this.knownKeysKeys()) {
+      let cursor = "0";
+      do {
+        const [nextCursor, keys] = await this.client.sscan(knownKeysKey, cursor, "COUNT", this.scanCount);
+        cursor = nextCursor;
+        for (const key of keys) {
+          if (key.startsWith(prefix)) {
+            await visitor(key);
+          }
+        }
+      } while (cursor !== "0");
+    }
+  }
   async tagsForKey(key) {
     return this.client.smembers(this.keyTagsKey(key));
   }
@@ -216,6 +275,27 @@ var RedisTagIndex = class {
     }
     return matches;
   }
+  async forEachKeyMatchingPattern(pattern, visitor) {
+    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;
+        for (const key of keys) {
+          if (PatternMatcher.matches(pattern, key)) {
+            await visitor(key);
+          }
+        }
+      } while (cursor !== "0");
+    }
+  }
   async clear() {
     const indexKeys = await this.scanIndexKeys();
     if (indexKeys.length === 0) {

package/dist/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import {
   RedisTagIndex
-} from "./chunk-QHWG7QS5.js";
+} from "./chunk-BQLL6IM5.js";
 import {
   isStoredValueEnvelope,
   resolveStoredValue
-} from "./chunk-7V7XAB74.js";
+} from "./chunk-4PPBOOXT.js";
 
 // src/cli.ts
 import Redis from "ioredis";

package/dist/{edge-P07GCO2Y.d.ts → edge-DLstcDMn.d.cts}

@@ -66,6 +66,7 @@ interface CacheLayer {
     clear(): Promise<void>;
     deleteMany?(keys: string[]): Promise<void>;
     keys?(): Promise<string[]>;
+    forEachKey?(visitor: (key: string) => void | Promise<void>): Promise<void>;
     ping?(): Promise<boolean>;
     dispose?(): Promise<void>;
     /**
@@ -140,10 +141,13 @@ interface CacheTagIndex {
     track(key: string, tags: string[]): Promise<void>;
     remove(key: string): Promise<void>;
     keysForTag(tag: string): Promise<string[]>;
+    forEachKeyForTag?(tag: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
     keysForPrefix?(prefix: string): Promise<string[]>;
+    forEachKeyForPrefix?(prefix: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
     /** Returns the tags associated with a specific key, or an empty array. */
     tagsForKey?(key: string): Promise<string[]>;
     matchPattern(pattern: string): Promise<string[]>;
+    forEachKeyMatchingPattern?(pattern: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
     clear(): Promise<void>;
 }
 interface CacheLayerSetManyEntry {
@@ -203,6 +207,9 @@ interface CacheStackOptions {
     singleFlightPollMs?: number;
     singleFlightRenewIntervalMs?: number;
     snapshotBaseDir?: string | false;
+    snapshotMaxBytes?: number | false;
+    snapshotMaxEntries?: number | false;
+    invalidationMaxKeys?: number | false;
     /**
      * Maximum number of entries in `accessProfiles` and `circuitBreakers` maps
      * before the oldest entries are pruned. Prevents unbounded memory growth.
@@ -396,6 +403,7 @@ declare class MemoryLayer implements CacheLayer {
     ping(): Promise<boolean>;
     dispose(): Promise<void>;
     keys(): Promise<string[]>;
+    forEachKey(visitor: (key: string) => void | Promise<void>): Promise<void>;
     exportState(): MemoryLayerSnapshotEntry[];
     importState(entries: MemoryLayerSnapshotEntry[]): void;
     private evict;
@@ -437,14 +445,18 @@ declare class TagIndex implements CacheTagIndex {
     track(key: string, tags: string[]): Promise<void>;
     remove(key: string): Promise<void>;
     keysForTag(tag: string): Promise<string[]>;
+    forEachKeyForTag(tag: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
     keysForPrefix(prefix: string): Promise<string[]>;
+    forEachKeyForPrefix(prefix: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
     tagsForKey(key: string): Promise<string[]>;
     matchPattern(pattern: string): Promise<string[]>;
+    forEachKeyMatchingPattern(pattern: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
     clear(): Promise<void>;
     private createTrieNode;
     private insertKnownKey;
     private findNode;
     private collectFromNode;
+    private visitFromNode;
     private collectPatternMatches;
     private pruneKnownKeysIfNeeded;
     private removeKey;
@@ -494,6 +506,10 @@ declare class CacheNamespace {
      */
     namespace(childPrefix: string): CacheNamespace;
     qualify(key: string): string;
+    private qualifyTag;
+    private qualifyGetOptions;
+    private qualifyWrapOptions;
+    private qualifyWriteOptions;
     private trackMetrics;
     private getMetricsMutex;
 }
@@ -523,6 +539,7 @@ declare class CacheStack extends EventEmitter {
     private readonly snapshotSerializer;
     private readonly backgroundRefreshes;
     private readonly layerDegradedUntil;
+    private readonly keyEpochs;
     private readonly ttlResolver;
     private readonly circuitBreakerManager;
     private currentGeneration?;
@@ -530,6 +547,7 @@ declare class CacheStack extends EventEmitter {
     private writeBehindTimer?;
     private writeBehindFlushPromise?;
     private generationCleanupPromise?;
+    private clearEpoch;
     private isDisconnecting;
     private disconnectPromise?;
     constructor(layers: CacheLayer[], options?: CacheStackOptions);
@@ -647,6 +665,10 @@ declare class CacheStack extends EventEmitter {
     private cleanupGeneration;
     private initializeWriteBehind;
     private shouldWriteBehind;
+    private beginClearEpoch;
+    private currentKeyEpoch;
+    private bumpKeyEpochs;
+    private isWriteOutdated;
     private enqueueWriteBehind;
     private flushWriteBehindQueue;
     private buildLayerSetEntry;
@@ -658,18 +680,8 @@ declare class CacheStack extends EventEmitter {
     private deleteKeysFromLayers;
     private validateConfiguration;
     private validateWriteOptions;
-    private validateLayerNumberOption;
-    private validatePositiveNumber;
-    private validateRateLimitOptions;
-    private validateNonNegativeNumber;
-    private validateCacheKey;
-    private validatePattern;
-    private validateTtlPolicy;
     private assertActive;
     private awaitStartup;
-    private serializeOptions;
-    private validateAdaptiveTtlOptions;
-    private validateCircuitBreakerOptions;
     private applyFreshReadPolicies;
     private shouldSkipLayer;
     private handleLayerFailure;
@@ -678,11 +690,14 @@ declare class CacheStack extends EventEmitter {
     private recordCircuitFailure;
     private isNegativeStoredValue;
     private emitError;
-    private serializeKeyPart;
     private isCacheSnapshotEntries;
     private sanitizeSnapshotValue;
-    private validateSnapshotFilePath;
-    private normalizeForSerialization;
+    private snapshotMaxBytes;
+    private snapshotMaxEntries;
+    private invalidationMaxKeys;
+    private collectKeysForTag;
+    private assertWithinInvalidationKeyLimit;
+    private visitExportEntries;
 }
 
 interface HonoLikeRequest {
@@ -690,6 +705,8 @@ interface HonoLikeRequest {
     url?: string;
     path?: string;
     query?: Record<string, unknown>;
+    headers?: Headers | Record<string, unknown>;
+    header?: (name: string) => string | undefined;
 }
 interface HonoLikeContext {
     req: HonoLikeRequest;
@@ -699,7 +716,8 @@ interface HonoLikeContext {
 interface HonoCacheMiddlewareOptions extends CacheGetOptions {
     keyResolver?: (request: HonoLikeRequest) => string;
     methods?: string[];
+    allowPrivateCaching?: boolean;
 }
-declare function createHonoCacheMiddleware(cache: CacheStack, options?: HonoCacheMiddlewareOptions): (context: HonoLikeContext, next: () => Promise<void>) => Promise<void>;
+declare function createHonoCacheMiddleware(cache: CacheStack, options?: HonoCacheMiddlewareOptions): (context: HonoLikeContext, next: () => Promise<void>) => Promise<unknown>;
 
 export { type CacheStatsSnapshot as A, type CacheTtlPolicy as B, type CacheLogger as C, type CacheTtlPolicyContext as D, type CacheWarmEntry as E, type CacheWarmOptions as F, type CacheWarmProgress as G, type CacheWriteBehindOptions as H, type InvalidationBus as I, type CacheWriteOptions as J, type EvictionPolicy as K, type LayerTtlMap as L, MemoryLayer as M, type MemoryLayerOptions as N, type MemoryLayerSnapshotEntry as O, PatternMatcher as P, createHonoCacheMiddleware as Q, TagIndex as T, type InvalidationMessage as a, type CacheTagIndex as b, CacheStack as c, type CacheWrapOptions as d, type CacheGetOptions as e, type CacheLayer as f, type CacheSerializer as g, type CacheLayerSetManyEntry as h, type CacheSingleFlightCoordinator as i, type CacheSingleFlightExecutionOptions as j, type CacheAdaptiveTtlOptions as k, type CacheCircuitBreakerOptions as l, type CacheDegradationOptions as m, type CacheHealthCheckResult as n, type CacheHitRateSnapshot as o, type CacheInspectResult as p, type CacheLayerLatency as q, type CacheMGetEntry as r, type CacheMSetEntry as s, type CacheMetricsSnapshot as t, CacheMissError as u, CacheNamespace as v, type CacheRateLimitOptions as w, type CacheSnapshotEntry as x, type CacheStackEvents as y, type CacheStackOptions as z };

package/dist/{edge-P07GCO2Y.d.cts → edge-DLstcDMn.d.ts}

@@ -66,6 +66,7 @@ interface CacheLayer {
     clear(): Promise<void>;
     deleteMany?(keys: string[]): Promise<void>;
     keys?(): Promise<string[]>;
+    forEachKey?(visitor: (key: string) => void | Promise<void>): Promise<void>;
     ping?(): Promise<boolean>;
     dispose?(): Promise<void>;
     /**
@@ -140,10 +141,13 @@ interface CacheTagIndex {
     track(key: string, tags: string[]): Promise<void>;
     remove(key: string): Promise<void>;
     keysForTag(tag: string): Promise<string[]>;
+    forEachKeyForTag?(tag: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
     keysForPrefix?(prefix: string): Promise<string[]>;
+    forEachKeyForPrefix?(prefix: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
     /** Returns the tags associated with a specific key, or an empty array. */
     tagsForKey?(key: string): Promise<string[]>;
     matchPattern(pattern: string): Promise<string[]>;
+    forEachKeyMatchingPattern?(pattern: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
     clear(): Promise<void>;
 }
 interface CacheLayerSetManyEntry {
@@ -203,6 +207,9 @@ interface CacheStackOptions {
     singleFlightPollMs?: number;
     singleFlightRenewIntervalMs?: number;
     snapshotBaseDir?: string | false;
+    snapshotMaxBytes?: number | false;
+    snapshotMaxEntries?: number | false;
+    invalidationMaxKeys?: number | false;
     /**
      * Maximum number of entries in `accessProfiles` and `circuitBreakers` maps
      * before the oldest entries are pruned. Prevents unbounded memory growth.
@@ -396,6 +403,7 @@ declare class MemoryLayer implements CacheLayer {
     ping(): Promise<boolean>;
     dispose(): Promise<void>;
     keys(): Promise<string[]>;
+    forEachKey(visitor: (key: string) => void | Promise<void>): Promise<void>;
     exportState(): MemoryLayerSnapshotEntry[];
     importState(entries: MemoryLayerSnapshotEntry[]): void;
     private evict;
@@ -437,14 +445,18 @@ declare class TagIndex implements CacheTagIndex {
     track(key: string, tags: string[]): Promise<void>;
     remove(key: string): Promise<void>;
     keysForTag(tag: string): Promise<string[]>;
+    forEachKeyForTag(tag: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
     keysForPrefix(prefix: string): Promise<string[]>;
+    forEachKeyForPrefix(prefix: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
     tagsForKey(key: string): Promise<string[]>;
     matchPattern(pattern: string): Promise<string[]>;
+    forEachKeyMatchingPattern(pattern: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
     clear(): Promise<void>;
     private createTrieNode;
     private insertKnownKey;
     private findNode;
     private collectFromNode;
+    private visitFromNode;
     private collectPatternMatches;
     private pruneKnownKeysIfNeeded;
     private removeKey;
@@ -494,6 +506,10 @@ declare class CacheNamespace {
      */
     namespace(childPrefix: string): CacheNamespace;
     qualify(key: string): string;
+    private qualifyTag;
+    private qualifyGetOptions;
+    private qualifyWrapOptions;
+    private qualifyWriteOptions;
     private trackMetrics;
     private getMetricsMutex;
 }
@@ -523,6 +539,7 @@ declare class CacheStack extends EventEmitter {
     private readonly snapshotSerializer;
     private readonly backgroundRefreshes;
     private readonly layerDegradedUntil;
+    private readonly keyEpochs;
     private readonly ttlResolver;
     private readonly circuitBreakerManager;
     private currentGeneration?;
@@ -530,6 +547,7 @@ declare class CacheStack extends EventEmitter {
     private writeBehindTimer?;
     private writeBehindFlushPromise?;
     private generationCleanupPromise?;
+    private clearEpoch;
     private isDisconnecting;
     private disconnectPromise?;
     constructor(layers: CacheLayer[], options?: CacheStackOptions);
@@ -647,6 +665,10 @@ declare class CacheStack extends EventEmitter {
     private cleanupGeneration;
     private initializeWriteBehind;
     private shouldWriteBehind;
+    private beginClearEpoch;
+    private currentKeyEpoch;
+    private bumpKeyEpochs;
+    private isWriteOutdated;
     private enqueueWriteBehind;
     private flushWriteBehindQueue;
     private buildLayerSetEntry;
@@ -658,18 +680,8 @@ declare class CacheStack extends EventEmitter {
     private deleteKeysFromLayers;
     private validateConfiguration;
     private validateWriteOptions;
-    private validateLayerNumberOption;
-    private validatePositiveNumber;
-    private validateRateLimitOptions;
-    private validateNonNegativeNumber;
-    private validateCacheKey;
-    private validatePattern;
-    private validateTtlPolicy;
     private assertActive;
     private awaitStartup;
-    private serializeOptions;
-    private validateAdaptiveTtlOptions;
-    private validateCircuitBreakerOptions;
     private applyFreshReadPolicies;
     private shouldSkipLayer;
     private handleLayerFailure;
@@ -678,11 +690,14 @@ declare class CacheStack extends EventEmitter {
     private recordCircuitFailure;
     private isNegativeStoredValue;
     private emitError;
-    private serializeKeyPart;
     private isCacheSnapshotEntries;
     private sanitizeSnapshotValue;
-    private validateSnapshotFilePath;
-    private normalizeForSerialization;
+    private snapshotMaxBytes;
+    private snapshotMaxEntries;
+    private invalidationMaxKeys;
+    private collectKeysForTag;
+    private assertWithinInvalidationKeyLimit;
+    private visitExportEntries;
 }
 
 interface HonoLikeRequest {
@@ -690,6 +705,8 @@ interface HonoLikeRequest {
     url?: string;
     path?: string;
     query?: Record<string, unknown>;
+    headers?: Headers | Record<string, unknown>;
+    header?: (name: string) => string | undefined;
 }
 interface HonoLikeContext {
     req: HonoLikeRequest;
@@ -699,7 +716,8 @@ interface HonoLikeContext {
 interface HonoCacheMiddlewareOptions extends CacheGetOptions {
     keyResolver?: (request: HonoLikeRequest) => string;
     methods?: string[];
+    allowPrivateCaching?: boolean;
 }
-declare function createHonoCacheMiddleware(cache: CacheStack, options?: HonoCacheMiddlewareOptions): (context: HonoLikeContext, next: () => Promise<void>) => Promise<void>;
+declare function createHonoCacheMiddleware(cache: CacheStack, options?: HonoCacheMiddlewareOptions): (context: HonoLikeContext, next: () => Promise<void>) => Promise<unknown>;
 
 export { type CacheStatsSnapshot as A, type CacheTtlPolicy as B, type CacheLogger as C, type CacheTtlPolicyContext as D, type CacheWarmEntry as E, type CacheWarmOptions as F, type CacheWarmProgress as G, type CacheWriteBehindOptions as H, type InvalidationBus as I, type CacheWriteOptions as J, type EvictionPolicy as K, type LayerTtlMap as L, MemoryLayer as M, type MemoryLayerOptions as N, type MemoryLayerSnapshotEntry as O, PatternMatcher as P, createHonoCacheMiddleware as Q, TagIndex as T, type InvalidationMessage as a, type CacheTagIndex as b, CacheStack as c, type CacheWrapOptions as d, type CacheGetOptions as e, type CacheLayer as f, type CacheSerializer as g, type CacheLayerSetManyEntry as h, type CacheSingleFlightCoordinator as i, type CacheSingleFlightExecutionOptions as j, type CacheAdaptiveTtlOptions as k, type CacheCircuitBreakerOptions as l, type CacheDegradationOptions as m, type CacheHealthCheckResult as n, type CacheHitRateSnapshot as o, type CacheInspectResult as p, type CacheLayerLatency as q, type CacheMGetEntry as r, type CacheMSetEntry as s, type CacheMetricsSnapshot as t, CacheMissError as u, CacheNamespace as v, type CacheRateLimitOptions as w, type CacheSnapshotEntry as x, type CacheStackEvents as y, type CacheStackOptions as z };