layercache 2.0.0 → 3.0.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,
@@ -184,6 +185,9 @@ function addMetricMap(base, delta) {
 
 // src/CacheNamespace.ts
 var CacheNamespace = class _CacheNamespace {
+  /**
+   * Creates a namespace backed by an existing cache stack.
+   */
   constructor(cache, prefix) {
     this.cache = cache;
     this.prefix = prefix;
@@ -193,9 +197,16 @@ var CacheNamespace = class _CacheNamespace {
   prefix;
   static metricsMutexes = /* @__PURE__ */ new WeakMap();
   metrics = createEmptyNamespaceMetrics();
+  /**
+   * Reads a key inside this namespace and optionally runs a read-through fetcher
+   * on miss or refresh.
+   */
   async get(key, fetcher, options) {
     return this.trackMetrics(() => this.cache.get(this.qualify(key), fetcher, this.qualifyGetOptions(options)));
   }
+  /**
+   * Alias for `get(key, fetcher, options)` that makes the get-or-set behavior explicit.
+   */
   async getOrSet(key, fetcher, options) {
     return this.trackMetrics(() => this.cache.getOrSet(this.qualify(key), fetcher, this.qualifyGetOptions(options)));
   }
@@ -205,24 +216,69 @@ var CacheNamespace = class _CacheNamespace {
   async getOrThrow(key, fetcher, options) {
     return this.trackMetrics(() => this.cache.getOrThrow(this.qualify(key), fetcher, this.qualifyGetOptions(options)));
   }
+  /**
+   * Returns true when the namespaced key exists and has not expired in any layer.
+   */
   async has(key) {
     return this.trackMetrics(() => this.cache.has(this.qualify(key)));
   }
+  /**
+   * Returns the remaining TTL in milliseconds for the namespaced key.
+   */
   async ttl(key) {
     return this.trackMetrics(() => this.cache.ttl(this.qualify(key)));
   }
+  /**
+   * Stores a value under a namespaced key.
+   */
   async set(key, value, options) {
     await this.trackMetrics(() => this.cache.set(this.qualify(key), value, this.qualifyWriteOptions(options)));
   }
+  /**
+   * Deletes a namespaced key from all layers.
+   */
   async delete(key) {
     await this.trackMetrics(() => this.cache.delete(this.qualify(key)));
   }
+  /**
+   * Deletes multiple namespaced keys from all layers.
+   */
   async mdelete(keys) {
     await this.trackMetrics(() => this.cache.mdelete(keys.map((k) => this.qualify(k))));
   }
+  /**
+   * Alias for `delete(key)` scoped to this namespace.
+   */
+  async invalidateByKey(key) {
+    await this.trackMetrics(() => this.cache.invalidateByKey(this.qualify(key)));
+  }
+  /**
+   * Alias for `mdelete(keys)` scoped to this namespace.
+   */
+  async invalidateByKeys(keys) {
+    await this.trackMetrics(() => this.cache.invalidateByKeys(keys.map((k) => this.qualify(k))));
+  }
+  /**
+   * Marks one exact namespaced key expired without deleting its stale value.
+   */
+  async expireByKey(key) {
+    await this.trackMetrics(() => this.cache.expireByKey(this.qualify(key)));
+  }
+  /**
+   * Marks multiple exact namespaced keys expired without deleting their stale values.
+   */
+  async expireByKeys(keys) {
+    await this.trackMetrics(() => this.cache.expireByKeys(keys.map((k) => this.qualify(k))));
+  }
+  /**
+   * Clears all keys in this namespace by invalidating the namespace prefix.
+   */
   async clear() {
     await this.trackMetrics(() => this.cache.invalidateByPrefix(this.prefix));
   }
+  /**
+   * Reads many namespaced keys concurrently.
+   */
   async mget(entries) {
     return this.trackMetrics(
       () => this.cache.mget(
@@ -234,6 +290,9 @@ var CacheNamespace = class _CacheNamespace {
       )
     );
   }
+  /**
+   * Writes many namespaced entries concurrently.
+   */
   async mset(entries) {
     await this.trackMetrics(
       () => this.cache.mset(
@@ -245,12 +304,21 @@ var CacheNamespace = class _CacheNamespace {
       )
     );
   }
+  /**
+   * Deletes keys associated with a tag scoped to this namespace.
+   */
   async invalidateByTag(tag) {
     await this.trackMetrics(() => this.cache.invalidateByTag(this.qualifyTag(tag)));
   }
+  /**
+   * Expires keys associated with a tag scoped to this namespace while preserving stale windows.
+   */
   async expireByTag(tag) {
     await this.trackMetrics(() => this.cache.expireByTag(this.qualifyTag(tag)));
   }
+  /**
+   * Deletes keys associated with any or all namespace-scoped tags.
+   */
   async invalidateByTags(tags, mode = "any") {
     await this.trackMetrics(
       () => this.cache.invalidateByTags(
@@ -259,6 +327,9 @@ var CacheNamespace = class _CacheNamespace {
       )
     );
   }
+  /**
+   * Expires keys associated with any or all namespace-scoped tags while preserving stale windows.
+   */
   async expireByTags(tags, mode = "any") {
     await this.trackMetrics(
       () => this.cache.expireByTags(
@@ -267,15 +338,27 @@ var CacheNamespace = class _CacheNamespace {
       )
     );
   }
+  /**
+   * Deletes namespaced keys matching a wildcard pattern.
+   */
   async invalidateByPattern(pattern) {
     await this.trackMetrics(() => this.cache.invalidateByPattern(this.qualify(pattern)));
   }
+  /**
+   * Expires namespaced keys matching a wildcard pattern while preserving stale windows.
+   */
   async expireByPattern(pattern) {
     await this.trackMetrics(() => this.cache.expireByPattern(this.qualify(pattern)));
   }
+  /**
+   * Deletes namespaced keys with the provided prefix.
+   */
   async invalidateByPrefix(prefix) {
     await this.trackMetrics(() => this.cache.invalidateByPrefix(this.qualify(prefix)));
   }
+  /**
+   * Expires namespaced keys with the provided prefix while preserving stale windows.
+   */
   async expireByPrefix(prefix) {
     await this.trackMetrics(() => this.cache.expireByPrefix(this.qualify(prefix)));
   }
@@ -292,9 +375,15 @@ var CacheNamespace = class _CacheNamespace {
       tags: result.tags.filter((tag) => tag.startsWith(`${this.prefix}:`)).map((tag) => tag.slice(this.prefix.length + 1))
     };
   }
+  /**
+   * Returns a cached wrapper whose generated keys are scoped to this namespace.
+   */
   wrap(keyPrefix, fetcher, options) {
     return this.cache.wrap(`${this.prefix}:${keyPrefix}`, fetcher, this.qualifyWrapOptions(options));
   }
+  /**
+   * Warms entries after qualifying each key and tag with this namespace prefix.
+   */
   warm(entries, options) {
     return this.cache.warm(
       entries.map((entry) => ({
@@ -305,9 +394,15 @@ var CacheNamespace = class _CacheNamespace {
       options
     );
   }
+  /**
+   * Returns metrics accumulated by operations performed through this namespace.
+   */
   getMetrics() {
     return cloneNamespaceMetrics(this.metrics);
   }
+  /**
+   * Returns hit-rate statistics for operations performed through this namespace.
+   */
   getHitRate() {
     return computeNamespaceHitRate(this.metrics);
   }
@@ -324,6 +419,9 @@ var CacheNamespace = class _CacheNamespace {
     validateNamespaceKey(childPrefix);
     return new _CacheNamespace(this.cache, `${this.prefix}:${childPrefix}`);
   }
+  /**
+   * Qualifies a raw key with this namespace prefix.
+   */
   qualify(key) {
     return `${this.prefix}:${key}`;
   }
@@ -1060,7 +1158,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();
   }
@@ -1119,10 +1219,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);
     }
   }
 };
@@ -1256,22 +1359,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()) {
@@ -1395,7 +1504,15 @@ var CacheStackReader = class {
       }
       await this.options.sleep(pollIntervalMs);
     }
-    return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext);
+    if (!this.options.singleFlightCoordinator) {
+      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)
+    );
   }
   async fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext = {
     key,
@@ -2447,6 +2564,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();
   }
@@ -2536,12 +2654,12 @@ 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);
     }
   }
 };
@@ -2558,10 +2676,16 @@ var TagIndex = class {
   constructor(options = {}) {
     this.maxKnownKeys = options.maxKnownKeys ?? 1e5;
   }
+  /**
+   * Records a key as known without changing tag assignments.
+   */
   async touch(key) {
     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();
@@ -2582,17 +2706,29 @@ var TagIndex = class {
       this.tagToKeys.set(tag, keys);
     }
   }
+  /**
+   * Removes a key from all tag mappings and known-key tracking.
+   */
   async remove(key) {
     this.removeKey(key);
   }
+  /**
+   * Returns keys currently associated with a tag.
+   */
   async keysForTag(tag) {
     return [...this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()];
   }
+  /**
+   * Visits keys currently associated with a tag.
+   */
   async forEachKeyForTag(tag, visitor) {
     for (const key of this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()) {
       await visitor(key);
     }
   }
+  /**
+   * Returns known keys that start with a prefix.
+   */
   async keysForPrefix(prefix) {
     const node = this.findNode(prefix);
     if (!node) {
@@ -2602,6 +2738,9 @@ var TagIndex = class {
     this.collectFromNode(node, prefix, matches);
     return matches;
   }
+  /**
+   * Visits known keys that start with a prefix.
+   */
   async forEachKeyForPrefix(prefix, visitor) {
     const node = this.findNode(prefix);
     if (!node) {
@@ -2609,20 +2748,32 @@ var TagIndex = class {
     }
     await this.visitFromNode(node, prefix, visitor);
   }
+  /**
+   * Returns the tags currently associated with a key.
+   */
   async tagsForKey(key) {
     return [...this.keyToTags.get(key) ?? /* @__PURE__ */ new Set()];
   }
+  /**
+   * 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];
   }
+  /**
+   * Visits known keys matching a wildcard pattern.
+   */
   async forEachKeyMatchingPattern(pattern, visitor) {
     const matches = await this.matchPattern(pattern);
     for (const key of matches) {
       await visitor(key);
     }
   }
+  /**
+   * Clears all tag and known-key index state.
+   */
   async clear() {
     this.tagToKeys.clear();
     this.keyToTags.clear();
@@ -2640,6 +2791,9 @@ var TagIndex = class {
   }
   insertKnownKey(key) {
     const isNew = !this.knownKeys.has(key);
+    if (!isNew) {
+      this.knownKeys.delete(key);
+    }
     this.knownKeys.set(key, Date.now());
     if (!isNew) {
       return;
@@ -2738,13 +2892,13 @@ var TagIndex = class {
     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) {
@@ -2797,9 +2951,15 @@ var TagIndex = class {
 
 // src/serialization/JsonSerializer.ts
 var JsonSerializer = class {
+  /**
+   * Serializes a value to JSON.
+   */
   serialize(value) {
     return JSON.stringify(value);
   }
+  /**
+   * Parses JSON and sanitizes the result before returning it.
+   */
   deserialize(payload) {
     const normalized = Buffer.isBuffer(payload) ? payload.toString("utf8") : payload;
     let parsed;
@@ -2826,6 +2986,9 @@ var StampedeGuard = class {
     this.maxInFlight = options.maxInFlight ?? 1e4;
     this.entryTimeoutMs = options.entryTimeoutMs;
   }
+  /**
+   * Deduplicates concurrent work for the same key in this process.
+   */
   async execute(key, task) {
     const existing = this.inFlight.get(key);
     if (existing) {
@@ -2925,6 +3088,9 @@ var DebugLogger = class {
   }
 };
 var CacheStack = class extends import_node_events.EventEmitter {
+  /**
+   * Creates a cache stack from ordered layers and optional global behavior settings.
+   */
   constructor(layers, options = {}) {
     super();
     this.layers = layers;
@@ -3190,6 +3356,10 @@ var CacheStack = class extends import_node_events.EventEmitter {
       });
     });
   }
+  /**
+   * Clears every configured layer, removes tag metadata, resets internal TTL
+   * profiles, and broadcasts a clear invalidation message.
+   */
   async clear() {
     await this.awaitStartup("clear");
     this.maintenance.beginClearEpoch();
@@ -3219,6 +3389,58 @@ var CacheStack = class extends import_node_events.EventEmitter {
       operation: "delete"
     });
   }
+  /**
+   * Alias for `delete(key)` that matches the `invalidateBy*` API family.
+   */
+  async invalidateByKey(key) {
+    await this.delete(key);
+  }
+  /**
+   * Alias for `mdelete(keys)` that matches the `invalidateBy*` API family.
+   */
+  async invalidateByKeys(keys) {
+    await this.mdelete(keys);
+  }
+  /**
+   * Marks one exact key expired without deleting its stale value.
+   */
+  async expireByKey(key) {
+    await this.observeOperation("layercache.expire_by_key", { "layercache.key": String(key ?? "") }, async () => {
+      const normalizedKey = this.qualifyKey(validateCacheKey(key));
+      await this.awaitStartup("expireByKey");
+      await this.expireKeys([normalizedKey]);
+      await this.publishInvalidation({
+        scope: "key",
+        keys: [normalizedKey],
+        sourceId: this.instanceId,
+        operation: "expire"
+      });
+    });
+  }
+  /**
+   * Marks multiple exact keys expired without deleting their stale values.
+   */
+  async expireByKeys(keys) {
+    await this.observeOperation("layercache.expire_by_keys", void 0, async () => {
+      if (keys.length === 0) {
+        return;
+      }
+      const normalizedKeys = keys.map((k) => validateCacheKey(k));
+      const cacheKeys = normalizedKeys.map((key) => this.qualifyKey(key));
+      await this.awaitStartup("expireByKeys");
+      await this.expireKeys(cacheKeys);
+      await this.publishInvalidation({
+        scope: "keys",
+        keys: cacheKeys,
+        sourceId: this.instanceId,
+        operation: "expire"
+      });
+    });
+  }
+  /**
+   * Reads many keys concurrently. Simple reads use layer-level bulk fast paths;
+   * entries with fetchers or options fall back to per-entry read-through logic.
+   */
   async mget(entries) {
     return this.observeOperation("layercache.mget", void 0, async () => {
       this.assertActive("mget");
@@ -3306,6 +3528,10 @@ var CacheStack = class extends import_node_events.EventEmitter {
       return normalizedEntries.map((entry) => resultsByKey.get(entry.key) ?? null);
     });
   }
+  /**
+   * Writes many entries concurrently using each layer's bulk write fast path
+   * when available.
+   */
   async mset(entries) {
     await this.observeOperation("layercache.mset", void 0, async () => {
       this.assertActive("mset");
@@ -3318,6 +3544,10 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.writeBatch(normalizedEntries);
     });
   }
+  /**
+   * Pre-populates cache entries by running their fetchers with bounded
+   * concurrency. Higher-priority entries run first.
+   */
   async warm(entries, options = {}) {
     this.assertActive("warm");
     const concurrency = Math.max(1, options.concurrency ?? 4);
@@ -3368,6 +3598,10 @@ var CacheStack = class extends import_node_events.EventEmitter {
     validateNamespaceKey(prefix);
     return new CacheNamespace(this, prefix);
   }
+  /**
+   * Deletes every key currently associated with `tag` and broadcasts an
+   * invalidation message.
+   */
   async invalidateByTag(tag) {
     await this.observeOperation("layercache.invalidate_by_tag", void 0, async () => {
       validateTag(tag);
@@ -3377,6 +3611,10 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
     });
   }
+  /**
+   * Marks every key associated with `tag` as expired while preserving stale
+   * windows for stale serving.
+   */
   async expireByTag(tag) {
     await this.observeOperation("layercache.expire_by_tag", void 0, async () => {
       validateTag(tag);
@@ -3386,6 +3624,10 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "expire" });
     });
   }
+  /**
+   * Deletes keys associated with any or all of the provided tags and broadcasts
+   * an invalidation message.
+   */
   async invalidateByTags(tags, mode = "any") {
     await this.observeOperation("layercache.invalidate_by_tags", void 0, async () => {
       if (tags.length === 0) {
@@ -3402,6 +3644,10 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
     });
   }
+  /**
+   * Marks keys associated with any or all of the provided tags as expired while
+   * preserving stale windows for stale serving.
+   */
   async expireByTags(tags, mode = "any") {
     await this.observeOperation("layercache.expire_by_tags", void 0, async () => {
       if (tags.length === 0) {
@@ -3418,6 +3664,9 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "expire" });
     });
   }
+  /**
+   * Deletes keys matching a wildcard pattern such as `user:*`.
+   */
   async invalidateByPattern(pattern) {
     await this.observeOperation("layercache.invalidate_by_pattern", void 0, async () => {
       validatePattern(pattern);
@@ -3430,6 +3679,10 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
     });
   }
+  /**
+   * Marks keys matching a wildcard pattern as expired while preserving stale
+   * windows for stale serving.
+   */
   async expireByPattern(pattern) {
     await this.observeOperation("layercache.expire_by_pattern", void 0, async () => {
       validatePattern(pattern);
@@ -3442,6 +3695,9 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "expire" });
     });
   }
+  /**
+   * Deletes keys that start with the provided prefix.
+   */
   async invalidateByPrefix(prefix) {
     await this.observeOperation("layercache.invalidate_by_prefix", void 0, async () => {
       await this.awaitStartup("invalidateByPrefix");
@@ -3451,6 +3707,10 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
     });
   }
+  /**
+   * Marks keys that start with the provided prefix as expired while preserving
+   * stale windows for stale serving.
+   */
   async expireByPrefix(prefix) {
     await this.observeOperation("layercache.expire_by_prefix", void 0, async () => {
       await this.awaitStartup("expireByPrefix");
@@ -3460,9 +3720,15 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "expire" });
     });
   }
+  /**
+   * Returns cumulative cache metrics since startup or the last `resetMetrics()`.
+   */
   getMetrics() {
     return this.metricsCollector.snapshot;
   }
+  /**
+   * Returns metrics plus layer degradation state and active background refresh count.
+   */
   getStats() {
     return {
       metrics: this.getMetrics(),
@@ -3474,6 +3740,9 @@ var CacheStack = class extends import_node_events.EventEmitter {
       backgroundRefreshes: this.reader.activeRefreshCount
     };
   }
+  /**
+   * Resets cumulative metrics counters.
+   */
   resetMetrics() {
     this.metricsCollector.reset();
   }
@@ -3483,6 +3752,10 @@ var CacheStack = class extends import_node_events.EventEmitter {
   getHitRate() {
     return this.metricsCollector.hitRate();
   }
+  /**
+   * Runs each layer's `ping()` hook when available and returns per-layer health
+   * and latency information.
+   */
   async healthCheck() {
     await this.startup;
     return Promise.all(
@@ -3526,6 +3799,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.
@@ -3567,22 +3846,38 @@ var CacheStack = class extends import_node_events.EventEmitter {
     const tags = await this.getTagsForKey(normalizedKey);
     return { key: userKey, foundInLayers, freshTtlMs, staleTtlMs, errorTtlMs, isStale, tags };
   }
+  /**
+   * Exports cache entries from configured layers for process-local snapshots.
+   */
   async exportState() {
     await this.awaitStartup("exportState");
     return this.snapshots.exportState(this.snapshotMaxEntries());
   }
+  /**
+   * Imports entries produced by `exportState()` into the configured layers.
+   */
   async importState(entries) {
     await this.awaitStartup("importState");
     await this.snapshots.importState(entries);
   }
+  /**
+   * Writes a snapshot file containing current cache entries.
+   */
   async persistToFile(filePath) {
     this.assertActive("persistToFile");
     await this.snapshots.persistToFile(filePath, this.options.snapshotBaseDir, this.snapshotMaxEntries());
   }
+  /**
+   * Restores cache entries from a snapshot file.
+   */
   async restoreFromFile(filePath) {
     this.assertActive("restoreFromFile");
     await this.snapshots.restoreFromFile(filePath, this.options.snapshotBaseDir, this.snapshotMaxBytes());
   }
+  /**
+   * Flushes background work, unsubscribes from buses, disposes timers, and then
+   * disposes each layer that provides `dispose()`.
+   */
   async disconnect() {
     if (!this.disconnectPromise) {
       this.isDisconnecting = true;
@@ -4067,12 +4362,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;
@@ -4081,7 +4429,11 @@ 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.
+   */
   async subscribe(handler) {
     const previousPromise = this.subscribePromise;
     let resolveThis;
@@ -4113,8 +4465,11 @@ 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;
@@ -4125,10 +4480,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;
@@ -4153,6 +4509,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 });
@@ -4161,22 +4545,41 @@ 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.
+   */
   async touch(key) {
     await this.client.sadd(this.knownKeysKeyFor(key), key);
   }
+  /**
+   * Replaces the tags associated with a key and records the key as known.
+   */
   async track(key, tags) {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
@@ -4194,20 +4597,32 @@ var RedisTagIndex = class {
     }
     await pipeline.exec();
   }
+  /**
+   * Removes a key from all tag mappings and known-key tracking.
+   */
   async remove(key) {
     const keyTagsKey = this.keyTagsKey(key);
     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);
     }
     await pipeline.exec();
   }
+  /**
+   * Returns keys currently associated with a tag.
+   */
   async keysForTag(tag) {
     return this.client.smembers(this.tagKeysKey(tag));
   }
+  /**
+   * Visits keys currently associated with a tag.
+   */
   async forEachKeyForTag(tag, visitor) {
     let cursor = "0";
     const tagKey = this.tagKeysKey(tag);
@@ -4219,38 +4634,56 @@ var RedisTagIndex = class {
       }
     } while (cursor !== "0");
   }
+  /**
+   * 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);
           }
         }
       } while (cursor !== "0");
     }
   }
+  /**
+   * Returns the tags currently associated with a key.
+   */
   async tagsForKey(key) {
     return this.client.smembers(this.keyTagsKey(key));
   }
+  /**
+   * 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(
@@ -4262,13 +4695,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(
@@ -4281,13 +4722,17 @@ 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);
           }
         }
       } while (cursor !== "0");
     }
   }
+  /**
+   * Clears all Redis tag-index state under this prefix.
+   */
   async clear() {
     const indexKeys = await this.scanIndexKeys();
     if (indexKeys.length === 0) {
@@ -4295,6 +4740,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";
@@ -4312,12 +4782,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)}`;
   }
@@ -4327,7 +4825,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.");
@@ -4423,6 +4921,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()));
@@ -4438,7 +4971,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");
@@ -4454,12 +4987,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);
         };
       }
@@ -4469,14 +5004,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
@@ -4507,35 +5036,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
@@ -4627,6 +5160,9 @@ var MemoryLayer = class {
   onEvict;
   entries = /* @__PURE__ */ new Map();
   cleanupTimer;
+  /**
+   * Creates an in-memory cache layer.
+   */
   constructor(options = {}) {
     this.name = options.name ?? "memory";
     this.defaultTtl = options.ttl;
@@ -4640,10 +5176,16 @@ var MemoryLayer = class {
       this.cleanupTimer.unref?.();
     }
   }
+  /**
+   * Reads and unwraps a fresh value from memory.
+   */
   async get(key) {
     const value = await this.getEntry(key);
     return unwrapStoredValue(value);
   }
+  /**
+   * Reads the raw stored value or envelope from memory.
+   */
   async getEntry(key) {
     const entry = this.entries.get(key);
     if (!entry) {
@@ -4662,12 +5204,21 @@ var MemoryLayer = class {
     }
     return entry.value;
   }
+  /**
+   * Reads many raw entries from memory.
+   */
   async getMany(keys) {
     return Promise.all(keys.map((key) => this.getEntry(key)));
   }
+  /**
+   * Writes many entries to memory.
+   */
   async setMany(entries) {
     await Promise.all(entries.map((entry) => this.set(entry.key, entry.value, entry.ttl)));
   }
+  /**
+   * Stores a value in memory using the provided TTL or layer default TTL.
+   */
   async set(key, value, ttl = this.defaultTtl) {
     this.entries.delete(key);
     this.entries.set(key, {
@@ -4680,6 +5231,9 @@ var MemoryLayer = class {
       this.evict();
     }
   }
+  /**
+   * Returns true when the key exists and has not expired.
+   */
   async has(key) {
     const entry = this.entries.get(key);
     if (!entry) {
@@ -4691,6 +5245,9 @@ var MemoryLayer = class {
     }
     return true;
   }
+  /**
+   * Returns remaining TTL in milliseconds, or null when absent or non-expiring.
+   */
   async ttl(key) {
     const entry = this.entries.get(key);
     if (!entry) {
@@ -4705,40 +5262,67 @@ var MemoryLayer = class {
     }
     return Math.max(0, Math.ceil(entry.expiresAt - Date.now()));
   }
+  /**
+   * Returns the number of currently retained, non-expired entries.
+   */
   async size() {
     this.pruneExpired();
     return this.entries.size;
   }
+  /**
+   * Deletes a key from memory.
+   */
   async delete(key) {
     this.entries.delete(key);
   }
+  /**
+   * Deletes multiple keys from memory.
+   */
   async deleteMany(keys) {
     for (const key of keys) {
       this.entries.delete(key);
     }
   }
+  /**
+   * Removes all entries from memory.
+   */
   async clear() {
     this.entries.clear();
   }
+  /**
+   * Health check hook that always succeeds for the in-process layer.
+   */
   async ping() {
     return true;
   }
+  /**
+   * Stops the cleanup timer, when one is active.
+   */
   async dispose() {
     if (this.cleanupTimer) {
       clearInterval(this.cleanupTimer);
       this.cleanupTimer = void 0;
     }
   }
+  /**
+   * Returns all currently retained, non-expired keys.
+   */
   async keys() {
     this.pruneExpired();
     return [...this.entries.keys()];
   }
+  /**
+   * Visits all currently retained, non-expired keys.
+   */
   async forEachKey(visitor) {
     this.pruneExpired();
     for (const key of this.entries.keys()) {
       await visitor(key);
     }
   }
+  /**
+   * Exports memory entries for process-local snapshots.
+   */
   exportState() {
     this.pruneExpired();
     return [...this.entries.entries()].map(([key, entry]) => ({
@@ -4747,6 +5331,9 @@ var MemoryLayer = class {
       expiresAt: entry.expiresAt
     }));
   }
+  /**
+   * Imports entries previously produced by `exportState()`.
+   */
   importState(entries) {
     for (const entry of entries) {
       if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
@@ -4826,6 +5413,9 @@ var RedisLayer = class {
   decompressionMaxBytes;
   commandTimeoutMs;
   disconnectOnDispose;
+  /**
+   * Creates a Redis cache layer using an existing ioredis client.
+   */
   constructor(options) {
     this.client = options.client;
     this.defaultTtl = options.ttl;
@@ -4840,10 +5430,16 @@ var RedisLayer = class {
     this.commandTimeoutMs = this.normalizeCommandTimeoutMs(options.commandTimeoutMs);
     this.disconnectOnDispose = options.disconnectOnDispose ?? false;
   }
+  /**
+   * Reads and unwraps a fresh value from Redis.
+   */
   async get(key) {
     const payload = await this.getEntry(key);
     return unwrapStoredValue(payload);
   }
+  /**
+   * Reads the raw stored value or envelope from Redis.
+   */
   async getEntry(key) {
     this.validateKey(key);
     const payload = await this.runCommand(
@@ -4855,6 +5451,9 @@ var RedisLayer = class {
     }
     return this.deserializeOrDelete(key, payload);
   }
+  /**
+   * Reads many raw entries from Redis using a pipeline.
+   */
   async getMany(keys) {
     if (keys.length === 0) {
       return [];
@@ -4880,6 +5479,9 @@ var RedisLayer = class {
       })
     );
   }
+  /**
+   * Writes many entries to Redis using a pipeline.
+   */
   async setMany(entries) {
     if (entries.length === 0) {
       return;
@@ -4900,6 +5502,9 @@ var RedisLayer = class {
     }
     await this.runCommand(`mset(${entries.length})`, () => pipeline.exec());
   }
+  /**
+   * Stores a value in Redis using the provided TTL or layer default TTL.
+   */
   async set(key, value, ttl = this.defaultTtl) {
     this.validateKey(key);
     const serialized = this.primarySerializer().serialize(value);
@@ -4914,10 +5519,16 @@ var RedisLayer = class {
     }
     await this.runCommand(`set(${this.displayKey(key)})`, () => this.client.set(normalizedKey, payload));
   }
+  /**
+   * Deletes a key from Redis.
+   */
   async delete(key) {
     this.validateKey(key);
     await this.runCommand(`delete(${this.displayKey(key)})`, () => this.client.del(this.withPrefix(key)));
   }
+  /**
+   * Deletes multiple keys from Redis in batches.
+   */
   async deleteMany(keys) {
     if (keys.length === 0) {
       return;
@@ -4930,11 +5541,17 @@ var RedisLayer = class {
       () => this.client.del(...keys.map((key) => this.withPrefix(key)))
     );
   }
+  /**
+   * Returns true when the key exists in Redis.
+   */
   async has(key) {
     this.validateKey(key);
     const exists = await this.runCommand(`has(${this.displayKey(key)})`, () => this.client.exists(this.withPrefix(key)));
     return exists > 0;
   }
+  /**
+   * Returns remaining Redis TTL in milliseconds, or null when absent or non-expiring.
+   */
   async ttl(key) {
     this.validateKey(key);
     const remaining = await this.runCommand(
@@ -4946,6 +5563,9 @@ var RedisLayer = class {
     }
     return remaining;
   }
+  /**
+   * Returns the number of keys under this layer's prefix.
+   */
   async size() {
     if (!this.prefix) {
       return this.runCommand("dbsize()", () => this.client.dbsize());
@@ -4963,6 +5583,9 @@ var RedisLayer = class {
     } while (cursor !== "0");
     return count;
   }
+  /**
+   * Runs a Redis ping command.
+   */
   async ping() {
     try {
       return await this.runCommand("ping()", () => this.client.ping()) === "PONG";
@@ -4970,6 +5593,9 @@ var RedisLayer = class {
       return false;
     }
   }
+  /**
+   * Disconnects the Redis client when `disconnectOnDispose` is enabled.
+   */
   async dispose() {
     if (this.disconnectOnDispose) {
       this.client.disconnect();
@@ -5002,6 +5628,9 @@ var RedisLayer = class {
       }
     } while (cursor !== "0");
   }
+  /**
+   * Returns keys under this layer's prefix without the prefix included.
+   */
   async keys() {
     const pattern = `${this.prefix}*`;
     const keys = await this.scanKeys(pattern);
@@ -5010,6 +5639,9 @@ var RedisLayer = class {
     }
     return keys.map((key) => key.slice(this.prefix.length));
   }
+  /**
+   * Visits keys under this layer's prefix without materializing all results.
+   */
   async forEachKey(visitor) {
     const pattern = `${this.prefix}*`;
     let cursor = "0";
@@ -5231,12 +5863,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";
@@ -5249,11 +5881,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. */
@@ -5300,8 +5932,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]);
@@ -5312,7 +5944,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);
@@ -5325,15 +5957,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."
       );
@@ -5367,6 +5999,9 @@ var DiskLayer = class {
   maxEntryBytes;
   protection;
   writeQueue = Promise.resolve();
+  /**
+   * Creates a disk-backed cache layer.
+   */
   constructor(options) {
     this.directory = this.resolveDirectory(options.directory);
     this.defaultTtl = options.ttl;
@@ -5379,9 +6014,15 @@ var DiskLayer = class {
       signingKey: options.signingKey
     });
   }
+  /**
+   * Reads and unwraps a fresh value from disk.
+   */
   async get(key) {
     return unwrapStoredValue(await this.getEntry(key));
   }
+  /**
+   * Reads the raw stored value or envelope from disk.
+   */
   async getEntry(key) {
     const filePath = this.keyToPath(key);
     const raw = await this.readEntryFile(filePath);
@@ -5401,6 +6042,9 @@ var DiskLayer = class {
     }
     return entry.value;
   }
+  /**
+   * Stores a value on disk using the provided TTL or layer default TTL.
+   */
   async set(key, value, ttl = this.defaultTtl) {
     await this.enqueueWrite(async () => {
       await import_node_fs2.promises.mkdir(this.directory, { recursive: true });
@@ -5413,7 +6057,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);
@@ -5426,16 +6070,28 @@ var DiskLayer = class {
       }
     });
   }
+  /**
+   * Reads many raw entries from disk.
+   */
   async getMany(keys) {
     return Promise.all(keys.map((key) => this.getEntry(key)));
   }
+  /**
+   * Writes many entries to disk.
+   */
   async setMany(entries) {
     await Promise.all(entries.map((entry) => this.set(entry.key, entry.value, entry.ttl)));
   }
+  /**
+   * Returns true when the key exists and has not expired.
+   */
   async has(key) {
     const value = await this.getEntry(key);
     return value !== null;
   }
+  /**
+   * Returns remaining TTL in milliseconds, or null when absent or non-expiring.
+   */
   async ttl(key) {
     const filePath = this.keyToPath(key);
     const raw = await this.readEntryFile(filePath);
@@ -5458,14 +6114,23 @@ var DiskLayer = class {
     }
     return remaining;
   }
+  /**
+   * Deletes a key from disk.
+   */
   async delete(key) {
     await this.enqueueWrite(() => this.safeDelete(this.keyToPath(key)));
   }
+  /**
+   * Deletes multiple keys from disk.
+   */
   async deleteMany(keys) {
     await this.enqueueWrite(async () => {
       await this.deletePathsWithConcurrency(keys.map((key) => this.keyToPath(key)));
     });
   }
+  /**
+   * Removes all cache entry files from this layer's directory.
+   */
   async clear() {
     await this.enqueueWrite(async () => {
       let entries;
@@ -5490,11 +6155,17 @@ var DiskLayer = class {
     });
     return keys;
   }
+  /**
+   * Visits all non-expired keys stored on disk.
+   */
   async forEachKey(visitor) {
     await this.scanEntries(async (entry) => {
       await visitor(entry.key);
     });
   }
+  /**
+   * Returns the number of non-expired entries stored on disk.
+   */
   async size() {
     let count = 0;
     await this.scanEntries(async () => {
@@ -5502,6 +6173,9 @@ var DiskLayer = class {
     });
     return count;
   }
+  /**
+   * Verifies the cache directory can be created.
+   */
   async ping() {
     try {
       await import_node_fs2.promises.mkdir(this.directory, { recursive: true });
@@ -5510,10 +6184,13 @@ var DiskLayer = class {
       return false;
     }
   }
+  /**
+   * Reserved for interface compatibility; DiskLayer does not hold persistent handles.
+   */
   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) {
@@ -5713,6 +6390,9 @@ var MemcachedLayer = class {
   client;
   keyPrefix;
   serializer;
+  /**
+   * Creates a Memcached cache layer using a compatible client.
+   */
   constructor(options) {
     this.client = options.client;
     this.defaultTtl = options.ttl;
@@ -5720,9 +6400,15 @@ var MemcachedLayer = class {
     this.keyPrefix = options.keyPrefix ?? "";
     this.serializer = options.serializer ?? new JsonSerializer();
   }
+  /**
+   * Reads and unwraps a fresh value from Memcached.
+   */
   async get(key) {
     return unwrapStoredValue(await this.getEntry(key));
   }
+  /**
+   * Reads the raw stored value or envelope from Memcached.
+   */
   async getEntry(key) {
     this.validateKey(key);
     const result = await this.client.get(this.withPrefix(key));
@@ -5735,9 +6421,15 @@ var MemcachedLayer = class {
       return null;
     }
   }
+  /**
+   * Reads many raw entries from Memcached.
+   */
   async getMany(keys) {
     return Promise.all(keys.map((key) => this.getEntry(key)));
   }
+  /**
+   * Stores a value in Memcached using the provided TTL or layer default TTL.
+   */
   async set(key, value, ttl = this.defaultTtl) {
     this.validateKey(key);
     const payload = this.serializer.serialize(value);
@@ -5745,18 +6437,30 @@ var MemcachedLayer = class {
       expires: ttl && ttl > 0 ? Math.ceil(ttl / 1e3) : void 0
     });
   }
+  /**
+   * Returns true when the key exists in Memcached.
+   */
   async has(key) {
     this.validateKey(key);
     const result = await this.client.get(this.withPrefix(key));
     return result !== null && result.value !== null;
   }
+  /**
+   * Deletes a key from Memcached.
+   */
   async delete(key) {
     this.validateKey(key);
     await this.client.delete(this.withPrefix(key));
   }
+  /**
+   * Deletes multiple keys from Memcached.
+   */
   async deleteMany(keys) {
     await Promise.all(keys.map((key) => this.delete(key)));
   }
+  /**
+   * Always throws because Memcached has no safe prefix clear primitive.
+   */
   async clear() {
     throw new Error(
       "MemcachedLayer.clear() is not supported. Use a key prefix and rotate it to effectively invalidate all keys."
@@ -5784,9 +6488,15 @@ var MemcachedLayer = class {
 // src/serialization/MsgpackSerializer.ts
 var import_msgpack = require("@msgpack/msgpack");
 var MsgpackSerializer = class {
+  /**
+   * Serializes a value to MessagePack bytes.
+   */
   serialize(value) {
     return Buffer.from((0, import_msgpack.encode)(value));
   }
+  /**
+   * Decodes MessagePack bytes and sanitizes the result before returning it.
+   */
   deserialize(payload) {
     const normalized = Buffer.isBuffer(payload) ? payload : Buffer.from(payload, "latin1");
     return sanitizeStructuredData((0, import_msgpack.decode)(normalized), {
@@ -5798,7 +6508,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])
@@ -5820,9 +6530,13 @@ var RedisSingleFlightCoordinator = class {
     this.prefix = options.prefix ?? "layercache:singleflight";
     this.commandTimeoutMs = this.normalizeCommandTimeoutMs(options.commandTimeoutMs);
   }
+  /**
+   * Executes `worker` when this process acquires the Redis lock; otherwise runs
+   * `waiter` while another process owns the work.
+   */
   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")
@@ -5976,6 +6690,7 @@ function sanitizeLabel(value) {
   MemoryLayer,
   MsgpackSerializer,
   PatternMatcher,
+  RedisGenerationStore,
   RedisInvalidationBus,
   RedisLayer,
   RedisSingleFlightCoordinator,