layercache 2.1.0 → 3.1.0

package/dist/index.cjs

@@ -39,6 +39,7 @@ __export(index_exports, {
   MemoryLayer: () => MemoryLayer,
   MsgpackSerializer: () => MsgpackSerializer,
   PatternMatcher: () => PatternMatcher,
+  RedisGenerationStore: () => RedisGenerationStore,
   RedisInvalidationBus: () => RedisInvalidationBus,
   RedisLayer: () => RedisLayer,
   RedisSingleFlightCoordinator: () => RedisSingleFlightCoordinator,
@@ -97,39 +98,6 @@ function cloneNamespaceMetrics(metrics) {
     )
   };
 }
-function diffNamespaceMetrics(before, after) {
-  const latencyByLayer = Object.fromEntries(
-    Object.entries(after.latencyByLayer).map(([layer, value]) => [
-      layer,
-      {
-        avgMs: value.avgMs,
-        maxMs: value.maxMs,
-        count: Math.max(0, value.count - (before.latencyByLayer[layer]?.count ?? 0))
-      }
-    ])
-  );
-  return {
-    hits: after.hits - before.hits,
-    misses: after.misses - before.misses,
-    fetches: after.fetches - before.fetches,
-    sets: after.sets - before.sets,
-    deletes: after.deletes - before.deletes,
-    backfills: after.backfills - before.backfills,
-    invalidations: after.invalidations - before.invalidations,
-    staleHits: after.staleHits - before.staleHits,
-    refreshes: after.refreshes - before.refreshes,
-    refreshErrors: after.refreshErrors - before.refreshErrors,
-    writeFailures: after.writeFailures - before.writeFailures,
-    singleFlightWaits: after.singleFlightWaits - before.singleFlightWaits,
-    negativeCacheHits: after.negativeCacheHits - before.negativeCacheHits,
-    circuitBreakerTrips: after.circuitBreakerTrips - before.circuitBreakerTrips,
-    degradedOperations: after.degradedOperations - before.degradedOperations,
-    hitsByLayer: diffMetricMap(before.hitsByLayer, after.hitsByLayer),
-    missesByLayer: diffMetricMap(before.missesByLayer, after.missesByLayer),
-    latencyByLayer,
-    resetAt: after.resetAt
-  };
-}
 function addNamespaceMetrics(base, delta) {
   return {
     hits: base.hits + delta.hits,
@@ -165,14 +133,6 @@ function computeNamespaceHitRate(metrics) {
   }
   return { overall, byLayer };
 }
-function diffMetricMap(before, after) {
-  const keys = /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)]);
-  const result = {};
-  for (const key of keys) {
-    result[key] = (after[key] ?? 0) - (before[key] ?? 0);
-  }
-  return result;
-}
 function addMetricMap(base, delta) {
   const keys = /* @__PURE__ */ new Set([...Object.keys(base), ...Object.keys(delta)]);
   const result = {};
@@ -209,6 +169,20 @@ var CacheNamespace = class _CacheNamespace {
   async getOrSet(key, fetcher, options) {
     return this.trackMetrics(() => this.cache.getOrSet(this.qualify(key), fetcher, this.qualifyGetOptions(options)));
   }
+  /**
+   * Returns a namespaced cache entry, or `null` on miss.
+   * Unlike `get()`, this distinguishes a stored `null` value from an absent key.
+   */
+  async getEntry(key) {
+    const entry = await this.trackMetrics(() => this.cache.getEntry(this.qualify(key)));
+    if (entry === null) {
+      return null;
+    }
+    return {
+      ...entry,
+      key
+    };
+  }
   /**
    * Like `get()`, but throws `CacheMissError` instead of returning `null`.
    */
@@ -443,13 +417,24 @@ var CacheNamespace = class _CacheNamespace {
     };
   }
   async trackMetrics(operation) {
-    return this.getMetricsMutex().runExclusive(async () => {
-      const before = this.cache.getMetrics();
-      const result = await operation();
-      const after = this.cache.getMetrics();
-      this.metrics = addNamespaceMetrics(this.metrics, diffNamespaceMetrics(before, after));
-      return result;
+    let result;
+    let metrics;
+    try {
+      ;
+      ({ result, metrics } = await this.cache.captureMetrics(operation));
+    } catch (error) {
+      const capturedMetrics = error.metrics;
+      if (capturedMetrics) {
+        await this.getMetricsMutex().runExclusive(() => {
+          this.metrics = addNamespaceMetrics(this.metrics, capturedMetrics);
+        });
+      }
+      throw error;
+    }
+    await this.getMetricsMutex().runExclusive(() => {
+      this.metrics = addNamespaceMetrics(this.metrics, metrics);
     });
+    return result;
   }
   getMetricsMutex() {
     const existing = _CacheNamespace.metricsMutexes.get(this.cache);
@@ -1157,7 +1142,9 @@ var CacheStackMaintenance = class {
   }
   bumpKeyEpochs(keys) {
     for (const key of keys) {
-      this.keyEpochs.set(key, this.currentKeyEpoch(key) + 1);
+      const nextEpoch = this.currentKeyEpoch(key) + 1;
+      this.keyEpochs.delete(key);
+      this.keyEpochs.set(key, nextEpoch);
     }
     this.pruneKeyEpochsIfNeeded();
   }
@@ -1216,10 +1203,13 @@ var CacheStackMaintenance = class {
     if (this.keyEpochs.size <= MAX_KEY_EPOCHS) {
       return;
     }
-    const sorted = [...this.keyEpochs.entries()].sort((a, b) => a[1] - b[1]);
-    const toDelete = Math.ceil(sorted.length * 0.1);
+    const toDelete = Math.ceil(this.keyEpochs.size * 0.1);
     for (let i = 0; i < toDelete; i++) {
-      this.keyEpochs.delete(sorted[i][0]);
+      const oldestKey = this.keyEpochs.keys().next().value;
+      if (oldestKey === void 0) {
+        break;
+      }
+      this.keyEpochs.delete(oldestKey);
     }
   }
 };
@@ -1265,6 +1255,9 @@ var DEFAULT_SINGLE_FLIGHT_LEASE_MS = 3e4;
 var DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS = 5e3;
 var DEFAULT_SINGLE_FLIGHT_POLL_MS = 50;
 var DEFAULT_BACKGROUND_REFRESH_TIMEOUT_MS = 3e4;
+var SINGLE_FLIGHT_BACKOFF_FACTOR = 2;
+var SINGLE_FLIGHT_BACKOFF_JITTER = 0.2;
+var SINGLE_FLIGHT_MAX_POLL_MS = 1e3;
 var CacheStackReader = class {
   constructor(options) {
     this.options = options;
@@ -1353,22 +1346,28 @@ var CacheStackReader = class {
     if (upToIndex < 0) {
       return;
     }
+    const operations = [];
     for (let index = 0; index <= upToIndex; index += 1) {
       const layer = this.options.layers[index];
       if (!layer || this.options.shouldSkipLayer(layer)) {
         continue;
       }
       const ttl = remainingStoredTtlMs(stored) ?? this.options.resolveLayerMs(layer.name, options?.ttl, void 0, layer.defaultTtl);
-      try {
-        await layer.set(key, stored, ttl);
-      } catch (error) {
-        await this.options.handleLayerFailure(layer, "backfill", error);
-        continue;
-      }
-      this.options.metricsCollector.increment("backfills");
-      this.options.logger.debug?.("backfill", { key, layer: layer.name });
-      this.options.emit("backfill", { key, layer: layer.name });
+      operations.push(
+        (async () => {
+          try {
+            await layer.set(key, stored, ttl);
+          } catch (error) {
+            await this.options.handleLayerFailure(layer, "backfill", error);
+            return;
+          }
+          this.options.metricsCollector.increment("backfills");
+          this.options.logger.debug?.("backfill", { key, layer: layer.name });
+          this.options.emit("backfill", { key, layer: layer.name });
+        })()
+      );
     }
+    await Promise.all(operations);
   }
   abortAllRefreshes() {
     for (const key of this.backgroundRefreshAbort.keys()) {
@@ -1482,6 +1481,7 @@ var CacheStackReader = class {
     const timeoutMs = this.options.singleFlightTimeoutMs ?? DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS;
     const pollIntervalMs = this.options.singleFlightPollMs ?? DEFAULT_SINGLE_FLIGHT_POLL_MS;
     const deadline = Date.now() + timeoutMs;
+    let nextPollMs = pollIntervalMs;
     this.options.metricsCollector.increment("singleFlightWaits");
     this.options.emit("stampede-dedupe", { key });
     while (Date.now() < deadline) {
@@ -1490,16 +1490,36 @@ var CacheStackReader = class {
         this.options.metricsCollector.increment("hits");
         return hit.value;
       }
-      await this.options.sleep(pollIntervalMs);
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) {
+        break;
+      }
+      const delayMs = Math.min(this.jitterSingleFlightPoll(nextPollMs), remainingMs);
+      await this.options.sleep(delayMs);
+      nextPollMs = Math.min(nextPollMs * SINGLE_FLIGHT_BACKOFF_FACTOR, SINGLE_FLIGHT_MAX_POLL_MS, timeoutMs);
+    }
+    if (!this.options.singleFlightCoordinator) {
+      return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext);
     }
-    return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext);
+    return this.options.singleFlightCoordinator.execute(
+      key,
+      this.resolveSingleFlightOptions(),
+      () => this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext),
+      () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext)
+    );
+  }
+  jitterSingleFlightPoll(delayMs) {
+    const jitterRange = delayMs * SINGLE_FLIGHT_BACKOFF_JITTER;
+    return Math.max(1, Math.round(delayMs - jitterRange + Math.random() * jitterRange * 2));
   }
   async fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext = {
     key,
     currentValue: void 0,
     state: "miss"
   }) {
-    this.options.circuitBreakerManager.assertClosed(key, options?.circuitBreaker ?? this.options.circuitBreaker);
+    const circuitBreakerOptions = options?.circuitBreaker ?? this.options.circuitBreaker;
+    const breakerKey = this.resolveCircuitBreakerKey(key, circuitBreakerOptions);
+    this.options.circuitBreakerManager.assertClosed(breakerKey, circuitBreakerOptions);
     this.options.metricsCollector.increment("fetches");
     const fetchStart = Date.now();
     let fetched;
@@ -1509,13 +1529,13 @@ var CacheStackReader = class {
         { key, fetcher },
         () => fetcher(fetcherContext)
       );
-      this.options.circuitBreakerManager.recordSuccess(key);
+      this.options.circuitBreakerManager.recordSuccess(breakerKey);
       this.options.logger.debug?.("fetch", { key, durationMs: Date.now() - fetchStart });
     } catch (error) {
-      this.options.recordCircuitFailure(key, options?.circuitBreaker ?? this.options.circuitBreaker, error);
+      this.options.recordCircuitFailure(key, breakerKey, circuitBreakerOptions, error);
       throw error;
     }
-    if (fetched === null || fetched === void 0) {
+    if (fetched === void 0 || fetched === null && !this.shouldCacheNullValues(options)) {
       if (!this.shouldNegativeCache(options)) {
         return null;
       }
@@ -1557,6 +1577,18 @@ var CacheStackReader = class {
     await this.options.storeEntry(key, "value", fetched, options);
     return fetched;
   }
+  resolveCircuitBreakerKey(key, options) {
+    if (!options) {
+      return `key:${key}`;
+    }
+    if (options.breakerKey) {
+      return `custom:${options.breakerKey}`;
+    }
+    if (options.scope === "shared") {
+      return "scope:shared";
+    }
+    return `key:${key}`;
+  }
   runScheduleBackgroundRefresh(key, fetcher, options, fetcherContext) {
     this.scheduleBackgroundRefresh(key, fetcher, options, fetcherContext);
   }
@@ -1657,6 +1689,9 @@ var CacheStackReader = class {
   shouldNegativeCache(options) {
     return options?.negativeCache ?? this.options.negativeCaching ?? false;
   }
+  shouldCacheNullValues(options) {
+    return options?.cacheNullValues ?? this.options.cacheNullValues ?? false;
+  }
   isNegativeStoredValue(stored) {
     return isStoredValueEnvelope(stored) && stored.kind === "empty";
   }
@@ -1999,9 +2034,12 @@ function validateRateLimitOptions(name, options) {
   validatePositiveNumber(`${name}.maxConcurrent`, options.maxConcurrent);
   validatePositiveNumber(`${name}.intervalMs`, options.intervalMs);
   validatePositiveNumber(`${name}.maxPerInterval`, options.maxPerInterval);
-  if (options.scope && !["global", "key", "fetcher"].includes(options.scope)) {
+  if (options.scope !== void 0 && !["global", "key", "fetcher"].includes(options.scope)) {
     throw new Error(`${name}.scope must be one of "global", "key", or "fetcher".`);
   }
+  if (options.queueOverflow !== void 0 && !["reject", "bypass"].includes(options.queueOverflow)) {
+    throw new Error(`${name}.queueOverflow must be one of "reject" or "bypass".`);
+  }
   if (options.bucketKey !== void 0 && options.bucketKey.length === 0) {
     throw new Error(`${name}.bucketKey must not be empty.`);
   }
@@ -2082,6 +2120,12 @@ function validateCircuitBreakerOptions(options) {
   }
   validatePositiveNumber("circuitBreaker.failureThreshold", options.failureThreshold);
   validatePositiveNumber("circuitBreaker.cooldownMs", options.cooldownMs);
+  if (options.scope !== void 0 && !["key", "shared"].includes(options.scope)) {
+    throw new Error('circuitBreaker.scope must be one of "key" or "shared".');
+  }
+  if (options.breakerKey !== void 0 && options.breakerKey.length === 0) {
+    throw new Error("circuitBreaker.breakerKey must not be empty.");
+  }
 }
 function validateContextEntryOptions(name, options) {
   if (!options) {
@@ -2195,6 +2239,7 @@ var CircuitBreakerManager = class {
 // src/internal/FetchRateLimiter.ts
 var MAX_BUCKETS = 1e4;
 var MAX_QUEUE_PER_BUCKET = 1e4;
+var DEFAULT_QUEUE_OVERFLOW_POLICY = "reject";
 var FetchRateLimiter = class {
   buckets = /* @__PURE__ */ new Map();
   queuesByBucket = /* @__PURE__ */ new Map();
@@ -2219,8 +2264,12 @@ var FetchRateLimiter = class {
       const bucketKey = this.resolveBucketKey(normalized, context);
       const queue = this.queuesByBucket.get(bucketKey) ?? [];
       if (queue.length >= MAX_QUEUE_PER_BUCKET) {
-        this.rateLimitBypasses += 1;
-        task().then(resolve2, reject);
+        if ((normalized.queueOverflow ?? DEFAULT_QUEUE_OVERFLOW_POLICY) === "bypass") {
+          this.rateLimitBypasses += 1;
+          task().then(resolve2, reject);
+          return;
+        }
+        reject(new Error(`FetchRateLimiter queue overflow for bucket "${bucketKey}".`));
         return;
       }
       queue.push({
@@ -2268,7 +2317,8 @@ var FetchRateLimiter = class {
       intervalMs,
       maxPerInterval,
       scope: options.scope ?? "global",
-      bucketKey: options.bucketKey
+      bucketKey: options.bucketKey,
+      queueOverflow: options.queueOverflow
     };
   }
   resolveBucketKey(options, context) {
@@ -2453,7 +2503,9 @@ var FetchRateLimiter = class {
 };
 
 // src/internal/MetricsCollector.ts
+var import_node_async_hooks = require("async_hooks");
 var MetricsCollector = class {
+  captures = new import_node_async_hooks.AsyncLocalStorage();
   data = this.empty();
   get snapshot() {
     return {
@@ -2466,18 +2518,46 @@ var MetricsCollector = class {
   increment(field, amount = 1) {
     ;
     this.data[field] += amount;
+    for (const capture of this.captures.getStore() ?? []) {
+      ;
+      capture[field] += amount;
+    }
   }
   incrementLayer(map, layerName) {
     this.data[map][layerName] = (this.data[map][layerName] ?? 0) + 1;
+    for (const capture of this.captures.getStore() ?? []) {
+      capture[map][layerName] = (capture[map][layerName] ?? 0) + 1;
+    }
   }
   /**
    * Records a read latency sample for the given layer.
    * Maintains a rolling average and max using Welford's online algorithm.
    */
   recordLatency(layerName, durationMs) {
-    const existing = this.data.latencyByLayer[layerName];
+    this.recordLatencySample(this.data, layerName, durationMs);
+    for (const capture of this.captures.getStore() ?? []) {
+      this.recordLatencySample(capture, layerName, durationMs);
+    }
+  }
+  async capture(operation) {
+    const metrics = this.empty();
+    const activeCaptures = this.captures.getStore();
+    const captures = activeCaptures ? [...activeCaptures, metrics] : [metrics];
+    try {
+      const result = await this.captures.run(captures, operation);
+      return { result, metrics };
+    } catch (error) {
+      if ((typeof error === "object" || typeof error === "function") && error !== null) {
+        ;
+        error.metrics = metrics;
+      }
+      throw error;
+    }
+  }
+  recordLatencySample(metrics, layerName, durationMs) {
+    const existing = metrics.latencyByLayer[layerName];
     if (!existing) {
-      this.data.latencyByLayer[layerName] = { avgMs: durationMs, maxMs: durationMs, count: 1 };
+      metrics.latencyByLayer[layerName] = { avgMs: durationMs, maxMs: durationMs, count: 1 };
       return;
     }
     existing.count += 1;
@@ -2544,6 +2624,7 @@ var TtlResolver = class {
     const profile = this.accessProfiles.get(key) ?? { hits: 0, lastAccessAt: Date.now() };
     profile.hits += 1;
     profile.lastAccessAt = Date.now();
+    this.accessProfiles.delete(key);
     this.accessProfiles.set(key, profile);
     this.pruneIfNeeded();
   }
@@ -2633,41 +2714,45 @@ var TtlResolver = class {
       return;
     }
     const toRemove = Math.ceil(this.maxProfileEntries * 0.1);
-    const sorted = [...this.accessProfiles.entries()].sort((a, b) => a[1].lastAccessAt - b[1].lastAccessAt);
-    for (let i = 0; i < toRemove && i < sorted.length; i++) {
-      const entry = sorted[i];
-      if (entry) {
-        this.accessProfiles.delete(entry[0]);
+    for (let i = 0; i < toRemove; i++) {
+      const oldestKey = this.accessProfiles.keys().next().value;
+      if (oldestKey === void 0) {
+        break;
       }
+      this.accessProfiles.delete(oldestKey);
     }
   }
 };
 
 // src/invalidation/TagIndex.ts
-var MAX_PATTERN_RECURSION_DEPTH = 500;
+var DEFAULT_TOUCH_REFRESH_INTERVAL_MS = 1e3;
 var TagIndex = class {
   tagToKeys = /* @__PURE__ */ new Map();
   keyToTags = /* @__PURE__ */ new Map();
   knownKeys = /* @__PURE__ */ new Map();
   maxKnownKeys;
+  touchRefreshIntervalMs;
   nextNodeId = 1;
   root = this.createTrieNode();
   constructor(options = {}) {
     this.maxKnownKeys = options.maxKnownKeys ?? 1e5;
+    this.touchRefreshIntervalMs = options.touchRefreshIntervalMs ?? DEFAULT_TOUCH_REFRESH_INTERVAL_MS;
   }
   /**
    * Records a key as known without changing tag assignments.
    */
   async touch(key) {
-    this.insertKnownKey(key);
-    this.pruneKnownKeysIfNeeded();
+    if (this.insertKnownKey(key)) {
+      this.pruneKnownKeysIfNeeded();
+    }
   }
   /**
    * Replaces the tags associated with a key and records the key as known.
    */
   async track(key, tags) {
-    this.insertKnownKey(key);
-    this.pruneKnownKeysIfNeeded();
+    if (this.insertKnownKey(key)) {
+      this.pruneKnownKeysIfNeeded();
+    }
     if (tags.length === 0) {
       return;
     }
@@ -2737,9 +2822,14 @@ var TagIndex = class {
    * Returns known keys matching a wildcard pattern.
    */
   async matchPattern(pattern) {
-    const matches = /* @__PURE__ */ new Set();
-    this.collectPatternMatches(this.root, "", pattern, 0, matches, /* @__PURE__ */ new Set(), 0);
-    return [...matches];
+    const literalPrefix = this.literalPrefix(pattern);
+    const node = this.findNode(literalPrefix);
+    if (!node) {
+      return [];
+    }
+    const candidates = [];
+    this.collectFromNode(node, literalPrefix, candidates);
+    return candidates.filter((key) => PatternMatcher.matches(pattern, key));
   }
   /**
    * Visits known keys matching a wildcard pattern.
@@ -2769,10 +2859,18 @@ var TagIndex = class {
     };
   }
   insertKnownKey(key) {
-    const isNew = !this.knownKeys.has(key);
-    this.knownKeys.set(key, Date.now());
+    const previousTouch = this.knownKeys.get(key);
+    const isNew = previousTouch === void 0;
+    const now = Date.now();
+    if (!isNew && now - previousTouch < this.touchRefreshIntervalMs) {
+      return false;
+    }
     if (!isNew) {
-      return;
+      this.knownKeys.delete(key);
+    }
+    this.knownKeys.set(key, now);
+    if (!isNew) {
+      return true;
     }
     let node = this.root;
     for (const character of key) {
@@ -2784,6 +2882,7 @@ var TagIndex = class {
       node = child;
     }
     node.terminal = true;
+    return true;
   }
   findNode(prefix) {
     let node = this.root;
@@ -2796,85 +2895,52 @@ var TagIndex = class {
     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);
+    const stack = [{ node, prefix }];
+    while (stack.length > 0) {
+      const current = stack.pop();
+      if (!current) {
+        continue;
+      }
+      if (current.node.terminal) {
+        matches.push(current.prefix);
+      }
+      const children = [...current.node.children].reverse();
+      for (const [character, child] of children) {
+        stack.push({ node: child, prefix: `${current.prefix}${character}` });
+      }
     }
   }
   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;
-    }
-    const stateKey = `${node.id}:${patternIndex}`;
-    if (visited.has(stateKey)) {
-      return;
-    }
-    visited.add(stateKey);
-    if (patternIndex === pattern.length) {
-      if (node.terminal) {
-        matches.add(prefix);
+    const stack = [{ node, prefix }];
+    while (stack.length > 0) {
+      const current = stack.pop();
+      if (!current) {
+        continue;
       }
-      return;
-    }
-    const patternChar = pattern[patternIndex];
-    if (patternChar === void 0) {
-      return;
-    }
-    if (patternChar === "*") {
-      this.collectPatternMatches(node, prefix, pattern, patternIndex + 1, matches, visited, depth + 1);
-      for (const [character, child2] of node.children) {
-        this.collectPatternMatches(child2, `${prefix}${character}`, pattern, patternIndex, matches, visited, depth + 1);
+      if (current.node.terminal) {
+        await visitor(current.prefix);
       }
-      return;
-    }
-    if (patternChar === "?") {
-      for (const [character, child2] of node.children) {
-        this.collectPatternMatches(
-          child2,
-          `${prefix}${character}`,
-          pattern,
-          patternIndex + 1,
-          matches,
-          visited,
-          depth + 1
-        );
+      const children = [...current.node.children].reverse();
+      for (const [character, child] of children) {
+        stack.push({ node: child, prefix: `${current.prefix}${character}` });
       }
-      return;
-    }
-    const child = node.children.get(patternChar);
-    if (child) {
-      this.collectPatternMatches(
-        child,
-        `${prefix}${patternChar}`,
-        pattern,
-        patternIndex + 1,
-        matches,
-        visited,
-        depth + 1
-      );
     }
   }
+  literalPrefix(pattern) {
+    const wildcardIndex = pattern.search(/[*?]/);
+    return wildcardIndex === -1 ? pattern : pattern.slice(0, wildcardIndex);
+  }
   pruneKnownKeysIfNeeded() {
     if (this.maxKnownKeys === void 0 || this.knownKeys.size <= this.maxKnownKeys) {
       return;
     }
-    const sorted = [...this.knownKeys.entries()].sort((a, b) => a[1] - b[1]);
     const toRemove = Math.ceil(this.maxKnownKeys * 0.1);
-    for (let i = 0; i < toRemove && i < sorted.length; i += 1) {
-      const entry = sorted[i];
-      if (entry) {
-        this.removeKey(entry[0]);
+    for (let i = 0; i < toRemove; i += 1) {
+      const oldestKey = this.knownKeys.keys().next().value;
+      if (oldestKey === void 0) {
+        break;
       }
+      this.removeKnownKey(oldestKey);
     }
   }
   removeKey(key) {
@@ -3171,7 +3237,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
       emitError: (operation, context) => this.emitError(operation, context),
       formatError: (error) => this.formatError(error),
       storeEntry: (key, kind, value, options2) => this.storeEntry(key, kind, value, options2),
-      recordCircuitFailure: (key, options2, error) => this.recordCircuitFailure(key, options2, error),
+      recordCircuitFailure: (key, breakerKey, options2, error) => this.recordCircuitFailure(key, breakerKey, options2, error),
       resolveLayerMs: (layerName, override, globalDefault, fallback) => this.resolveLayerMs(layerName, override, globalDefault, fallback),
       sleep: (ms) => this.sleep(ms),
       withTimeout: (promise, ms, createError) => this.withTimeout(promise, ms, createError),
@@ -3186,6 +3252,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
       singleFlightRenewIntervalMs: options.singleFlightRenewIntervalMs,
       backgroundRefreshTimeoutMs: options.backgroundRefreshTimeoutMs,
       negativeCaching: options.negativeCaching,
+      cacheNullValues: options.cacheNullValues,
       refreshAhead: options.refreshAhead,
       circuitBreaker: options.circuitBreaker,
       fetcherRateLimit: options.fetcherRateLimit
@@ -3238,6 +3305,64 @@ var CacheStack = class extends import_node_events.EventEmitter {
   async getOrSet(key, fetcher, options) {
     return this.get(key, fetcher, options);
   }
+  /**
+   * Returns a discriminated cache entry, or `null` on miss.
+   * Unlike `get()`, this distinguishes a stored `null` value from an absent key.
+   */
+  async getEntry(key) {
+    return this.observeOperation("layercache.get_entry", { "layercache.key": String(key ?? "") }, async () => {
+      const userKey = validateCacheKey(key);
+      const normalizedKey = this.qualifyKey(userKey);
+      await this.awaitStartup("getEntry");
+      let sawRetainableValue = false;
+      for (let index = 0; index < this.layers.length; index += 1) {
+        const layer = this.layers[index];
+        if (!layer || this.shouldSkipLayer(layer)) {
+          continue;
+        }
+        const readStart = performance.now();
+        const stored = await this.readLayerEntry(layer, normalizedKey);
+        this.metricsCollector.recordLatency(layer.name, performance.now() - readStart);
+        if (stored === null) {
+          this.metricsCollector.incrementLayer("missesByLayer", layer.name);
+          continue;
+        }
+        const resolved = resolveStoredValue(stored);
+        if (resolved.state === "expired") {
+          await layer.delete(normalizedKey);
+          continue;
+        }
+        sawRetainableValue = true;
+        await this.tagIndex.touch(normalizedKey);
+        await this.reader.backfill(normalizedKey, stored, index - 1);
+        this.metricsCollector.increment("hits");
+        if (resolved.state === "stale-while-revalidate" || resolved.state === "stale-if-error") {
+          this.metricsCollector.increment("staleHits");
+        }
+        this.metricsCollector.incrementLayer("hitsByLayer", layer.name);
+        this.logger.debug?.("hit", { key: normalizedKey, layer: layer.name, state: resolved.state });
+        this.emit("hit", {
+          key: normalizedKey,
+          layer: layer.name,
+          state: resolved.state
+        });
+        return {
+          key: userKey,
+          value: resolved.value,
+          kind: resolved.envelope?.kind ?? "value",
+          state: resolved.state,
+          layer: layer.name
+        };
+      }
+      if (!sawRetainableValue) {
+        await this.tagIndex.remove(normalizedKey);
+      }
+      this.metricsCollector.increment("misses");
+      this.logger.debug?.("miss", { key: normalizedKey, mode: "getEntry" });
+      this.emit("miss", { key: normalizedKey, mode: "getEntry" });
+      return null;
+    });
+  }
   /**
    * Like `get()`, but throws `CacheMissError` instead of returning `null`.
    * Useful when the value is expected to exist or the fetcher is expected to
@@ -3702,6 +3827,13 @@ var CacheStack = class extends import_node_events.EventEmitter {
   getMetrics() {
     return this.metricsCollector.snapshot;
   }
+  /**
+   * Runs an operation while collecting only the metrics emitted by its async context.
+   * Used by namespaces so metrics tracking does not serialize the operation itself.
+   */
+  async captureMetrics(operation) {
+    return this.metricsCollector.capture(operation);
+  }
   /**
    * Returns metrics plus layer degradation state and active background refresh count.
    */
@@ -3775,6 +3907,12 @@ var CacheStack = class extends import_node_events.EventEmitter {
     }
     return this.currentGeneration;
   }
+  /**
+   * Returns the active generation prefix number used for future cache keys.
+   */
+  getGeneration() {
+    return this.currentGeneration;
+  }
   /**
    * Returns detailed metadata about a single cache key: which layers contain it,
    * remaining fresh/stale/error TTLs, and associated tags.
@@ -3999,7 +4137,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
     for (const key of keys) {
       await this.tagIndex.remove(key);
       this.ttlResolver.deleteProfile(key);
-      this.circuitBreakerManager.delete(key);
+      this.circuitBreakerManager.delete(`key:${key}`);
     }
     this.metricsCollector.increment("deletes", keys.length);
     this.metricsCollector.increment("invalidations");
@@ -4018,7 +4156,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
       }
       await this.tagIndex.remove(key);
       this.ttlResolver.deleteProfile(key);
-      this.circuitBreakerManager.delete(key);
+      this.circuitBreakerManager.delete(`key:${key}`);
     }
     this.metricsCollector.increment("invalidations");
     this.logger.debug?.("expire", { keys });
@@ -4060,7 +4198,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
       for (const key of keys) {
         await this.tagIndex.remove(key);
         this.ttlResolver.deleteProfile(key);
-        this.circuitBreakerManager.delete(key);
+        this.circuitBreakerManager.delete(`key:${key}`);
       }
     }
   }
@@ -4305,15 +4443,15 @@ var CacheStack = class extends import_node_events.EventEmitter {
   isGracefulDegradationEnabled() {
     return Boolean(this.options.gracefulDegradation);
   }
-  recordCircuitFailure(key, options, error) {
+  recordCircuitFailure(key, breakerKey, options, error) {
     if (!options) {
       return;
     }
-    this.circuitBreakerManager.recordFailure(key, options);
-    if (this.circuitBreakerManager.isOpen(key)) {
+    this.circuitBreakerManager.recordFailure(breakerKey, options);
+    if (this.circuitBreakerManager.isOpen(breakerKey)) {
       this.metricsCollector.increment("circuitBreakerTrips");
     }
-    this.emitError("fetch", { key, error: this.formatError(error) });
+    this.emitError("fetch", { key, breakerKey, error: this.formatError(error) });
   }
   emitError(operation, context) {
     this.logger.error?.(operation, context);
@@ -4332,12 +4470,65 @@ var CacheStack = class extends import_node_events.EventEmitter {
   }
 };
 
+// src/generation/RedisGenerationStore.ts
+var DEFAULT_GENERATION_KEY = "layercache:generation";
+var RedisGenerationStore = class {
+  client;
+  key;
+  constructor(options) {
+    this.client = options.client;
+    this.key = options.key ?? DEFAULT_GENERATION_KEY;
+  }
+  async get() {
+    const stored = await this.client.get(this.key);
+    if (stored === null) {
+      return void 0;
+    }
+    return this.parseGeneration(stored);
+  }
+  async getOrInitialize(initialGeneration = 0) {
+    this.assertGeneration(initialGeneration);
+    await this.client.set(this.key, String(initialGeneration), "NX");
+    const generation = await this.get();
+    if (generation === void 0) {
+      throw new Error(`RedisGenerationStore failed to initialize generation key "${this.key}".`);
+    }
+    return generation;
+  }
+  async set(generation) {
+    this.assertGeneration(generation);
+    await this.client.set(this.key, String(generation));
+  }
+  async bump() {
+    const generation = await this.client.incr(this.key);
+    this.assertGeneration(generation);
+    return generation;
+  }
+  parseGeneration(value) {
+    const generation = Number.parseInt(value, 10);
+    if (String(generation) !== value || !this.isGeneration(generation)) {
+      throw new Error(`RedisGenerationStore found invalid persisted generation value for key "${this.key}".`);
+    }
+    return generation;
+  }
+  assertGeneration(value) {
+    if (!this.isGeneration(value)) {
+      throw new Error("RedisGenerationStore generation must be a non-negative safe integer.");
+    }
+  }
+  isGeneration(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+  }
+};
+
 // src/invalidation/RedisInvalidationBus.ts
+var import_node_crypto3 = require("crypto");
 var RedisInvalidationBus = class {
   channel;
   publisher;
   subscriber;
   logger;
+  signingKey;
   handlers = /* @__PURE__ */ new Set();
   sharedListener;
   subscribePromise;
@@ -4346,6 +4537,7 @@ var RedisInvalidationBus = class {
     this.subscriber = options.subscriber ?? options.publisher.duplicate();
     this.channel = options.channel ?? "layercache:invalidation";
     this.logger = options.logger;
+    this.signingKey = options.signingSecret ? normalizeSigningSecret(options.signingSecret) : void 0;
   }
   /**
    * Subscribes to invalidation messages and returns an unsubscribe function.
@@ -4385,7 +4577,7 @@ var RedisInvalidationBus = class {
    * Publishes an invalidation message to other subscribers.
    */
   async publish(message) {
-    await this.publisher.publish(this.channel, JSON.stringify(message));
+    await this.publisher.publish(this.channel, JSON.stringify(this.signingKey ? this.signMessage(message) : message));
   }
   async dispatchToHandlers(payload) {
     let message;
@@ -4396,10 +4588,11 @@ var RedisInvalidationBus = class {
         maxNodes: 1e4,
         createObject: () => /* @__PURE__ */ Object.create(null)
       });
-      if (!this.isInvalidationMessage(parsed)) {
+      const candidate = this.signingKey ? this.verifySignedEnvelope(parsed) : parsed;
+      if (!this.isInvalidationMessage(candidate)) {
         throw new Error("Invalid invalidation payload shape.");
       }
-      message = parsed;
+      message = candidate;
     } catch (error) {
       this.reportError("invalid invalidation payload", error);
       return;
@@ -4424,6 +4617,34 @@ var RedisInvalidationBus = class {
     const validKeys = candidate.keys === void 0 || Array.isArray(candidate.keys) && candidate.keys.every((key) => typeof key === "string");
     return validScope && typeof candidate.sourceId === "string" && candidate.sourceId.length > 0 && validOperation && validKeys;
   }
+  signMessage(message) {
+    const payload = JSON.stringify(message);
+    return {
+      payload: message,
+      signature: this.createSignature(payload)
+    };
+  }
+  verifySignedEnvelope(value) {
+    if (!value || typeof value !== "object") {
+      throw new Error("Signed invalidation envelope must be an object.");
+    }
+    const envelope = value;
+    if (!envelope.payload || typeof envelope.payload !== "object" || typeof envelope.signature !== "string") {
+      throw new Error("Signed invalidation envelope is missing payload or signature.");
+    }
+    const payload = JSON.stringify(envelope.payload);
+    const expected = this.createSignature(payload);
+    if (!isEqualSignature(envelope.signature, expected)) {
+      throw new Error("Invalid invalidation message signature.");
+    }
+    return envelope.payload;
+  }
+  createSignature(payload) {
+    if (!this.signingKey) {
+      throw new Error("RedisInvalidationBus signing key is not configured.");
+    }
+    return (0, import_node_crypto3.createHmac)("sha256", this.signingKey).update(payload).digest("hex");
+  }
   reportError(message, error) {
     if (this.logger?.error) {
       this.logger.error(message, { error });
@@ -4432,18 +4653,31 @@ var RedisInvalidationBus = class {
     console.error(`[layercache] ${message}`, error);
   }
 };
+function normalizeSigningSecret(secret) {
+  const raw = Buffer.isBuffer(secret) ? secret : Buffer.from(secret, "utf8");
+  return (0, import_node_crypto3.createHash)("sha256").update(raw).digest();
+}
+function isEqualSignature(actual, expected) {
+  const actualBuffer = Buffer.from(actual, "hex");
+  const expectedBuffer = Buffer.from(expected, "hex");
+  return actualBuffer.length === expectedBuffer.length && (0, import_node_crypto3.timingSafeEqual)(actualBuffer, expectedBuffer);
+}
 
 // src/invalidation/RedisTagIndex.ts
+var DEFAULT_KNOWN_KEYS_SHARDS = 16;
 var RedisTagIndex = class {
   client;
   prefix;
   scanCount;
   knownKeysShards;
+  logger;
+  warnedLegacyKnownKeys = false;
   constructor(options) {
     this.client = options.client;
     this.prefix = options.prefix ?? "layercache:tag-index";
     this.scanCount = options.scanCount ?? 100;
     this.knownKeysShards = normalizeKnownKeysShards(options.knownKeysShards);
+    this.logger = options.logger;
   }
   /**
    * Records a key as known without changing tag assignments.
@@ -4479,6 +4713,9 @@ var RedisTagIndex = class {
     const existingTags = await this.client.smembers(keyTagsKey);
     const pipeline = this.client.pipeline();
     pipeline.srem(this.knownKeysKeyFor(key), key);
+    if (this.knownKeysShards > 1) {
+      pipeline.srem(this.legacyKnownKeysKey(), key);
+    }
     pipeline.del(keyTagsKey);
     for (const tag of existingTags) {
       pipeline.srem(this.tagKeysKey(tag), key);
@@ -4509,28 +4746,34 @@ var RedisTagIndex = class {
    * Returns known keys that start with a prefix.
    */
   async keysForPrefix(prefix) {
-    const matches = [];
-    for (const knownKeysKey of this.knownKeysKeys()) {
+    const matches = /* @__PURE__ */ new Set();
+    for (const knownKeysKey of await this.knownKeysKeysForRead()) {
       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)));
+        for (const key of keys) {
+          if (key.startsWith(prefix)) {
+            matches.add(key);
+          }
+        }
       } while (cursor !== "0");
     }
-    return matches;
+    return [...matches];
   }
   /**
    * Visits known keys that start with a prefix.
    */
   async forEachKeyForPrefix(prefix, visitor) {
-    for (const knownKeysKey of this.knownKeysKeys()) {
+    const visited = /* @__PURE__ */ new Set();
+    for (const knownKeysKey of await this.knownKeysKeysForRead()) {
       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)) {
+          if (key.startsWith(prefix) && !visited.has(key)) {
+            visited.add(key);
             await visitor(key);
           }
         }
@@ -4547,8 +4790,8 @@ var RedisTagIndex = class {
    * Returns known keys matching a wildcard pattern.
    */
   async matchPattern(pattern) {
-    const matches = [];
-    for (const knownKeysKey of this.knownKeysKeys()) {
+    const matches = /* @__PURE__ */ new Set();
+    for (const knownKeysKey of await this.knownKeysKeysForRead()) {
       let cursor = "0";
       do {
         const [nextCursor, keys] = await this.client.sscan(
@@ -4560,16 +4803,21 @@ var RedisTagIndex = class {
           this.scanCount
         );
         cursor = nextCursor;
-        matches.push(...keys.filter((key) => PatternMatcher.matches(pattern, key)));
+        for (const key of keys) {
+          if (PatternMatcher.matches(pattern, key)) {
+            matches.add(key);
+          }
+        }
       } while (cursor !== "0");
     }
-    return matches;
+    return [...matches];
   }
   /**
    * Visits known keys matching a wildcard pattern.
    */
   async forEachKeyMatchingPattern(pattern, visitor) {
-    for (const knownKeysKey of this.knownKeysKeys()) {
+    const visited = /* @__PURE__ */ new Set();
+    for (const knownKeysKey of await this.knownKeysKeysForRead()) {
       let cursor = "0";
       do {
         const [nextCursor, keys] = await this.client.sscan(
@@ -4582,7 +4830,8 @@ var RedisTagIndex = class {
         );
         cursor = nextCursor;
         for (const key of keys) {
-          if (PatternMatcher.matches(pattern, key)) {
+          if (PatternMatcher.matches(pattern, key) && !visited.has(key)) {
+            visited.add(key);
             await visitor(key);
           }
         }
@@ -4599,6 +4848,31 @@ var RedisTagIndex = class {
     }
     await this.client.del(...indexKeys);
   }
+  async migrateLegacyKnownKeys() {
+    if (this.knownKeysShards === 1) {
+      return { migratedKeys: 0 };
+    }
+    const legacyKey = this.legacyKnownKeysKey();
+    let cursor = "0";
+    let migratedKeys = 0;
+    do {
+      const [nextCursor, keys] = await this.client.sscan(legacyKey, cursor, "COUNT", this.scanCount);
+      cursor = nextCursor;
+      if (keys.length === 0) {
+        continue;
+      }
+      const pipeline = this.client.pipeline();
+      for (const key of keys) {
+        pipeline.sadd(this.knownKeysKeyFor(key), key);
+      }
+      await pipeline.exec();
+      migratedKeys += keys.length;
+    } while (cursor !== "0");
+    if (migratedKeys > 0) {
+      await this.client.del(legacyKey);
+    }
+    return { migratedKeys };
+  }
   async scanIndexKeys() {
     const matches = [];
     let cursor = "0";
@@ -4616,12 +4890,40 @@ var RedisTagIndex = class {
     }
     return `${this.prefix}:keys:${simpleHash(key) % this.knownKeysShards}`;
   }
+  async knownKeysKeysForRead() {
+    if (this.knownKeysShards === 1) {
+      return [this.legacyKnownKeysKey()];
+    }
+    const shardedKeys = this.knownKeysKeys();
+    const legacyKey = this.legacyKnownKeysKey();
+    const legacyExists = await this.client.exists(legacyKey) > 0;
+    if (!legacyExists) {
+      return shardedKeys;
+    }
+    this.warnLegacyKnownKeys(legacyKey);
+    return [legacyKey, ...shardedKeys];
+  }
   knownKeysKeys() {
     if (this.knownKeysShards === 1) {
       return [`${this.prefix}:keys`];
     }
     return Array.from({ length: this.knownKeysShards }, (_, index) => `${this.prefix}:keys:${index}`);
   }
+  legacyKnownKeysKey() {
+    return `${this.prefix}:keys`;
+  }
+  warnLegacyKnownKeys(legacyKey) {
+    if (this.warnedLegacyKnownKeys) {
+      return;
+    }
+    this.warnedLegacyKnownKeys = true;
+    const message = "RedisTagIndex detected a legacy RedisTagIndex known-key set. Run `layercache migrate-tag-index` to migrate keys into the sharded layout.";
+    if (this.logger?.warn) {
+      this.logger.warn(message, { legacyKey, knownKeysShards: this.knownKeysShards });
+      return;
+    }
+    console.warn(`[layercache] ${message}`, { legacyKey, knownKeysShards: this.knownKeysShards });
+  }
   keyTagsKey(key) {
     return `${this.prefix}:key:${encodeURIComponent(key)}`;
   }
@@ -4631,7 +4933,7 @@ var RedisTagIndex = class {
 };
 function normalizeKnownKeysShards(value) {
   if (value === void 0) {
-    return 1;
+    return DEFAULT_KNOWN_KEYS_SHARDS;
   }
   if (!Number.isInteger(value) || value <= 0) {
     throw new Error("RedisTagIndex.knownKeysShards must be a positive integer.");
@@ -4727,6 +5029,41 @@ function createFastifyLayercachePlugin(cache, options = {}) {
   };
 }
 
+// src/integrations/httpCacheKeys.ts
+var SENSITIVE_QUERY_PARAMETERS = /* @__PURE__ */ new Set([
+  "access_token",
+  "api_key",
+  "apikey",
+  "auth",
+  "authorization",
+  "code",
+  "credentials",
+  "id_token",
+  "jwt",
+  "password",
+  "private_key",
+  "refresh_token",
+  "secret",
+  "session",
+  "sessionid",
+  "session_id",
+  "token"
+]);
+function normalizeHttpCacheUrl(url) {
+  try {
+    const parsed = new URL(url, "http://localhost");
+    for (const name of [...parsed.searchParams.keys()]) {
+      if (SENSITIVE_QUERY_PARAMETERS.has(name.toLowerCase())) {
+        parsed.searchParams.delete(name);
+      }
+    }
+    parsed.searchParams.sort();
+    return parsed.pathname + parsed.search;
+  } catch {
+    return url;
+  }
+}
+
 // src/integrations/express.ts
 function createExpressCacheMiddleware(cache, options = {}) {
   const allowedMethods = new Set((options.methods ?? ["GET"]).map((m) => m.toUpperCase()));
@@ -4742,7 +5079,7 @@ function createExpressCacheMiddleware(cache, options = {}) {
         return;
       }
       const rawUrl = req.originalUrl ?? req.url ?? "/";
-      const key = options.keyResolver ? options.keyResolver(req) : `${method}:${normalizeUrl(rawUrl)}`;
+      const key = options.keyResolver ? options.keyResolver(req) : `${method}:${normalizeHttpCacheUrl(rawUrl)}`;
       const cached = await cache.get(key, void 0, options);
       if (cached !== null) {
         res.setHeader?.("content-type", "application/json; charset=utf-8");
@@ -4758,12 +5095,14 @@ function createExpressCacheMiddleware(cache, options = {}) {
       if (originalJson) {
         res.json = (body) => {
           res.setHeader?.("x-cache", "MISS");
-          cache.set(key, body, options).catch((err) => {
-            cache.emit("error", {
-              operation: "set",
-              error: err instanceof Error ? err.message : String(err)
+          if (isSuccessfulStatus(res.statusCode)) {
+            cache.set(key, body, options).catch((err) => {
+              cache.emit("error", {
+                operation: "set",
+                error: err instanceof Error ? err.message : String(err)
+              });
             });
-          });
+          }
           return originalJson(body);
         };
       }
@@ -4773,14 +5112,8 @@ function createExpressCacheMiddleware(cache, options = {}) {
     }
   };
 }
-function normalizeUrl(url) {
-  try {
-    const parsed = new URL(url, "http://localhost");
-    parsed.searchParams.sort();
-    return parsed.pathname + parsed.search;
-  } catch {
-    return url;
-  }
+function isSuccessfulStatus(statusCode) {
+  return statusCode === void 0 || statusCode >= 200 && statusCode < 300;
 }
 
 // src/integrations/graphql.ts
@@ -4811,35 +5144,39 @@ function createHonoCacheMiddleware(cache, options = {}) {
       return;
     }
     const rawPath = context.req.path ?? context.req.url ?? "/";
-    const key = options.keyResolver ? options.keyResolver(context.req) : `${method}:${normalizeUrl2(rawPath)}`;
+    const key = options.keyResolver ? options.keyResolver(context.req) : `${method}:${normalizeHttpCacheUrl(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");
       return context.json(cached);
     }
+    let currentStatus;
+    const originalStatus = context.status?.bind(context);
+    if (originalStatus) {
+      context.status = (status) => {
+        currentStatus = status;
+        return originalStatus(status);
+      };
+    }
     const originalJson = context.json.bind(context);
     context.json = (body, status) => {
       context.header?.("x-cache", "MISS");
-      cache.set(key, body, options).catch((err) => {
-        cache.emit("error", {
-          operation: "set",
-          error: err instanceof Error ? err.message : String(err)
+      if (isSuccessfulStatus2(status ?? currentStatus)) {
+        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 normalizeUrl2(url) {
-  try {
-    const parsed = new URL(url, "http://localhost");
-    parsed.searchParams.sort();
-    return parsed.pathname + parsed.search;
-  } catch {
-    return url;
-  }
+function isSuccessfulStatus2(statusCode) {
+  return statusCode === void 0 || statusCode >= 200 && statusCode < 300;
 }
 
 // src/integrations/opentelemetry.ts
@@ -5634,12 +5971,12 @@ var RedisLayer = class {
 };
 
 // src/layers/DiskLayer.ts
-var import_node_crypto4 = require("crypto");
+var import_node_crypto5 = require("crypto");
 var import_node_fs2 = require("fs");
 var import_node_path = require("path");
 
 // src/internal/PayloadProtection.ts
-var import_node_crypto3 = require("crypto");
+var import_node_crypto4 = require("crypto");
 var MAGIC_ENCRYPTED = Buffer.from("LCP1:");
 var MAGIC_SIGNED = Buffer.from("LCS1:");
 var ALGORITHM = "aes-256-gcm";
@@ -5652,11 +5989,11 @@ var PayloadProtection = class {
   constructor(options) {
     if (options.encryptionKey) {
       const raw = Buffer.isBuffer(options.encryptionKey) ? options.encryptionKey : Buffer.from(options.encryptionKey, "utf8");
-      this.encryptionKey = (0, import_node_crypto3.createHash)("sha256").update(raw).digest();
+      this.encryptionKey = (0, import_node_crypto4.createHash)("sha256").update(raw).digest();
     }
     if (options.signingKey && !options.encryptionKey) {
       const raw = Buffer.isBuffer(options.signingKey) ? options.signingKey : Buffer.from(options.signingKey, "utf8");
-      this.signingKey = (0, import_node_crypto3.createHash)("sha256").update(raw).digest();
+      this.signingKey = (0, import_node_crypto4.createHash)("sha256").update(raw).digest();
     }
   }
   /** Returns `true` when any protection (encryption or signing) is configured. */
@@ -5703,8 +6040,8 @@ var PayloadProtection = class {
   }
   // ── Encryption (AES-256-GCM) ──────────────────────────────────────────
   encrypt(plaintext, key) {
-    const iv = (0, import_node_crypto3.randomBytes)(IV_LENGTH);
-    const cipher = (0, import_node_crypto3.createCipheriv)(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+    const iv = (0, import_node_crypto4.randomBytes)(IV_LENGTH);
+    const cipher = (0, import_node_crypto4.createCipheriv)(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
     const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
     const authTag = cipher.getAuthTag();
     return Buffer.concat([MAGIC_ENCRYPTED, iv, authTag, encrypted]);
@@ -5715,7 +6052,7 @@ var PayloadProtection = class {
     const authTag = payload.subarray(headerEnd + IV_LENGTH, headerEnd + IV_LENGTH + AUTH_TAG_LENGTH);
     const ciphertext = payload.subarray(headerEnd + IV_LENGTH + AUTH_TAG_LENGTH);
     try {
-      const decipher = (0, import_node_crypto3.createDecipheriv)(ALGORITHM, key, iv, {
+      const decipher = (0, import_node_crypto4.createDecipheriv)(ALGORITHM, key, iv, {
         authTagLength: AUTH_TAG_LENGTH
       });
       decipher.setAuthTag(authTag);
@@ -5728,15 +6065,15 @@ var PayloadProtection = class {
   }
   // ── Signing (HMAC-SHA256) ─────────────────────────────────────────────
   sign(payload, key) {
-    const hmac = (0, import_node_crypto3.createHmac)("sha256", key).update(payload).digest();
+    const hmac = (0, import_node_crypto4.createHmac)("sha256", key).update(payload).digest();
     return Buffer.concat([MAGIC_SIGNED, hmac, payload]);
   }
   verify(payload, key) {
     const headerEnd = MAGIC_SIGNED.length;
     const receivedHmac = payload.subarray(headerEnd, headerEnd + HMAC_LENGTH);
     const data = payload.subarray(headerEnd + HMAC_LENGTH);
-    const expectedHmac = (0, import_node_crypto3.createHmac)("sha256", key).update(data).digest();
-    if (receivedHmac.length !== HMAC_LENGTH || !(0, import_node_crypto3.timingSafeEqual)(receivedHmac, expectedHmac)) {
+    const expectedHmac = (0, import_node_crypto4.createHmac)("sha256", key).update(data).digest();
+    if (receivedHmac.length !== HMAC_LENGTH || !(0, import_node_crypto4.timingSafeEqual)(receivedHmac, expectedHmac)) {
       throw new PayloadProtectionError(
         "HMAC verification failed. The data may have been tampered with or the signingKey is incorrect."
       );
@@ -5760,6 +6097,7 @@ var PayloadProtectionError = class extends Error {
 
 // src/layers/DiskLayer.ts
 var FILE_SCAN_CONCURRENCY = 32;
+var DEFAULT_MAX_WRITE_QUEUE_DEPTH = 1e4;
 var DiskLayer = class {
   name;
   defaultTtl;
@@ -5768,8 +6106,10 @@ var DiskLayer = class {
   serializer;
   maxFiles;
   maxEntryBytes;
+  maxWriteQueueDepth;
   protection;
   writeQueue = Promise.resolve();
+  writeQueueDepth = 0;
   /**
    * Creates a disk-backed cache layer.
    */
@@ -5780,6 +6120,7 @@ var DiskLayer = class {
     this.serializer = options.serializer ?? new JsonSerializer();
     this.maxFiles = this.normalizeMaxFiles(options.maxFiles);
     this.maxEntryBytes = this.normalizeMaxEntryBytes(options.maxEntryBytes);
+    this.maxWriteQueueDepth = this.normalizeMaxWriteQueueDepth(options.maxWriteQueueDepth);
     this.protection = new PayloadProtection({
       encryptionKey: options.encryptionKey,
       signingKey: options.signingKey
@@ -5828,7 +6169,7 @@ var DiskLayer = class {
       const raw = Buffer.isBuffer(payload) ? payload : Buffer.from(payload, "utf8");
       const protectedPayload = this.protection.protect(raw);
       const targetPath = this.keyToPath(key);
-      const tempPath = `${targetPath}.${process.pid}.${Date.now()}.${(0, import_node_crypto4.randomBytes)(8).toString("hex")}.tmp`;
+      const tempPath = `${targetPath}.${process.pid}.${Date.now()}.${(0, import_node_crypto5.randomBytes)(8).toString("hex")}.tmp`;
       try {
         await import_node_fs2.promises.writeFile(tempPath, protectedPayload);
         await import_node_fs2.promises.rename(tempPath, targetPath);
@@ -5961,7 +6302,7 @@ var DiskLayer = class {
   async dispose() {
   }
   keyToPath(key) {
-    const hash = (0, import_node_crypto4.createHash)("sha256").update(key).digest("hex");
+    const hash = (0, import_node_crypto5.createHash)("sha256").update(key).digest("hex");
     return (0, import_node_path.join)(this.directory, `${hash}.lc`);
   }
   resolveDirectory(directory) {
@@ -5995,6 +6336,16 @@ var DiskLayer = class {
     }
     return normalized;
   }
+  normalizeMaxWriteQueueDepth(maxWriteQueueDepth) {
+    if (maxWriteQueueDepth === false) {
+      return false;
+    }
+    const normalized = maxWriteQueueDepth ?? DEFAULT_MAX_WRITE_QUEUE_DEPTH;
+    if (!Number.isInteger(normalized) || normalized <= 0) {
+      throw new Error("DiskLayer.maxWriteQueueDepth must be a positive integer or false.");
+    }
+    return normalized;
+  }
   async readEntryFile(filePath) {
     let handle;
     try {
@@ -6107,7 +6458,13 @@ var DiskLayer = class {
     }
   }
   enqueueWrite(operation) {
-    const next = this.writeQueue.then(operation, operation);
+    if (this.maxWriteQueueDepth !== false && this.writeQueueDepth >= this.maxWriteQueueDepth) {
+      return Promise.reject(new Error(`DiskLayer write queue limit (${this.maxWriteQueueDepth}) exceeded.`));
+    }
+    this.writeQueueDepth += 1;
+    const next = this.writeQueue.then(operation, operation).finally(() => {
+      this.writeQueueDepth -= 1;
+    });
     this.writeQueue = next.catch(() => void 0);
     return next;
   }
@@ -6279,7 +6636,7 @@ var MsgpackSerializer = class {
 };
 
 // src/singleflight/RedisSingleFlightCoordinator.ts
-var import_node_crypto5 = require("crypto");
+var import_node_crypto6 = require("crypto");
 var RELEASE_SCRIPT = `
 if redis.call("get", KEYS[1]) == ARGV[1] then
   return redis.call("del", KEYS[1])
@@ -6307,7 +6664,7 @@ var RedisSingleFlightCoordinator = class {
    */
   async execute(key, options, worker, waiter) {
     const lockKey = `${this.prefix}:${encodeURIComponent(key)}`;
-    const token = (0, import_node_crypto5.randomUUID)();
+    const token = (0, import_node_crypto6.randomUUID)();
     const acquired = await this.runCommand(
       `acquire("${key}")`,
       () => this.client.set(lockKey, token, "PX", options.leaseMs, "NX")
@@ -6461,6 +6818,7 @@ function sanitizeLabel(value) {
   MemoryLayer,
   MsgpackSerializer,
   PatternMatcher,
+  RedisGenerationStore,
   RedisInvalidationBus,
   RedisLayer,
   RedisSingleFlightCoordinator,