layercache 1.4.0 → 2.1.0

package/dist/index.js

@@ -12,12 +12,12 @@ import {
   validateTag,
   validateTags,
   validateTtlPolicy
-} from "./chunk-7KMKQ6QZ.js";
+} from "./chunk-6X7NV5BG.js";
 import {
   MemoryLayer,
   TagIndex,
   createHonoCacheMiddleware
-} from "./chunk-FFZCC7EQ.js";
+} from "./chunk-IVX6ABFX.js";
 import {
   PatternMatcher,
   createStoredValueEnvelope,
@@ -157,6 +157,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 +169,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 +188,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 +262,9 @@ var CacheNamespace = class _CacheNamespace {
       )
     );
   }
+  /**
+   * Writes many namespaced entries concurrently.
+   */
   async mset(entries) {
     await this.trackMetrics(
       () => this.cache.mset(
@@ -218,12 +276,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 +299,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 +310,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 +347,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 +366,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 +391,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}`;
   }
@@ -2167,9 +2264,15 @@ var TtlResolver = 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;
@@ -2196,6 +2299,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 +2401,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 +2669,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 +2702,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 +2841,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 +2857,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 +2911,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 +2924,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 +2937,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 +2957,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 +2977,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 +2992,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 +3008,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 +3020,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 +3033,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 +3053,9 @@ var CacheStack = class extends EventEmitter {
       backgroundRefreshes: this.reader.activeRefreshCount
     };
   }
+  /**
+   * Resets cumulative metrics counters.
+   */
   resetMetrics() {
     this.metricsCollector.reset();
   }
@@ -2853,6 +3065,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(
@@ -2937,22 +3153,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;
@@ -3452,6 +3684,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;
@@ -3483,6 +3718,9 @@ var RedisInvalidationBus = class {
       }
     };
   }
+  /**
+   * Publishes an invalidation message to other subscribers.
+   */
   async publish(message) {
     await this.publisher.publish(this.channel, JSON.stringify(message));
   }
@@ -3783,6 +4021,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 +4038,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 +4059,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 +4087,9 @@ var RedisLayer = class {
       })
     );
   }
+  /**
+   * Writes many entries to Redis using a pipeline.
+   */
   async setMany(entries) {
     if (entries.length === 0) {
       return;
@@ -3857,6 +4110,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 +4127,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 +4149,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 +4171,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 +4191,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 +4201,9 @@ var RedisLayer = class {
       return false;
     }
   }
+  /**
+   * Disconnects the Redis client when `disconnectOnDispose` is enabled.
+   */
   async dispose() {
     if (this.disconnectOnDispose) {
       this.client.disconnect();
@@ -3959,6 +4236,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 +4247,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";
@@ -4324,6 +4607,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 +4622,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 +4650,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 +4678,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 +4722,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 +4763,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 +4781,9 @@ var DiskLayer = class {
     });
     return count;
   }
+  /**
+   * Verifies the cache directory can be created.
+   */
   async ping() {
     try {
       await fs2.mkdir(this.directory, { recursive: true });
@@ -4467,6 +4792,9 @@ var DiskLayer = class {
       return false;
     }
   }
+  /**
+   * Reserved for interface compatibility; DiskLayer does not hold persistent handles.
+   */
   async dispose() {
   }
   keyToPath(key) {
@@ -4670,6 +4998,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 +5008,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 +5029,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 +5045,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 +5096,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 +5138,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();