layercache 1.4.0 → 2.1.0

package/dist/index.cjs

@@ -184,6 +184,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 +196,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 +215,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 +289,9 @@ var CacheNamespace = class _CacheNamespace {
       )
     );
   }
+  /**
+   * Writes many namespaced entries concurrently.
+   */
   async mset(entries) {
     await this.trackMetrics(
       () => this.cache.mset(
@@ -245,12 +303,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 +326,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 +337,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 +374,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 +393,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 +418,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}`;
   }
@@ -2558,10 +2655,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 +2685,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 +2717,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 +2727,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();
@@ -2797,9 +2927,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 +2962,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 +3064,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 +3332,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 +3365,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 +3504,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 +3520,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 +3574,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 +3587,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 +3600,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 +3620,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 +3640,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 +3655,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 +3671,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 +3683,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 +3696,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 +3716,9 @@ var CacheStack = class extends import_node_events.EventEmitter {
       backgroundRefreshes: this.reader.activeRefreshCount
     };
   }
+  /**
+   * Resets cumulative metrics counters.
+   */
   resetMetrics() {
     this.metricsCollector.reset();
   }
@@ -3483,6 +3728,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(
@@ -3567,22 +3816,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;
@@ -4082,6 +4347,9 @@ var RedisInvalidationBus = class {
     this.channel = options.channel ?? "layercache:invalidation";
     this.logger = options.logger;
   }
+  /**
+   * Subscribes to invalidation messages and returns an unsubscribe function.
+   */
   async subscribe(handler) {
     const previousPromise = this.subscribePromise;
     let resolveThis;
@@ -4113,6 +4381,9 @@ var RedisInvalidationBus = class {
       }
     };
   }
+  /**
+   * Publishes an invalidation message to other subscribers.
+   */
   async publish(message) {
     await this.publisher.publish(this.channel, JSON.stringify(message));
   }
@@ -4174,9 +4445,15 @@ var RedisTagIndex = class {
     this.scanCount = options.scanCount ?? 100;
     this.knownKeysShards = normalizeKnownKeysShards(options.knownKeysShards);
   }
+  /**
+   * 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,6 +4471,9 @@ 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);
@@ -4205,9 +4485,15 @@ var RedisTagIndex = class {
     }
     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,6 +4505,9 @@ 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()) {
@@ -4231,6 +4520,9 @@ var RedisTagIndex = class {
     }
     return matches;
   }
+  /**
+   * Visits known keys that start with a prefix.
+   */
   async forEachKeyForPrefix(prefix, visitor) {
     for (const knownKeysKey of this.knownKeysKeys()) {
       let cursor = "0";
@@ -4245,9 +4537,15 @@ var RedisTagIndex = class {
       } 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()) {
@@ -4267,6 +4565,9 @@ var RedisTagIndex = class {
     }
     return matches;
   }
+  /**
+   * Visits known keys matching a wildcard pattern.
+   */
   async forEachKeyMatchingPattern(pattern, visitor) {
     for (const knownKeysKey of this.knownKeysKeys()) {
       let cursor = "0";
@@ -4288,6 +4589,9 @@ var RedisTagIndex = class {
       } while (cursor !== "0");
     }
   }
+  /**
+   * Clears all Redis tag-index state under this prefix.
+   */
   async clear() {
     const indexKeys = await this.scanIndexKeys();
     if (indexKeys.length === 0) {
@@ -4627,6 +4931,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 +4947,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 +4975,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 +5002,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 +5016,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 +5033,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 +5102,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 +5184,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 +5201,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 +5222,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 +5250,9 @@ var RedisLayer = class {
       })
     );
   }
+  /**
+   * Writes many entries to Redis using a pipeline.
+   */
   async setMany(entries) {
     if (entries.length === 0) {
       return;
@@ -4900,6 +5273,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 +5290,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 +5312,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 +5334,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 +5354,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 +5364,9 @@ var RedisLayer = class {
       return false;
     }
   }
+  /**
+   * Disconnects the Redis client when `disconnectOnDispose` is enabled.
+   */
   async dispose() {
     if (this.disconnectOnDispose) {
       this.client.disconnect();
@@ -5002,6 +5399,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 +5410,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";
@@ -5367,6 +5770,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 +5785,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 +5813,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 });
@@ -5426,16 +5841,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 +5885,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 +5926,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 +5944,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,6 +5955,9 @@ var DiskLayer = class {
       return false;
     }
   }
+  /**
+   * Reserved for interface compatibility; DiskLayer does not hold persistent handles.
+   */
   async dispose() {
   }
   keyToPath(key) {
@@ -5713,6 +6161,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 +6171,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 +6192,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 +6208,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 +6259,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), {
@@ -5820,6 +6301,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 = (0, import_node_crypto5.randomUUID)();