layercache 2.0.0 → 3.0.0

package/dist/index.js

@@ -12,12 +12,13 @@ import {
   validateTag,
   validateTags,
   validateTtlPolicy
-} from "./chunk-7KMKQ6QZ.js";
+} from "./chunk-NBMG7DHT.js";
 import {
   MemoryLayer,
   TagIndex,
-  createHonoCacheMiddleware
-} from "./chunk-FFZCC7EQ.js";
+  createHonoCacheMiddleware,
+  normalizeHttpCacheUrl
+} from "./chunk-5CIBABDH.js";
 import {
   PatternMatcher,
   createStoredValueEnvelope,
@@ -157,6 +158,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;
@@ -166,9 +170,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)));
   }
@@ -178,24 +189,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(
@@ -207,6 +263,9 @@ var CacheNamespace = class _CacheNamespace {
       )
     );
   }
+  /**
+   * Writes many namespaced entries concurrently.
+   */
   async mset(entries) {
     await this.trackMetrics(
       () => this.cache.mset(
@@ -218,12 +277,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(
@@ -232,6 +300,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(
@@ -240,15 +311,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)));
   }
@@ -265,9 +348,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) => ({
@@ -278,9 +367,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);
   }
@@ -297,6 +392,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}`;
   }
@@ -816,7 +914,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();
   }
@@ -875,10 +975,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);
     }
   }
 };
@@ -1012,22 +1115,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()) {
@@ -1151,7 +1260,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,
@@ -2066,6 +2183,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();
   }
@@ -2155,21 +2273,27 @@ 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/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;
@@ -2196,6 +2320,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) {
@@ -2295,6 +2422,9 @@ var DebugLogger = class {
   }
 };
 var CacheStack = class extends EventEmitter {
+  /**
+   * Creates a cache stack from ordered layers and optional global behavior settings.
+   */
   constructor(layers, options = {}) {
     super();
     this.layers = layers;
@@ -2560,6 +2690,10 @@ var CacheStack = class extends 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();
@@ -2589,6 +2723,58 @@ var CacheStack = class extends 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");
@@ -2676,6 +2862,10 @@ var CacheStack = class extends 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");
@@ -2688,6 +2878,10 @@ var CacheStack = class extends 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);
@@ -2738,6 +2932,10 @@ var CacheStack = class extends 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);
@@ -2747,6 +2945,10 @@ var CacheStack = class extends 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);
@@ -2756,6 +2958,10 @@ var CacheStack = class extends 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) {
@@ -2772,6 +2978,10 @@ var CacheStack = class extends 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) {
@@ -2788,6 +2998,9 @@ var CacheStack = class extends 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);
@@ -2800,6 +3013,10 @@ var CacheStack = class extends 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);
@@ -2812,6 +3029,9 @@ var CacheStack = class extends 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");
@@ -2821,6 +3041,10 @@ var CacheStack = class extends 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");
@@ -2830,9 +3054,15 @@ var CacheStack = class extends 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(),
@@ -2844,6 +3074,9 @@ var CacheStack = class extends EventEmitter {
       backgroundRefreshes: this.reader.activeRefreshCount
     };
   }
+  /**
+   * Resets cumulative metrics counters.
+   */
   resetMetrics() {
     this.metricsCollector.reset();
   }
@@ -2853,6 +3086,10 @@ var CacheStack = class extends 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(
@@ -2896,6 +3133,12 @@ var CacheStack = class extends 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.
@@ -2937,22 +3180,38 @@ var CacheStack = class extends 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;
@@ -3437,12 +3696,65 @@ var CacheStack = class extends 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
+import { createHash, createHmac, timingSafeEqual } from "crypto";
 var RedisInvalidationBus = class {
   channel;
   publisher;
   subscriber;
   logger;
+  signingKey;
   handlers = /* @__PURE__ */ new Set();
   sharedListener;
   subscribePromise;
@@ -3451,7 +3763,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;
@@ -3483,8 +3799,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;
@@ -3495,10 +3814,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;
@@ -3523,6 +3843,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 createHmac("sha256", this.signingKey).update(payload).digest("hex");
+  }
   reportError(message, error) {
     if (this.logger?.error) {
       this.logger.error(message, { error });
@@ -3531,6 +3879,15 @@ var RedisInvalidationBus = class {
     console.error(`[layercache] ${message}`, error);
   }
 };
+function normalizeSigningSecret(secret) {
+  const raw = Buffer.isBuffer(secret) ? secret : Buffer.from(secret, "utf8");
+  return 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 && timingSafeEqual(actualBuffer, expectedBuffer);
+}
 
 // src/http/createCacheStatsHandler.ts
 function createCacheStatsHandler(cache, options = {}) {
@@ -3628,7 +3985,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");
@@ -3644,12 +4001,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);
         };
       }
@@ -3659,14 +4018,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
@@ -3783,6 +4136,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;
@@ -3797,10 +4153,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(
@@ -3812,6 +4174,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 [];
@@ -3837,6 +4202,9 @@ var RedisLayer = class {
       })
     );
   }
+  /**
+   * Writes many entries to Redis using a pipeline.
+   */
   async setMany(entries) {
     if (entries.length === 0) {
       return;
@@ -3857,6 +4225,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);
@@ -3871,10 +4242,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;
@@ -3887,11 +4264,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(
@@ -3903,6 +4286,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());
@@ -3920,6 +4306,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";
@@ -3927,6 +4316,9 @@ var RedisLayer = class {
       return false;
     }
   }
+  /**
+   * Disconnects the Redis client when `disconnectOnDispose` is enabled.
+   */
   async dispose() {
     if (this.disconnectOnDispose) {
       this.client.disconnect();
@@ -3959,6 +4351,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);
@@ -3967,6 +4362,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";
@@ -4188,12 +4586,12 @@ var RedisLayer = class {
 };
 
 // src/layers/DiskLayer.ts
-import { createHash as createHash2, randomBytes as randomBytes4 } from "crypto";
+import { createHash as createHash3, randomBytes as randomBytes4 } from "crypto";
 import { promises as fs2 } from "fs";
 import { join, resolve } from "path";
 
 // src/internal/PayloadProtection.ts
-import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes as randomBytes3, timingSafeEqual } from "crypto";
+import { createCipheriv, createDecipheriv, createHash as createHash2, createHmac as createHmac2, randomBytes as randomBytes3, timingSafeEqual as timingSafeEqual2 } from "crypto";
 var MAGIC_ENCRYPTED = Buffer.from("LCP1:");
 var MAGIC_SIGNED = Buffer.from("LCS1:");
 var ALGORITHM = "aes-256-gcm";
@@ -4206,11 +4604,11 @@ var PayloadProtection = class {
   constructor(options) {
     if (options.encryptionKey) {
       const raw = Buffer.isBuffer(options.encryptionKey) ? options.encryptionKey : Buffer.from(options.encryptionKey, "utf8");
-      this.encryptionKey = createHash("sha256").update(raw).digest();
+      this.encryptionKey = createHash2("sha256").update(raw).digest();
     }
     if (options.signingKey && !options.encryptionKey) {
       const raw = Buffer.isBuffer(options.signingKey) ? options.signingKey : Buffer.from(options.signingKey, "utf8");
-      this.signingKey = createHash("sha256").update(raw).digest();
+      this.signingKey = createHash2("sha256").update(raw).digest();
     }
   }
   /** Returns `true` when any protection (encryption or signing) is configured. */
@@ -4282,15 +4680,15 @@ var PayloadProtection = class {
   }
   // ── Signing (HMAC-SHA256) ─────────────────────────────────────────────
   sign(payload, key) {
-    const hmac = createHmac("sha256", key).update(payload).digest();
+    const hmac = createHmac2("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 = createHmac("sha256", key).update(data).digest();
-    if (receivedHmac.length !== HMAC_LENGTH || !timingSafeEqual(receivedHmac, expectedHmac)) {
+    const expectedHmac = createHmac2("sha256", key).update(data).digest();
+    if (receivedHmac.length !== HMAC_LENGTH || !timingSafeEqual2(receivedHmac, expectedHmac)) {
       throw new PayloadProtectionError(
         "HMAC verification failed. The data may have been tampered with or the signingKey is incorrect."
       );
@@ -4324,6 +4722,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;
@@ -4336,9 +4737,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);
@@ -4358,6 +4765,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 fs2.mkdir(this.directory, { recursive: true });
@@ -4383,16 +4793,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);
@@ -4415,14 +4837,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;
@@ -4447,11 +4878,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 () => {
@@ -4459,6 +4896,9 @@ var DiskLayer = class {
     });
     return count;
   }
+  /**
+   * Verifies the cache directory can be created.
+   */
   async ping() {
     try {
       await fs2.mkdir(this.directory, { recursive: true });
@@ -4467,10 +4907,13 @@ var DiskLayer = class {
       return false;
     }
   }
+  /**
+   * Reserved for interface compatibility; DiskLayer does not hold persistent handles.
+   */
   async dispose() {
   }
   keyToPath(key) {
-    const hash = createHash2("sha256").update(key).digest("hex");
+    const hash = createHash3("sha256").update(key).digest("hex");
     return join(this.directory, `${hash}.lc`);
   }
   resolveDirectory(directory) {
@@ -4670,6 +5113,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;
@@ -4677,9 +5123,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));
@@ -4692,9 +5144,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);
@@ -4702,18 +5160,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."
@@ -4741,9 +5211,15 @@ var MemcachedLayer = class {
 // src/serialization/MsgpackSerializer.ts
 import { decode, encode } from "@msgpack/msgpack";
 var MsgpackSerializer = class {
+  /**
+   * Serializes a value to MessagePack bytes.
+   */
   serialize(value) {
     return Buffer.from(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(decode(normalized), {
@@ -4777,6 +5253,10 @@ 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 = randomUUID();
@@ -4932,6 +5412,7 @@ export {
   MemoryLayer,
   MsgpackSerializer,
   PatternMatcher,
+  RedisGenerationStore,
   RedisInvalidationBus,
   RedisLayer,
   RedisSingleFlightCoordinator,