layercache 1.1.0 → 1.2.1

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,11 +17,20 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CacheMissError: () => CacheMissError,
   CacheNamespace: () => CacheNamespace,
   CacheStack: () => CacheStack,
   DiskLayer: () => DiskLayer,
@@ -37,70 +48,96 @@ __export(index_exports, {
   cacheGraphqlResolver: () => cacheGraphqlResolver,
   createCacheStatsHandler: () => createCacheStatsHandler,
   createCachedMethodDecorator: () => createCachedMethodDecorator,
+  createExpressCacheMiddleware: () => createExpressCacheMiddleware,
   createFastifyLayercachePlugin: () => createFastifyLayercachePlugin,
+  createHonoCacheMiddleware: () => createHonoCacheMiddleware,
+  createOpenTelemetryPlugin: () => createOpenTelemetryPlugin,
   createPrometheusMetricsExporter: () => createPrometheusMetricsExporter,
   createTrpcCacheMiddleware: () => createTrpcCacheMiddleware
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/CacheStack.ts
-var import_node_crypto = require("crypto");
 var import_node_events = require("events");
-var import_node_fs = require("fs");
 
 // src/CacheNamespace.ts
-var CacheNamespace = class {
+var import_async_mutex = require("async-mutex");
+var CacheNamespace = class _CacheNamespace {
   constructor(cache, prefix) {
     this.cache = cache;
     this.prefix = prefix;
   }
   cache;
   prefix;
+  static metricsMutexes = /* @__PURE__ */ new WeakMap();
+  metrics = emptyMetrics();
   async get(key, fetcher, options) {
-    return this.cache.get(this.qualify(key), fetcher, options);
+    return this.trackMetrics(() => this.cache.get(this.qualify(key), fetcher, options));
   }
   async getOrSet(key, fetcher, options) {
-    return this.cache.getOrSet(this.qualify(key), fetcher, options);
+    return this.trackMetrics(() => this.cache.getOrSet(this.qualify(key), fetcher, options));
+  }
+  /**
+   * Like `get()`, but throws `CacheMissError` instead of returning `null`.
+   */
+  async getOrThrow(key, fetcher, options) {
+    return this.trackMetrics(() => this.cache.getOrThrow(this.qualify(key), fetcher, options));
   }
   async has(key) {
-    return this.cache.has(this.qualify(key));
+    return this.trackMetrics(() => this.cache.has(this.qualify(key)));
   }
   async ttl(key) {
-    return this.cache.ttl(this.qualify(key));
+    return this.trackMetrics(() => this.cache.ttl(this.qualify(key)));
   }
   async set(key, value, options) {
-    await this.cache.set(this.qualify(key), value, options);
+    await this.trackMetrics(() => this.cache.set(this.qualify(key), value, options));
   }
   async delete(key) {
-    await this.cache.delete(this.qualify(key));
+    await this.trackMetrics(() => this.cache.delete(this.qualify(key)));
   }
   async mdelete(keys) {
-    await this.cache.mdelete(keys.map((k) => this.qualify(k)));
+    await this.trackMetrics(() => this.cache.mdelete(keys.map((k) => this.qualify(k))));
   }
   async clear() {
-    await this.cache.invalidateByPattern(`${this.prefix}:*`);
+    await this.trackMetrics(() => this.cache.invalidateByPrefix(this.prefix));
   }
   async mget(entries) {
-    return this.cache.mget(
-      entries.map((entry) => ({
-        ...entry,
-        key: this.qualify(entry.key)
-      }))
+    return this.trackMetrics(
+      () => this.cache.mget(
+        entries.map((entry) => ({
+          ...entry,
+          key: this.qualify(entry.key)
+        }))
+      )
     );
   }
   async mset(entries) {
-    await this.cache.mset(
-      entries.map((entry) => ({
-        ...entry,
-        key: this.qualify(entry.key)
-      }))
+    await this.trackMetrics(
+      () => this.cache.mset(
+        entries.map((entry) => ({
+          ...entry,
+          key: this.qualify(entry.key)
+        }))
+      )
     );
   }
   async invalidateByTag(tag) {
-    await this.cache.invalidateByTag(tag);
+    await this.trackMetrics(() => this.cache.invalidateByTag(tag));
+  }
+  async invalidateByTags(tags, mode = "any") {
+    await this.trackMetrics(() => this.cache.invalidateByTags(tags, mode));
   }
   async invalidateByPattern(pattern) {
-    await this.cache.invalidateByPattern(this.qualify(pattern));
+    await this.trackMetrics(() => this.cache.invalidateByPattern(this.qualify(pattern)));
+  }
+  async invalidateByPrefix(prefix) {
+    await this.trackMetrics(() => this.cache.invalidateByPrefix(this.qualify(prefix)));
+  }
+  /**
+   * Returns detailed metadata about a single cache key within this namespace.
+   */
+  async inspect(key) {
+    return this.cache.inspect(this.qualify(key));
   }
   wrap(keyPrefix, fetcher, options) {
     return this.cache.wrap(`${this.prefix}:${keyPrefix}`, fetcher, options);
@@ -115,15 +152,159 @@ var CacheNamespace = class {
     );
   }
   getMetrics() {
-    return this.cache.getMetrics();
+    return cloneMetrics(this.metrics);
   }
   getHitRate() {
-    return this.cache.getHitRate();
+    const total = this.metrics.hits + this.metrics.misses;
+    const overall = total === 0 ? 0 : this.metrics.hits / total;
+    const byLayer = {};
+    const layers = /* @__PURE__ */ new Set([...Object.keys(this.metrics.hitsByLayer), ...Object.keys(this.metrics.missesByLayer)]);
+    for (const layer of layers) {
+      const hits = this.metrics.hitsByLayer[layer] ?? 0;
+      const misses = this.metrics.missesByLayer[layer] ?? 0;
+      byLayer[layer] = hits + misses === 0 ? 0 : hits / (hits + misses);
+    }
+    return { overall, byLayer };
+  }
+  /**
+   * Creates a nested namespace. Keys are prefixed with `parentPrefix:childPrefix:`.
+   *
+   * ```ts
+   * const tenant = cache.namespace('tenant:abc')
+   * const posts = tenant.namespace('posts')
+   * // keys become: "tenant:abc:posts:mykey"
+   * ```
+   */
+  namespace(childPrefix) {
+    return new _CacheNamespace(this.cache, `${this.prefix}:${childPrefix}`);
   }
   qualify(key) {
     return `${this.prefix}:${key}`;
   }
+  async trackMetrics(operation) {
+    return this.getMetricsMutex().runExclusive(async () => {
+      const before = this.cache.getMetrics();
+      const result = await operation();
+      const after = this.cache.getMetrics();
+      this.metrics = addMetrics(this.metrics, diffMetrics(before, after));
+      return result;
+    });
+  }
+  getMetricsMutex() {
+    const existing = _CacheNamespace.metricsMutexes.get(this.cache);
+    if (existing) {
+      return existing;
+    }
+    const mutex = new import_async_mutex.Mutex();
+    _CacheNamespace.metricsMutexes.set(this.cache, mutex);
+    return mutex;
+  }
 };
+function emptyMetrics() {
+  return {
+    hits: 0,
+    misses: 0,
+    fetches: 0,
+    sets: 0,
+    deletes: 0,
+    backfills: 0,
+    invalidations: 0,
+    staleHits: 0,
+    refreshes: 0,
+    refreshErrors: 0,
+    writeFailures: 0,
+    singleFlightWaits: 0,
+    negativeCacheHits: 0,
+    circuitBreakerTrips: 0,
+    degradedOperations: 0,
+    hitsByLayer: {},
+    missesByLayer: {},
+    latencyByLayer: {},
+    resetAt: Date.now()
+  };
+}
+function cloneMetrics(metrics) {
+  return {
+    ...metrics,
+    hitsByLayer: { ...metrics.hitsByLayer },
+    missesByLayer: { ...metrics.missesByLayer },
+    latencyByLayer: Object.fromEntries(
+      Object.entries(metrics.latencyByLayer).map(([key, value]) => [key, { ...value }])
+    )
+  };
+}
+function diffMetrics(before, after) {
+  const latencyByLayer = Object.fromEntries(
+    Object.entries(after.latencyByLayer).map(([layer, value]) => [
+      layer,
+      {
+        avgMs: value.avgMs,
+        maxMs: value.maxMs,
+        count: Math.max(0, value.count - (before.latencyByLayer[layer]?.count ?? 0))
+      }
+    ])
+  );
+  return {
+    hits: after.hits - before.hits,
+    misses: after.misses - before.misses,
+    fetches: after.fetches - before.fetches,
+    sets: after.sets - before.sets,
+    deletes: after.deletes - before.deletes,
+    backfills: after.backfills - before.backfills,
+    invalidations: after.invalidations - before.invalidations,
+    staleHits: after.staleHits - before.staleHits,
+    refreshes: after.refreshes - before.refreshes,
+    refreshErrors: after.refreshErrors - before.refreshErrors,
+    writeFailures: after.writeFailures - before.writeFailures,
+    singleFlightWaits: after.singleFlightWaits - before.singleFlightWaits,
+    negativeCacheHits: after.negativeCacheHits - before.negativeCacheHits,
+    circuitBreakerTrips: after.circuitBreakerTrips - before.circuitBreakerTrips,
+    degradedOperations: after.degradedOperations - before.degradedOperations,
+    hitsByLayer: diffMap(before.hitsByLayer, after.hitsByLayer),
+    missesByLayer: diffMap(before.missesByLayer, after.missesByLayer),
+    latencyByLayer,
+    resetAt: after.resetAt
+  };
+}
+function addMetrics(base, delta) {
+  return {
+    hits: base.hits + delta.hits,
+    misses: base.misses + delta.misses,
+    fetches: base.fetches + delta.fetches,
+    sets: base.sets + delta.sets,
+    deletes: base.deletes + delta.deletes,
+    backfills: base.backfills + delta.backfills,
+    invalidations: base.invalidations + delta.invalidations,
+    staleHits: base.staleHits + delta.staleHits,
+    refreshes: base.refreshes + delta.refreshes,
+    refreshErrors: base.refreshErrors + delta.refreshErrors,
+    writeFailures: base.writeFailures + delta.writeFailures,
+    singleFlightWaits: base.singleFlightWaits + delta.singleFlightWaits,
+    negativeCacheHits: base.negativeCacheHits + delta.negativeCacheHits,
+    circuitBreakerTrips: base.circuitBreakerTrips + delta.circuitBreakerTrips,
+    degradedOperations: base.degradedOperations + delta.degradedOperations,
+    hitsByLayer: addMap(base.hitsByLayer, delta.hitsByLayer),
+    missesByLayer: addMap(base.missesByLayer, delta.missesByLayer),
+    latencyByLayer: cloneMetrics(delta).latencyByLayer,
+    resetAt: base.resetAt
+  };
+}
+function diffMap(before, after) {
+  const keys = /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)]);
+  const result = {};
+  for (const key of keys) {
+    result[key] = (after[key] ?? 0) - (before[key] ?? 0);
+  }
+  return result;
+}
+function addMap(base, delta) {
+  const keys = /* @__PURE__ */ new Set([...Object.keys(base), ...Object.keys(delta)]);
+  const result = {};
+  for (const key of keys) {
+    result[key] = (base[key] ?? 0) + (delta[key] ?? 0);
+  }
+  return result;
+}
 
 // src/internal/CircuitBreakerManager.ts
 var CircuitBreakerManager = class {
@@ -217,11 +398,105 @@ var CircuitBreakerManager = class {
   }
 };
 
+// src/internal/FetchRateLimiter.ts
+var FetchRateLimiter = class {
+  active = 0;
+  queue = [];
+  startedAt = [];
+  drainTimer;
+  async schedule(options, task) {
+    if (!options) {
+      return task();
+    }
+    const normalized = this.normalize(options);
+    if (!normalized) {
+      return task();
+    }
+    return new Promise((resolve, reject) => {
+      this.queue.push({ options: normalized, task, resolve, reject });
+      this.drain();
+    });
+  }
+  normalize(options) {
+    const maxConcurrent = options.maxConcurrent;
+    const intervalMs = options.intervalMs;
+    const maxPerInterval = options.maxPerInterval;
+    if (!maxConcurrent && !(intervalMs && maxPerInterval)) {
+      return void 0;
+    }
+    return {
+      maxConcurrent,
+      intervalMs,
+      maxPerInterval
+    };
+  }
+  drain() {
+    if (this.drainTimer) {
+      clearTimeout(this.drainTimer);
+      this.drainTimer = void 0;
+    }
+    while (this.queue.length > 0) {
+      const next = this.queue[0];
+      if (!next) {
+        return;
+      }
+      const waitMs = this.waitTime(next.options);
+      if (waitMs > 0) {
+        this.drainTimer = setTimeout(() => {
+          this.drainTimer = void 0;
+          this.drain();
+        }, waitMs);
+        this.drainTimer.unref?.();
+        return;
+      }
+      this.queue.shift();
+      this.active += 1;
+      this.startedAt.push(Date.now());
+      void next.task().then(next.resolve, next.reject).finally(() => {
+        this.active -= 1;
+        this.drain();
+      });
+    }
+  }
+  waitTime(options) {
+    const now = Date.now();
+    if (options.maxConcurrent && this.active >= options.maxConcurrent) {
+      return 1;
+    }
+    if (!options.intervalMs || !options.maxPerInterval) {
+      return 0;
+    }
+    this.prune(now, options.intervalMs);
+    if (this.startedAt.length < options.maxPerInterval) {
+      return 0;
+    }
+    const oldest = this.startedAt[0];
+    if (!oldest) {
+      return 0;
+    }
+    return Math.max(1, options.intervalMs - (now - oldest));
+  }
+  prune(now, intervalMs) {
+    while (this.startedAt.length > 0) {
+      const startedAt = this.startedAt[0];
+      if (startedAt === void 0 || now - startedAt < intervalMs) {
+        break;
+      }
+      this.startedAt.shift();
+    }
+  }
+};
+
 // src/internal/MetricsCollector.ts
 var MetricsCollector = class {
   data = this.empty();
   get snapshot() {
-    return { ...this.data };
+    return {
+      ...this.data,
+      hitsByLayer: { ...this.data.hitsByLayer },
+      missesByLayer: { ...this.data.missesByLayer },
+      latencyByLayer: Object.fromEntries(Object.entries(this.data.latencyByLayer).map(([k, v]) => [k, { ...v }]))
+    };
   }
   increment(field, amount = 1) {
     ;
@@ -230,6 +505,22 @@ var MetricsCollector = class {
   incrementLayer(map, layerName) {
     this.data[map][layerName] = (this.data[map][layerName] ?? 0) + 1;
   }
+  /**
+   * Records a read latency sample for the given layer.
+   * Maintains a rolling average and max using Welford's online algorithm.
+   */
+  recordLatency(layerName, durationMs) {
+    const existing = this.data.latencyByLayer[layerName];
+    if (!existing) {
+      this.data.latencyByLayer[layerName] = { avgMs: durationMs, maxMs: durationMs, count: 1 };
+      return;
+    }
+    existing.count += 1;
+    existing.avgMs += (durationMs - existing.avgMs) / existing.count;
+    if (durationMs > existing.maxMs) {
+      existing.maxMs = durationMs;
+    }
+  }
   reset() {
     this.data = this.empty();
   }
@@ -264,6 +555,7 @@ var MetricsCollector = class {
       degradedOperations: 0,
       hitsByLayer: {},
       missesByLayer: {},
+      latencyByLayer: {},
       resetAt: Date.now()
     };
   }
@@ -391,13 +683,14 @@ var TtlResolver = class {
   clearProfiles() {
     this.accessProfiles.clear();
   }
-  resolveFreshTtl(key, layerName, kind, options, fallbackTtl, globalNegativeTtl, globalTtl) {
+  resolveFreshTtl(key, layerName, kind, options, fallbackTtl, globalNegativeTtl, globalTtl, value) {
+    const policyTtl = kind === "value" ? this.resolvePolicyTtl(key, value, options?.ttlPolicy) : void 0;
     const baseTtl = kind === "empty" ? this.resolveLayerSeconds(
       layerName,
       options?.negativeTtl,
       globalNegativeTtl,
-      this.resolveLayerSeconds(layerName, options?.ttl, globalTtl, fallbackTtl) ?? DEFAULT_NEGATIVE_TTL_SECONDS
-    ) : this.resolveLayerSeconds(layerName, options?.ttl, globalTtl, fallbackTtl);
+      this.resolveLayerSeconds(layerName, options?.ttl, globalTtl, policyTtl ?? fallbackTtl) ?? DEFAULT_NEGATIVE_TTL_SECONDS
+    ) : this.resolveLayerSeconds(layerName, options?.ttl, globalTtl, policyTtl ?? fallbackTtl);
     const adaptiveTtl = this.applyAdaptiveTtl(key, layerName, baseTtl, options?.adaptiveTtl);
     const jitter = this.resolveLayerSeconds(layerName, options?.ttlJitter, void 0);
     return this.applyJitter(adaptiveTtl, jitter);
@@ -436,6 +729,29 @@ var TtlResolver = class {
     const delta = (Math.random() * 2 - 1) * jitter;
     return Math.max(1, Math.round(ttl + delta));
   }
+  resolvePolicyTtl(key, value, policy) {
+    if (!policy) {
+      return void 0;
+    }
+    if (typeof policy === "function") {
+      return policy({ key, value });
+    }
+    const now = /* @__PURE__ */ new Date();
+    if (policy === "until-midnight") {
+      const nextMidnight = new Date(now);
+      nextMidnight.setHours(24, 0, 0, 0);
+      return Math.max(1, Math.ceil((nextMidnight.getTime() - now.getTime()) / 1e3));
+    }
+    if (policy === "next-hour") {
+      const nextHour = new Date(now);
+      nextHour.setMinutes(60, 0, 0);
+      return Math.max(1, Math.ceil((nextHour.getTime() - now.getTime()) / 1e3));
+    }
+    const alignToSeconds = policy.alignTo;
+    const currentSeconds = Math.floor(Date.now() / 1e3);
+    const nextBoundary = Math.ceil((currentSeconds + 1) / alignToSeconds) * alignToSeconds;
+    return Math.max(1, nextBoundary - currentSeconds);
+  }
   readLayerNumber(layerName, value) {
     if (typeof value === "number") {
       return value;
@@ -463,36 +779,46 @@ var PatternMatcher = class _PatternMatcher {
   /**
    * Tests whether a glob-style pattern matches a value.
    * Supports `*` (any sequence of characters) and `?` (any single character).
-   * Uses a linear-time algorithm to avoid ReDoS vulnerabilities.
+   * Uses a two-pointer algorithm to avoid ReDoS vulnerabilities and
+   * quadratic memory usage on long patterns/keys.
    */
   static matches(pattern, value) {
     return _PatternMatcher.matchLinear(pattern, value);
   }
   /**
-   * Linear-time glob matching using dynamic programming.
-   * Avoids catastrophic backtracking that RegExp-based glob matching can cause.
+   * Linear-time glob matching with O(1) extra memory.
    */
   static matchLinear(pattern, value) {
-    const m = pattern.length;
-    const n = value.length;
-    const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(false));
-    dp[0][0] = true;
-    for (let i = 1; i <= m; i++) {
-      if (pattern[i - 1] === "*") {
-        dp[i][0] = dp[i - 1]?.[0];
-      }
-    }
-    for (let i = 1; i <= m; i++) {
-      for (let j = 1; j <= n; j++) {
-        const pc = pattern[i - 1];
-        if (pc === "*") {
-          dp[i][j] = dp[i - 1]?.[j] || dp[i]?.[j - 1];
-        } else if (pc === "?" || pc === value[j - 1]) {
-          dp[i][j] = dp[i - 1]?.[j - 1];
-        }
+    let patternIndex = 0;
+    let valueIndex = 0;
+    let starIndex = -1;
+    let backtrackValueIndex = 0;
+    while (valueIndex < value.length) {
+      const patternChar = pattern[patternIndex];
+      const valueChar = value[valueIndex];
+      if (patternChar === "*" && patternIndex < pattern.length) {
+        starIndex = patternIndex;
+        patternIndex += 1;
+        backtrackValueIndex = valueIndex;
+        continue;
+      }
+      if (patternChar === "?" || patternChar === valueChar) {
+        patternIndex += 1;
+        valueIndex += 1;
+        continue;
+      }
+      if (starIndex !== -1) {
+        patternIndex = starIndex + 1;
+        backtrackValueIndex += 1;
+        valueIndex = backtrackValueIndex;
+        continue;
       }
+      return false;
     }
-    return dp[m]?.[n];
+    while (patternIndex < pattern.length && pattern[patternIndex] === "*") {
+      patternIndex += 1;
+    }
+    return patternIndex === pattern.length;
   }
 };
 
@@ -501,11 +827,17 @@ var TagIndex = class {
   tagToKeys = /* @__PURE__ */ new Map();
   keyToTags = /* @__PURE__ */ new Map();
   knownKeys = /* @__PURE__ */ new Set();
+  maxKnownKeys;
+  constructor(options = {}) {
+    this.maxKnownKeys = options.maxKnownKeys;
+  }
   async touch(key) {
     this.knownKeys.add(key);
+    this.pruneKnownKeysIfNeeded();
   }
   async track(key, tags) {
     this.knownKeys.add(key);
+    this.pruneKnownKeysIfNeeded();
     if (tags.length === 0) {
       return;
     }
@@ -524,6 +856,40 @@ var TagIndex = class {
     }
   }
   async remove(key) {
+    this.removeKey(key);
+  }
+  async keysForTag(tag) {
+    return [...this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()];
+  }
+  async keysForPrefix(prefix) {
+    return [...this.knownKeys].filter((key) => key.startsWith(prefix));
+  }
+  async tagsForKey(key) {
+    return [...this.keyToTags.get(key) ?? /* @__PURE__ */ new Set()];
+  }
+  async matchPattern(pattern) {
+    return [...this.knownKeys].filter((key) => PatternMatcher.matches(pattern, key));
+  }
+  async clear() {
+    this.tagToKeys.clear();
+    this.keyToTags.clear();
+    this.knownKeys.clear();
+  }
+  pruneKnownKeysIfNeeded() {
+    if (this.maxKnownKeys === void 0 || this.knownKeys.size <= this.maxKnownKeys) {
+      return;
+    }
+    const toRemove = Math.ceil(this.maxKnownKeys * 0.1);
+    let removed = 0;
+    for (const key of this.knownKeys) {
+      if (removed >= toRemove) {
+        break;
+      }
+      this.removeKey(key);
+      removed += 1;
+    }
+  }
+  removeKey(key) {
     this.knownKeys.delete(key);
     const tags = this.keyToTags.get(key);
     if (!tags) {
@@ -541,21 +907,10 @@ var TagIndex = class {
     }
     this.keyToTags.delete(key);
   }
-  async keysForTag(tag) {
-    return [...this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()];
-  }
-  async matchPattern(pattern) {
-    return [...this.knownKeys].filter((key) => PatternMatcher.matches(pattern, key));
-  }
-  async clear() {
-    this.tagToKeys.clear();
-    this.keyToTags.clear();
-    this.knownKeys.clear();
-  }
 };
 
 // src/stampede/StampedeGuard.ts
-var import_async_mutex = require("async-mutex");
+var import_async_mutex2 = require("async-mutex");
 var StampedeGuard = class {
   mutexes = /* @__PURE__ */ new Map();
   async execute(key, task) {
@@ -572,7 +927,7 @@ var StampedeGuard = class {
   getMutexEntry(key) {
     let entry = this.mutexes.get(key);
     if (!entry) {
-      entry = { mutex: new import_async_mutex.Mutex(), references: 0 };
+      entry = { mutex: new import_async_mutex2.Mutex(), references: 0 };
       this.mutexes.set(key, entry);
     }
     entry.references += 1;
@@ -580,6 +935,16 @@ var StampedeGuard = class {
   }
 };
 
+// src/types.ts
+var CacheMissError = class extends Error {
+  key;
+  constructor(key) {
+    super(`Cache miss for key "${key}".`);
+    this.name = "CacheMissError";
+    this.key = key;
+  }
+};
+
 // src/CacheStack.ts
 var DEFAULT_SINGLE_FLIGHT_LEASE_MS = 3e4;
 var DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS = 5e3;
@@ -623,6 +988,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
     const maxProfileEntries = options.maxProfileEntries ?? DEFAULT_MAX_PROFILE_ENTRIES;
     this.ttlResolver = new TtlResolver({ maxProfileEntries });
     this.circuitBreakerManager = new CircuitBreakerManager({ maxEntries: maxProfileEntries });
+    this.currentGeneration = options.generation;
     if (options.publishSetInvalidation !== void 0) {
       console.warn(
         "[layercache] CacheStackOptions.publishSetInvalidation is deprecated. Use broadcastL1Invalidation instead."
@@ -631,21 +997,27 @@ var CacheStack = class extends import_node_events.EventEmitter {
     const debugEnv = process.env.DEBUG?.split(",").includes("layercache:debug") ?? false;
     this.logger = typeof options.logger === "object" ? options.logger : new DebugLogger(Boolean(options.logger) || debugEnv);
     this.tagIndex = options.tagIndex ?? new TagIndex();
+    this.initializeWriteBehind(options.writeBehind);
     this.startup = this.initialize();
   }
   layers;
   options;
   stampedeGuard = new StampedeGuard();
   metricsCollector = new MetricsCollector();
-  instanceId = (0, import_node_crypto.randomUUID)();
+  instanceId = createInstanceId();
   startup;
   unsubscribeInvalidation;
   logger;
   tagIndex;
+  fetchRateLimiter = new FetchRateLimiter();
   backgroundRefreshes = /* @__PURE__ */ new Map();
   layerDegradedUntil = /* @__PURE__ */ new Map();
   ttlResolver;
   circuitBreakerManager;
+  currentGeneration;
+  writeBehindQueue = [];
+  writeBehindTimer;
+  writeBehindFlushPromise;
   isDisconnecting = false;
   disconnectPromise;
   /**
@@ -655,9 +1027,9 @@ var CacheStack = class extends import_node_events.EventEmitter {
    * and no `fetcher` is provided.
    */
   async get(key, fetcher, options) {
-    const normalizedKey = this.validateCacheKey(key);
+    const normalizedKey = this.qualifyKey(this.validateCacheKey(key));
     this.validateWriteOptions(options);
-    await this.startup;
+    await this.awaitStartup("get");
     const hit = await this.readFromLayers(normalizedKey, options, "allow-stale");
     if (hit.found) {
       this.ttlResolver.recordAccess(normalizedKey);
@@ -706,12 +1078,24 @@ var CacheStack = class extends import_node_events.EventEmitter {
   async getOrSet(key, fetcher, options) {
     return this.get(key, fetcher, options);
   }
+  /**
+   * Like `get()`, but throws `CacheMissError` instead of returning `null`.
+   * Useful when the value is expected to exist or the fetcher is expected to
+   * return non-null.
+   */
+  async getOrThrow(key, fetcher, options) {
+    const value = await this.get(key, fetcher, options);
+    if (value === null) {
+      throw new CacheMissError(key);
+    }
+    return value;
+  }
   /**
    * Returns true if the given key exists and is not expired in any layer.
    */
   async has(key) {
-    const normalizedKey = this.validateCacheKey(key);
-    await this.startup;
+    const normalizedKey = this.qualifyKey(this.validateCacheKey(key));
+    await this.awaitStartup("has");
     for (const layer of this.layers) {
       if (this.shouldSkipLayer(layer)) {
         continue;
@@ -741,8 +1125,8 @@ var CacheStack = class extends import_node_events.EventEmitter {
    * that has it, or null if the key is not found / has no TTL.
    */
   async ttl(key) {
-    const normalizedKey = this.validateCacheKey(key);
-    await this.startup;
+    const normalizedKey = this.qualifyKey(this.validateCacheKey(key));
+    await this.awaitStartup("ttl");
     for (const layer of this.layers) {
       if (this.shouldSkipLayer(layer)) {
         continue;
@@ -763,17 +1147,17 @@ var CacheStack = class extends import_node_events.EventEmitter {
    * Stores a value in all cache layers. Overwrites any existing value.
    */
   async set(key, value, options) {
-    const normalizedKey = this.validateCacheKey(key);
+    const normalizedKey = this.qualifyKey(this.validateCacheKey(key));
     this.validateWriteOptions(options);
-    await this.startup;
+    await this.awaitStartup("set");
     await this.storeEntry(normalizedKey, "value", value, options);
   }
   /**
    * Deletes the key from all layers and publishes an invalidation message.
    */
   async delete(key) {
-    const normalizedKey = this.validateCacheKey(key);
-    await this.startup;
+    const normalizedKey = this.qualifyKey(this.validateCacheKey(key));
+    await this.awaitStartup("delete");
     await this.deleteKeys([normalizedKey]);
     await this.publishInvalidation({
       scope: "key",
@@ -783,7 +1167,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
     });
   }
   async clear() {
-    await this.startup;
+    await this.awaitStartup("clear");
     await Promise.all(this.layers.map((layer) => layer.clear()));
     await this.tagIndex.clear();
     this.ttlResolver.clearProfiles();
@@ -799,23 +1183,25 @@ var CacheStack = class extends import_node_events.EventEmitter {
     if (keys.length === 0) {
       return;
     }
-    await this.startup;
+    await this.awaitStartup("mdelete");
     const normalizedKeys = keys.map((k) => this.validateCacheKey(k));
-    await this.deleteKeys(normalizedKeys);
+    const cacheKeys = normalizedKeys.map((key) => this.qualifyKey(key));
+    await this.deleteKeys(cacheKeys);
     await this.publishInvalidation({
       scope: "keys",
-      keys: normalizedKeys,
+      keys: cacheKeys,
       sourceId: this.instanceId,
       operation: "delete"
     });
   }
   async mget(entries) {
+    this.assertActive("mget");
     if (entries.length === 0) {
       return [];
     }
     const normalizedEntries = entries.map((entry) => ({
       ...entry,
-      key: this.validateCacheKey(entry.key)
+      key: this.qualifyKey(this.validateCacheKey(entry.key))
     }));
     normalizedEntries.forEach((entry) => this.validateWriteOptions(entry.options));
     const canFastPath = normalizedEntries.every((entry) => entry.fetch === void 0 && entry.options === void 0);
@@ -841,7 +1227,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
         })
       );
     }
-    await this.startup;
+    await this.awaitStartup("mget");
     const pending = /* @__PURE__ */ new Set();
     const indexesByKey = /* @__PURE__ */ new Map();
     const resultsByKey = /* @__PURE__ */ new Map();
@@ -889,14 +1275,17 @@ var CacheStack = class extends import_node_events.EventEmitter {
     return normalizedEntries.map((entry) => resultsByKey.get(entry.key) ?? null);
   }
   async mset(entries) {
+    this.assertActive("mset");
     const normalizedEntries = entries.map((entry) => ({
       ...entry,
-      key: this.validateCacheKey(entry.key)
+      key: this.qualifyKey(this.validateCacheKey(entry.key))
     }));
     normalizedEntries.forEach((entry) => this.validateWriteOptions(entry.options));
-    await Promise.all(normalizedEntries.map((entry) => this.set(entry.key, entry.value, entry.options)));
+    await this.awaitStartup("mset");
+    await this.writeBatch(normalizedEntries);
   }
   async warm(entries, options = {}) {
+    this.assertActive("warm");
     const concurrency = Math.max(1, options.concurrency ?? 4);
     const total = entries.length;
     let completed = 0;
@@ -945,14 +1334,31 @@ var CacheStack = class extends import_node_events.EventEmitter {
     return new CacheNamespace(this, prefix);
   }
   async invalidateByTag(tag) {
-    await this.startup;
+    await this.awaitStartup("invalidateByTag");
     const keys = await this.tagIndex.keysForTag(tag);
     await this.deleteKeys(keys);
     await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
   }
+  async invalidateByTags(tags, mode = "any") {
+    if (tags.length === 0) {
+      return;
+    }
+    await this.awaitStartup("invalidateByTags");
+    const keysByTag = await Promise.all(tags.map((tag) => this.tagIndex.keysForTag(tag)));
+    const keys = mode === "all" ? this.intersectKeys(keysByTag) : [...new Set(keysByTag.flat())];
+    await this.deleteKeys(keys);
+    await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
+  }
   async invalidateByPattern(pattern) {
-    await this.startup;
-    const keys = await this.tagIndex.matchPattern(pattern);
+    await this.awaitStartup("invalidateByPattern");
+    const keys = await this.tagIndex.matchPattern(this.qualifyPattern(pattern));
+    await this.deleteKeys(keys);
+    await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
+  }
+  async invalidateByPrefix(prefix) {
+    await this.awaitStartup("invalidateByPrefix");
+    const qualifiedPrefix = this.qualifyKey(this.validateCacheKey(prefix));
+    const keys = this.tagIndex.keysForPrefix ? await this.tagIndex.keysForPrefix(qualifiedPrefix) : await this.tagIndex.matchPattern(`${qualifiedPrefix}*`);
     await this.deleteKeys(keys);
     await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
   }
@@ -979,8 +1385,77 @@ var CacheStack = class extends import_node_events.EventEmitter {
   getHitRate() {
     return this.metricsCollector.hitRate();
   }
-  async exportState() {
+  async healthCheck() {
     await this.startup;
+    return Promise.all(
+      this.layers.map(async (layer) => {
+        const startedAt = performance.now();
+        try {
+          const healthy = layer.ping ? await layer.ping() : true;
+          return {
+            layer: layer.name,
+            healthy,
+            latencyMs: performance.now() - startedAt
+          };
+        } catch (error) {
+          return {
+            layer: layer.name,
+            healthy: false,
+            latencyMs: performance.now() - startedAt,
+            error: this.formatError(error)
+          };
+        }
+      })
+    );
+  }
+  bumpGeneration(nextGeneration) {
+    const current = this.currentGeneration ?? 0;
+    this.currentGeneration = nextGeneration ?? current + 1;
+    return this.currentGeneration;
+  }
+  /**
+   * Returns detailed metadata about a single cache key: which layers contain it,
+   * remaining fresh/stale/error TTLs, and associated tags.
+   * Returns `null` if the key does not exist in any layer.
+   */
+  async inspect(key) {
+    const userKey = this.validateCacheKey(key);
+    const normalizedKey = this.qualifyKey(userKey);
+    await this.awaitStartup("inspect");
+    const foundInLayers = [];
+    let freshTtlSeconds = null;
+    let staleTtlSeconds = null;
+    let errorTtlSeconds = null;
+    let isStale = false;
+    for (const layer of this.layers) {
+      if (this.shouldSkipLayer(layer)) {
+        continue;
+      }
+      const stored = await this.readLayerEntry(layer, normalizedKey);
+      if (stored === null) {
+        continue;
+      }
+      const resolved = resolveStoredValue(stored);
+      if (resolved.state === "expired") {
+        continue;
+      }
+      foundInLayers.push(layer.name);
+      if (foundInLayers.length === 1 && resolved.envelope) {
+        const now = Date.now();
+        freshTtlSeconds = resolved.envelope.freshUntil !== null ? Math.max(0, Math.ceil((resolved.envelope.freshUntil - now) / 1e3)) : null;
+        staleTtlSeconds = resolved.envelope.staleUntil !== null ? Math.max(0, Math.ceil((resolved.envelope.staleUntil - now) / 1e3)) : null;
+        errorTtlSeconds = resolved.envelope.errorUntil !== null ? Math.max(0, Math.ceil((resolved.envelope.errorUntil - now) / 1e3)) : null;
+        isStale = resolved.state === "stale-while-revalidate" || resolved.state === "stale-if-error";
+      }
+    }
+    if (foundInLayers.length === 0) {
+      return null;
+    }
+    const tags = await this.getTagsForKey(normalizedKey);
+    return { key: userKey, foundInLayers, freshTtlSeconds, staleTtlSeconds, errorTtlSeconds, isStale, tags };
+  }
+  async exportState() {
+    await this.awaitStartup("exportState");
     const exported = /* @__PURE__ */ new Map();
     for (const layer of this.layers) {
       if (!layer.keys) {
@@ -988,15 +1463,16 @@ var CacheStack = class extends import_node_events.EventEmitter {
       }
       const keys = await layer.keys();
       for (const key of keys) {
-        if (exported.has(key)) {
+        const exportedKey = this.stripQualifiedKey(key);
+        if (exported.has(exportedKey)) {
           continue;
         }
         const stored = await this.readLayerEntry(layer, key);
         if (stored === null) {
           continue;
         }
-        exported.set(key, {
-          key,
+        exported.set(exportedKey, {
+          key: exportedKey,
           value: stored,
           ttl: remainingStoredTtlSeconds(stored)
         });
@@ -1005,20 +1481,25 @@ var CacheStack = class extends import_node_events.EventEmitter {
     return [...exported.values()];
   }
   async importState(entries) {
-    await this.startup;
+    await this.awaitStartup("importState");
     await Promise.all(
       entries.map(async (entry) => {
-        await Promise.all(this.layers.map((layer) => layer.set(entry.key, entry.value, entry.ttl)));
-        await this.tagIndex.touch(entry.key);
+        const qualifiedKey = this.qualifyKey(entry.key);
+        await Promise.all(this.layers.map((layer) => layer.set(qualifiedKey, entry.value, entry.ttl)));
+        await this.tagIndex.touch(qualifiedKey);
       })
     );
   }
   async persistToFile(filePath) {
+    this.assertActive("persistToFile");
     const snapshot = await this.exportState();
-    await import_node_fs.promises.writeFile(filePath, JSON.stringify(snapshot, null, 2), "utf8");
+    const { promises: fs2 } = await import("fs");
+    await fs2.writeFile(filePath, JSON.stringify(snapshot, null, 2), "utf8");
   }
   async restoreFromFile(filePath) {
-    const raw = await import_node_fs.promises.readFile(filePath, "utf8");
+    this.assertActive("restoreFromFile");
+    const { promises: fs2 } = await import("fs");
+    const raw = await fs2.readFile(filePath, "utf8");
     let parsed;
     try {
       parsed = JSON.parse(raw, (_key, value) => {
@@ -1041,7 +1522,13 @@ var CacheStack = class extends import_node_events.EventEmitter {
       this.disconnectPromise = (async () => {
         await this.startup;
         await this.unsubscribeInvalidation?.();
+        await this.flushWriteBehindQueue();
         await Promise.allSettled([...this.backgroundRefreshes.values()]);
+        if (this.writeBehindTimer) {
+          clearInterval(this.writeBehindTimer);
+          this.writeBehindTimer = void 0;
+        }
+        await Promise.allSettled(this.layers.map((layer) => layer.dispose?.() ?? Promise.resolve()));
       })();
     }
     await this.disconnectPromise;
@@ -1101,7 +1588,10 @@ var CacheStack = class extends import_node_events.EventEmitter {
     const fetchStart = Date.now();
     let fetched;
     try {
-      fetched = await fetcher();
+      fetched = await this.fetchRateLimiter.schedule(
+        options?.fetcherRateLimit ?? this.options.fetcherRateLimit,
+        fetcher
+      );
       this.circuitBreakerManager.recordSuccess(key);
       this.logger.debug?.("fetch", { key, durationMs: Date.now() - fetchStart });
     } catch (error) {
@@ -1115,6 +1605,9 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.storeEntry(key, "empty", null, options);
       return null;
     }
+    if (options?.shouldCache && !options.shouldCache(fetched)) {
+      return fetched;
+    }
     await this.storeEntry(key, "value", fetched, options);
     return fetched;
   }
@@ -1132,12 +1625,70 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.publishInvalidation({ scope: "key", keys: [key], sourceId: this.instanceId, operation: "write" });
     }
   }
+  async writeBatch(entries) {
+    const now = Date.now();
+    const entriesByLayer = /* @__PURE__ */ new Map();
+    const immediateOperations = [];
+    const deferredOperations = [];
+    for (const entry of entries) {
+      for (const layer of this.layers) {
+        if (this.shouldSkipLayer(layer)) {
+          continue;
+        }
+        const layerEntry = this.buildLayerSetEntry(layer, entry.key, "value", entry.value, entry.options, now);
+        const bucket = entriesByLayer.get(layer) ?? [];
+        bucket.push(layerEntry);
+        entriesByLayer.set(layer, bucket);
+      }
+    }
+    for (const [layer, layerEntries] of entriesByLayer.entries()) {
+      const operation = async () => {
+        try {
+          if (layer.setMany) {
+            await layer.setMany(layerEntries);
+            return;
+          }
+          await Promise.all(layerEntries.map((entry) => layer.set(entry.key, entry.value, entry.ttl)));
+        } catch (error) {
+          await this.handleLayerFailure(layer, "write", error);
+        }
+      };
+      if (this.shouldWriteBehind(layer)) {
+        deferredOperations.push(operation);
+      } else {
+        immediateOperations.push(operation);
+      }
+    }
+    await this.executeLayerOperations(immediateOperations, { key: "batch", action: "mset" });
+    await Promise.all(deferredOperations.map((operation) => this.enqueueWriteBehind(operation)));
+    for (const entry of entries) {
+      if (entry.options?.tags) {
+        await this.tagIndex.track(entry.key, entry.options.tags);
+      } else {
+        await this.tagIndex.touch(entry.key);
+      }
+      this.metricsCollector.increment("sets");
+      this.logger.debug?.("set", { key: entry.key, kind: "value", tags: entry.options?.tags });
+      this.emit("set", { key: entry.key, kind: "value", tags: entry.options?.tags });
+    }
+    if (this.shouldBroadcastL1Invalidation()) {
+      await this.publishInvalidation({
+        scope: "keys",
+        keys: entries.map((entry) => entry.key),
+        sourceId: this.instanceId,
+        operation: "write"
+      });
+    }
+  }
   async readFromLayers(key, options, mode) {
     let sawRetainableValue = false;
     for (let index = 0; index < this.layers.length; index += 1) {
       const layer = this.layers[index];
       if (!layer) continue;
+      const readStart = performance.now();
       const stored = await this.readLayerEntry(layer, key);
+      const readDuration = performance.now() - readStart;
+      this.metricsCollector.recordLatency(layer.name, readDuration);
       if (stored === null) {
         this.metricsCollector.incrementLayer("missesByLayer", layer.name);
         continue;
@@ -1212,33 +1763,28 @@ var CacheStack = class extends import_node_events.EventEmitter {
   }
   async writeAcrossLayers(key, kind, value, options) {
     const now = Date.now();
-    const operations = this.layers.map((layer) => async () => {
-      if (this.shouldSkipLayer(layer)) {
-        return;
-      }
-      const freshTtl = this.resolveFreshTtl(key, layer.name, kind, options, layer.defaultTtl);
-      const staleWhileRevalidate = this.resolveLayerSeconds(
-        layer.name,
-        options?.staleWhileRevalidate,
-        this.options.staleWhileRevalidate
-      );
-      const staleIfError = this.resolveLayerSeconds(layer.name, options?.staleIfError, this.options.staleIfError);
-      const payload = createStoredValueEnvelope({
-        kind,
-        value,
-        freshTtlSeconds: freshTtl,
-        staleWhileRevalidateSeconds: staleWhileRevalidate,
-        staleIfErrorSeconds: staleIfError,
-        now
-      });
-      const ttl = remainingStoredTtlSeconds(payload, now) ?? freshTtl;
-      try {
-        await layer.set(key, payload, ttl);
-      } catch (error) {
-        await this.handleLayerFailure(layer, "write", error);
+    const immediateOperations = [];
+    const deferredOperations = [];
+    for (const layer of this.layers) {
+      const operation = async () => {
+        if (this.shouldSkipLayer(layer)) {
+          return;
+        }
+        const entry = this.buildLayerSetEntry(layer, key, kind, value, options, now);
+        try {
+          await layer.set(entry.key, entry.value, entry.ttl);
+        } catch (error) {
+          await this.handleLayerFailure(layer, "write", error);
+        }
+      };
+      if (this.shouldWriteBehind(layer)) {
+        deferredOperations.push(operation);
+      } else {
+        immediateOperations.push(operation);
       }
-    });
-    await this.executeLayerOperations(operations, { key, action: kind === "empty" ? "negative-set" : "set" });
+    }
+    await this.executeLayerOperations(immediateOperations, { key, action: kind === "empty" ? "negative-set" : "set" });
+    await Promise.all(deferredOperations.map((operation) => this.enqueueWriteBehind(operation)));
   }
   async executeLayerOperations(operations, context) {
     if (this.options.writePolicy !== "best-effort") {
@@ -1262,8 +1808,17 @@ var CacheStack = class extends import_node_events.EventEmitter {
       );
     }
   }
-  resolveFreshTtl(key, layerName, kind, options, fallbackTtl) {
-    return this.ttlResolver.resolveFreshTtl(key, layerName, kind, options, fallbackTtl, this.options.negativeTtl);
+  resolveFreshTtl(key, layerName, kind, options, fallbackTtl, value) {
+    return this.ttlResolver.resolveFreshTtl(
+      key,
+      layerName,
+      kind,
+      options,
+      fallbackTtl,
+      this.options.negativeTtl,
+      void 0,
+      value
+    );
   }
   resolveLayerSeconds(layerName, override, globalDefault, fallback) {
     return this.ttlResolver.resolveLayerSeconds(layerName, override, globalDefault, fallback);
@@ -1339,6 +1894,12 @@ var CacheStack = class extends import_node_events.EventEmitter {
       }
     }
   }
+  async getTagsForKey(key) {
+    if (this.tagIndex.tagsForKey) {
+      return this.tagIndex.tagsForKey(key);
+    }
+    return [];
+  }
   formatError(error) {
     if (error instanceof Error) {
       return error.message;
@@ -1351,6 +1912,105 @@ var CacheStack = class extends import_node_events.EventEmitter {
   shouldBroadcastL1Invalidation() {
     return this.options.broadcastL1Invalidation ?? this.options.publishSetInvalidation ?? true;
   }
+  initializeWriteBehind(options) {
+    if (this.options.writeStrategy !== "write-behind") {
+      return;
+    }
+    const flushIntervalMs = options?.flushIntervalMs;
+    if (!flushIntervalMs || flushIntervalMs <= 0) {
+      return;
+    }
+    this.writeBehindTimer = setInterval(() => {
+      void this.flushWriteBehindQueue();
+    }, flushIntervalMs);
+    this.writeBehindTimer.unref?.();
+  }
+  shouldWriteBehind(layer) {
+    return this.options.writeStrategy === "write-behind" && !layer.isLocal;
+  }
+  async enqueueWriteBehind(operation) {
+    this.writeBehindQueue.push(operation);
+    const batchSize = this.options.writeBehind?.batchSize ?? 100;
+    const maxQueueSize = this.options.writeBehind?.maxQueueSize ?? batchSize * 10;
+    if (this.writeBehindQueue.length >= batchSize) {
+      await this.flushWriteBehindQueue();
+      return;
+    }
+    if (this.writeBehindQueue.length >= maxQueueSize) {
+      await this.flushWriteBehindQueue();
+    }
+  }
+  async flushWriteBehindQueue() {
+    if (this.writeBehindFlushPromise || this.writeBehindQueue.length === 0) {
+      await this.writeBehindFlushPromise;
+      return;
+    }
+    const batchSize = this.options.writeBehind?.batchSize ?? 100;
+    const batch = this.writeBehindQueue.splice(0, batchSize);
+    this.writeBehindFlushPromise = (async () => {
+      await Promise.allSettled(batch.map((operation) => operation()));
+    })();
+    await this.writeBehindFlushPromise;
+    this.writeBehindFlushPromise = void 0;
+    if (this.writeBehindQueue.length > 0) {
+      await this.flushWriteBehindQueue();
+    }
+  }
+  buildLayerSetEntry(layer, key, kind, value, options, now) {
+    const freshTtl = this.resolveFreshTtl(key, layer.name, kind, options, layer.defaultTtl, value);
+    const staleWhileRevalidate = this.resolveLayerSeconds(
+      layer.name,
+      options?.staleWhileRevalidate,
+      this.options.staleWhileRevalidate
+    );
+    const staleIfError = this.resolveLayerSeconds(layer.name, options?.staleIfError, this.options.staleIfError);
+    const payload = createStoredValueEnvelope({
+      kind,
+      value,
+      freshTtlSeconds: freshTtl,
+      staleWhileRevalidateSeconds: staleWhileRevalidate,
+      staleIfErrorSeconds: staleIfError,
+      now
+    });
+    const ttl = remainingStoredTtlSeconds(payload, now) ?? freshTtl;
+    return {
+      key,
+      value: payload,
+      ttl
+    };
+  }
+  intersectKeys(groups) {
+    if (groups.length === 0) {
+      return [];
+    }
+    const [firstGroup, ...rest] = groups;
+    if (!firstGroup) {
+      return [];
+    }
+    const restSets = rest.map((group) => new Set(group));
+    return [...new Set(firstGroup)].filter((key) => restSets.every((group) => group.has(key)));
+  }
+  qualifyKey(key) {
+    const prefix = this.generationPrefix();
+    return prefix ? `${prefix}${key}` : key;
+  }
+  qualifyPattern(pattern) {
+    const prefix = this.generationPrefix();
+    return prefix ? `${prefix}${pattern}` : pattern;
+  }
+  stripQualifiedKey(key) {
+    const prefix = this.generationPrefix();
+    if (!prefix || !key.startsWith(prefix)) {
+      return key;
+    }
+    return key.slice(prefix.length);
+  }
+  generationPrefix() {
+    if (this.currentGeneration === void 0) {
+      return "";
+    }
+    return `v${this.currentGeneration}:`;
+  }
   async deleteKeysFromLayers(layers, keys) {
     await Promise.all(
       layers.map(async (layer) => {
@@ -1394,6 +2054,9 @@ var CacheStack = class extends import_node_events.EventEmitter {
     this.validatePositiveNumber("singleFlightPollMs", this.options.singleFlightPollMs);
     this.validateAdaptiveTtlOptions(this.options.adaptiveTtl);
     this.validateCircuitBreakerOptions(this.options.circuitBreaker);
+    if (this.options.generation !== void 0) {
+      this.validateNonNegativeNumber("generation", this.options.generation);
+    }
   }
   validateWriteOptions(options) {
     if (!options) {
@@ -1405,6 +2068,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
     this.validateLayerNumberOption("options.staleIfError", options.staleIfError);
     this.validateLayerNumberOption("options.ttlJitter", options.ttlJitter);
     this.validateLayerNumberOption("options.refreshAhead", options.refreshAhead);
+    this.validateTtlPolicy("options.ttlPolicy", options.ttlPolicy);
     this.validateAdaptiveTtlOptions(options.adaptiveTtl);
     this.validateCircuitBreakerOptions(options.circuitBreaker);
   }
@@ -1448,6 +2112,26 @@ var CacheStack = class extends import_node_events.EventEmitter {
     }
     return key;
   }
+  validateTtlPolicy(name, policy) {
+    if (!policy || typeof policy === "function" || policy === "until-midnight" || policy === "next-hour") {
+      return;
+    }
+    if ("alignTo" in policy) {
+      this.validatePositiveNumber(`${name}.alignTo`, policy.alignTo);
+      return;
+    }
+    throw new Error(`${name} is invalid.`);
+  }
+  assertActive(operation) {
+    if (this.isDisconnecting) {
+      throw new Error(`CacheStack is disconnecting; cannot perform ${operation}.`);
+    }
+  }
+  async awaitStartup(operation) {
+    this.assertActive(operation);
+    await this.startup;
+    this.assertActive(operation);
+  }
   serializeOptions(options) {
     return JSON.stringify(this.normalizeForSerialization(options) ?? null);
   }
@@ -1553,41 +2237,47 @@ var CacheStack = class extends import_node_events.EventEmitter {
     return value;
   }
 };
+function createInstanceId() {
+  return globalThis.crypto?.randomUUID?.() ?? `layercache-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
 
 // src/invalidation/RedisInvalidationBus.ts
 var RedisInvalidationBus = class {
   channel;
   publisher;
   subscriber;
-  activeListener;
+  logger;
+  handlers = /* @__PURE__ */ new Set();
+  sharedListener;
   constructor(options) {
     this.publisher = options.publisher;
     this.subscriber = options.subscriber ?? options.publisher.duplicate();
     this.channel = options.channel ?? "layercache:invalidation";
+    this.logger = options.logger;
   }
   async subscribe(handler) {
-    if (this.activeListener) {
-      throw new Error("RedisInvalidationBus already has an active subscription.");
+    if (this.handlers.size === 0) {
+      const listener = (_channel, payload) => {
+        void this.dispatchToHandlers(payload);
+      };
+      this.sharedListener = listener;
+      this.subscriber.on("message", listener);
+      await this.subscriber.subscribe(this.channel);
     }
-    const listener = (_channel, payload) => {
-      void this.handleMessage(payload, handler);
-    };
-    this.activeListener = listener;
-    this.subscriber.on("message", listener);
-    await this.subscriber.subscribe(this.channel);
+    this.handlers.add(handler);
     return async () => {
-      if (this.activeListener !== listener) {
-        return;
+      this.handlers.delete(handler);
+      if (this.handlers.size === 0 && this.sharedListener) {
+        this.subscriber.off("message", this.sharedListener);
+        this.sharedListener = void 0;
+        await this.subscriber.unsubscribe(this.channel);
       }
-      this.activeListener = void 0;
-      this.subscriber.off("message", listener);
-      await this.subscriber.unsubscribe(this.channel);
     };
   }
   async publish(message) {
     await this.publisher.publish(this.channel, JSON.stringify(message));
   }
-  async handleMessage(payload, handler) {
+  async dispatchToHandlers(payload) {
     let message;
     try {
       const parsed = JSON.parse(payload);
@@ -1599,11 +2289,15 @@ var RedisInvalidationBus = class {
       this.reportError("invalid invalidation payload", error);
       return;
     }
-    try {
-      await handler(message);
-    } catch (error) {
-      this.reportError("invalidation handler failed", error);
-    }
+    await Promise.all(
+      [...this.handlers].map(async (handler) => {
+        try {
+          await handler(message);
+        } catch (error) {
+          this.reportError("invalidation handler failed", error);
+        }
+      })
+    );
   }
   isInvalidationMessage(value) {
     if (!value || typeof value !== "object") {
@@ -1616,6 +2310,10 @@ var RedisInvalidationBus = class {
     return validScope && typeof candidate.sourceId === "string" && candidate.sourceId.length > 0 && validOperation && validKeys;
   }
   reportError(message, error) {
+    if (this.logger?.error) {
+      this.logger.error(message, { error });
+      return;
+    }
     console.error(`[layercache] ${message}`, error);
   }
 };
@@ -1664,6 +2362,19 @@ var RedisTagIndex = class {
   async keysForTag(tag) {
     return this.client.smembers(this.tagKeysKey(tag));
   }
+  async keysForPrefix(prefix) {
+    const matches = [];
+    let cursor = "0";
+    do {
+      const [nextCursor, keys] = await this.client.sscan(this.knownKeysKey(), cursor, "COUNT", this.scanCount);
+      cursor = nextCursor;
+      matches.push(...keys.filter((key) => key.startsWith(prefix)));
+    } while (cursor !== "0");
+    return matches;
+  }
+  async tagsForKey(key) {
+    return this.client.smembers(this.keyTagsKey(key));
+  }
   async matchPattern(pattern) {
     const matches = [];
     let cursor = "0";
@@ -1754,6 +2465,43 @@ function createFastifyLayercachePlugin(cache, options = {}) {
   };
 }
 
+// src/integrations/express.ts
+function createExpressCacheMiddleware(cache, options = {}) {
+  const allowedMethods = new Set((options.methods ?? ["GET"]).map((m) => m.toUpperCase()));
+  return async (req, res, next) => {
+    try {
+      const method = (req.method ?? "GET").toUpperCase();
+      if (!allowedMethods.has(method)) {
+        next();
+        return;
+      }
+      const key = options.keyResolver ? options.keyResolver(req) : `${method}:${req.originalUrl ?? req.url ?? "/"}`;
+      const cached = await cache.get(key, void 0, options);
+      if (cached !== null) {
+        res.setHeader?.("content-type", "application/json; charset=utf-8");
+        res.setHeader?.("x-cache", "HIT");
+        if (res.json) {
+          res.json(cached);
+        } else {
+          res.end?.(JSON.stringify(cached));
+        }
+        return;
+      }
+      const originalJson = res.json?.bind(res);
+      if (originalJson) {
+        res.json = (body) => {
+          res.setHeader?.("x-cache", "MISS");
+          void cache.set(key, body, options);
+          return originalJson(body);
+        };
+      }
+      next();
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+
 // src/integrations/graphql.ts
 function cacheGraphqlResolver(cache, prefix, resolver, options = {}) {
   const wrapped = cache.wrap(prefix, resolver, {
@@ -1763,6 +2511,95 @@ function cacheGraphqlResolver(cache, prefix, resolver, options = {}) {
   return (...args) => wrapped(...args);
 }
 
+// src/integrations/hono.ts
+function createHonoCacheMiddleware(cache, options = {}) {
+  const allowedMethods = new Set((options.methods ?? ["GET"]).map((method) => method.toUpperCase()));
+  return async (context, next) => {
+    const method = (context.req.method ?? "GET").toUpperCase();
+    if (!allowedMethods.has(method)) {
+      await next();
+      return;
+    }
+    const key = options.keyResolver ? options.keyResolver(context.req) : `${method}:${context.req.path ?? context.req.url ?? "/"}`;
+    const cached = await cache.get(key, void 0, options);
+    if (cached !== null) {
+      context.header?.("x-cache", "HIT");
+      context.header?.("content-type", "application/json; charset=utf-8");
+      context.json(cached);
+      return;
+    }
+    const originalJson = context.json.bind(context);
+    context.json = (body, status) => {
+      context.header?.("x-cache", "MISS");
+      void cache.set(key, body, options);
+      return originalJson(body, status);
+    };
+    await next();
+  };
+}
+
+// src/integrations/opentelemetry.ts
+function createOpenTelemetryPlugin(cache, tracer) {
+  const originals = {
+    get: cache.get.bind(cache),
+    set: cache.set.bind(cache),
+    delete: cache.delete.bind(cache),
+    mget: cache.mget.bind(cache),
+    mset: cache.mset.bind(cache),
+    invalidateByTag: cache.invalidateByTag.bind(cache),
+    invalidateByTags: cache.invalidateByTags.bind(cache),
+    invalidateByPattern: cache.invalidateByPattern.bind(cache),
+    invalidateByPrefix: cache.invalidateByPrefix.bind(cache)
+  };
+  cache.get = instrument("layercache.get", tracer, originals.get, (args) => ({
+    "layercache.key": String(args[0] ?? "")
+  }));
+  cache.set = instrument("layercache.set", tracer, originals.set, (args) => ({
+    "layercache.key": String(args[0] ?? "")
+  }));
+  cache.delete = instrument("layercache.delete", tracer, originals.delete, (args) => ({
+    "layercache.key": String(args[0] ?? "")
+  }));
+  cache.mget = instrument("layercache.mget", tracer, originals.mget);
+  cache.mset = instrument("layercache.mset", tracer, originals.mset);
+  cache.invalidateByTag = instrument("layercache.invalidate_by_tag", tracer, originals.invalidateByTag);
+  cache.invalidateByTags = instrument("layercache.invalidate_by_tags", tracer, originals.invalidateByTags);
+  cache.invalidateByPattern = instrument("layercache.invalidate_by_pattern", tracer, originals.invalidateByPattern);
+  cache.invalidateByPrefix = instrument("layercache.invalidate_by_prefix", tracer, originals.invalidateByPrefix);
+  return {
+    uninstall() {
+      cache.get = originals.get;
+      cache.set = originals.set;
+      cache.delete = originals.delete;
+      cache.mget = originals.mget;
+      cache.mset = originals.mset;
+      cache.invalidateByTag = originals.invalidateByTag;
+      cache.invalidateByTags = originals.invalidateByTags;
+      cache.invalidateByPattern = originals.invalidateByPattern;
+      cache.invalidateByPrefix = originals.invalidateByPrefix;
+    }
+  };
+}
+function instrument(name, tracer, method, attributes) {
+  return (async (...args) => {
+    const span = tracer.startSpan(name, { attributes: attributes?.(args) });
+    try {
+      const result = await method(...args);
+      span.setAttribute?.("layercache.success", true);
+      if (result === null) {
+        span.setAttribute?.("layercache.result", "null");
+      }
+      return result;
+    } catch (error) {
+      span.setAttribute?.("layercache.success", false);
+      span.recordException?.(error);
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+
 // src/integrations/trpc.ts
 function createTrpcCacheMiddleware(cache, prefix, options = {}) {
   return async (context) => {
@@ -1795,12 +2632,21 @@ var MemoryLayer = class {
   isLocal = true;
   maxSize;
   evictionPolicy;
+  onEvict;
   entries = /* @__PURE__ */ new Map();
+  cleanupTimer;
   constructor(options = {}) {
     this.name = options.name ?? "memory";
     this.defaultTtl = options.ttl;
     this.maxSize = options.maxSize ?? 1e3;
     this.evictionPolicy = options.evictionPolicy ?? "lru";
+    this.onEvict = options.onEvict;
+    if (options.cleanupIntervalMs && options.cleanupIntervalMs > 0) {
+      this.cleanupTimer = setInterval(() => {
+        this.pruneExpired();
+      }, options.cleanupIntervalMs);
+      this.cleanupTimer.unref?.();
+    }
   }
   async get(key) {
     const value = await this.getEntry(key);
@@ -1817,10 +2663,10 @@ var MemoryLayer = class {
     }
     if (this.evictionPolicy === "lru") {
       this.entries.delete(key);
-      entry.frequency += 1;
+      entry.accessCount += 1;
       this.entries.set(key, entry);
-    } else {
-      entry.frequency += 1;
+    } else if (this.evictionPolicy === "lfu") {
+      entry.accessCount += 1;
     }
     return entry.value;
   }
@@ -1831,12 +2677,17 @@ var MemoryLayer = class {
     }
     return values;
   }
+  async setMany(entries) {
+    for (const entry of entries) {
+      await this.set(entry.key, entry.value, entry.ttl);
+    }
+  }
   async set(key, value, ttl = this.defaultTtl) {
     this.entries.delete(key);
     this.entries.set(key, {
       value,
       expiresAt: ttl && ttl > 0 ? Date.now() + ttl * 1e3 : null,
-      frequency: 0,
+      accessCount: 0,
       insertedAt: Date.now()
     });
     while (this.entries.size > this.maxSize) {
@@ -1883,6 +2734,15 @@ var MemoryLayer = class {
   async clear() {
     this.entries.clear();
   }
+  async ping() {
+    return true;
+  }
+  async dispose() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = void 0;
+    }
+  }
   async keys() {
     this.pruneExpired();
     return [...this.entries.keys()];
@@ -1903,7 +2763,7 @@ var MemoryLayer = class {
       this.entries.set(entry.key, {
         value: entry.value,
         expiresAt: entry.expiresAt,
-        frequency: 0,
+        accessCount: 0,
         insertedAt: Date.now()
       });
     }
@@ -1915,22 +2775,30 @@ var MemoryLayer = class {
     if (this.evictionPolicy === "lru" || this.evictionPolicy === "fifo") {
       const oldestKey = this.entries.keys().next().value;
       if (oldestKey !== void 0) {
+        const entry = this.entries.get(oldestKey);
         this.entries.delete(oldestKey);
+        if (entry) {
+          this.onEvict?.(oldestKey, unwrapStoredValue(entry.value));
+        }
       }
       return;
     }
     let victimKey;
-    let minFreq = Number.POSITIVE_INFINITY;
+    let minCount = Number.POSITIVE_INFINITY;
     let minInsertedAt = Number.POSITIVE_INFINITY;
     for (const [key, entry] of this.entries.entries()) {
-      if (entry.frequency < minFreq || entry.frequency === minFreq && entry.insertedAt < minInsertedAt) {
-        minFreq = entry.frequency;
+      if (entry.accessCount < minCount || entry.accessCount === minCount && entry.insertedAt < minInsertedAt) {
+        minCount = entry.accessCount;
         minInsertedAt = entry.insertedAt;
         victimKey = key;
       }
     }
     if (victimKey !== void 0) {
+      const victim = this.entries.get(victimKey);
       this.entries.delete(victimKey);
+      if (victim) {
+        this.onEvict?.(victimKey, unwrapStoredValue(victim.value));
+      }
     }
   }
   pruneExpired() {
@@ -1946,6 +2814,7 @@ var MemoryLayer = class {
 };
 
 // src/layers/RedisLayer.ts
+var import_node_util = require("util");
 var import_node_zlib = require("zlib");
 
 // src/serialization/JsonSerializer.ts
@@ -1961,27 +2830,33 @@ var JsonSerializer = class {
 
 // src/layers/RedisLayer.ts
 var BATCH_DELETE_SIZE = 500;
+var gzipAsync = (0, import_node_util.promisify)(import_node_zlib.gzip);
+var gunzipAsync = (0, import_node_util.promisify)(import_node_zlib.gunzip);
+var brotliCompressAsync = (0, import_node_util.promisify)(import_node_zlib.brotliCompress);
+var brotliDecompressAsync = (0, import_node_util.promisify)(import_node_zlib.brotliDecompress);
 var RedisLayer = class {
   name;
   defaultTtl;
   isLocal = false;
   client;
-  serializer;
+  serializers;
   prefix;
   allowUnprefixedClear;
   scanCount;
   compression;
   compressionThreshold;
+  disconnectOnDispose;
   constructor(options) {
     this.client = options.client;
     this.defaultTtl = options.ttl;
     this.name = options.name ?? "redis";
-    this.serializer = options.serializer ?? new JsonSerializer();
+    this.serializers = Array.isArray(options.serializer) ? options.serializer : [options.serializer ?? new JsonSerializer()];
     this.prefix = options.prefix ?? "";
     this.allowUnprefixedClear = options.allowUnprefixedClear ?? false;
     this.scanCount = options.scanCount ?? 100;
     this.compression = options.compression;
     this.compressionThreshold = options.compressionThreshold ?? 1024;
+    this.disconnectOnDispose = options.disconnectOnDispose ?? false;
   }
   async get(key) {
     const payload = await this.getEntry(key);
@@ -2016,8 +2891,26 @@ var RedisLayer = class {
       })
     );
   }
+  async setMany(entries) {
+    if (entries.length === 0) {
+      return;
+    }
+    const pipeline = this.client.pipeline();
+    for (const entry of entries) {
+      const serialized = this.primarySerializer().serialize(entry.value);
+      const payload = await this.encodePayload(serialized);
+      const normalizedKey = this.withPrefix(entry.key);
+      if (entry.ttl && entry.ttl > 0) {
+        pipeline.set(normalizedKey, payload, "EX", entry.ttl);
+      } else {
+        pipeline.set(normalizedKey, payload);
+      }
+    }
+    await pipeline.exec();
+  }
   async set(key, value, ttl = this.defaultTtl) {
-    const payload = this.encodePayload(this.serializer.serialize(value));
+    const serialized = this.primarySerializer().serialize(value);
+    const payload = await this.encodePayload(serialized);
     const normalizedKey = this.withPrefix(key);
     if (ttl && ttl > 0) {
       await this.client.set(normalizedKey, payload, "EX", ttl);
@@ -2049,6 +2942,18 @@ var RedisLayer = class {
     const keys = await this.keys();
     return keys.length;
   }
+  async ping() {
+    try {
+      return await this.client.ping() === "PONG";
+    } catch {
+      return false;
+    }
+  }
+  async dispose() {
+    if (this.disconnectOnDispose) {
+      this.client.disconnect();
+    }
+  }
   /**
    * Deletes all keys matching the layer's prefix in batches to avoid
    * loading millions of keys into memory at once.
@@ -2095,17 +3000,48 @@ var RedisLayer = class {
     return `${this.prefix}${key}`;
   }
   async deserializeOrDelete(key, payload) {
+    const decodedPayload = await this.decodePayload(payload);
+    for (const serializer of this.serializers) {
+      try {
+        const value = serializer.deserialize(decodedPayload);
+        if (serializer !== this.primarySerializer()) {
+          await this.rewriteWithPrimarySerializer(key, value).catch(() => void 0);
+        }
+        return value;
+      } catch {
+      }
+    }
     try {
-      return this.serializer.deserialize(this.decodePayload(payload));
-    } catch {
       await this.client.del(this.withPrefix(key)).catch(() => void 0);
-      return null;
+    } catch {
     }
+    return null;
+  }
+  async rewriteWithPrimarySerializer(key, value) {
+    const serialized = this.primarySerializer().serialize(value);
+    const payload = await this.encodePayload(serialized);
+    const ttl = await this.client.ttl(this.withPrefix(key));
+    if (ttl > 0) {
+      await this.client.set(this.withPrefix(key), payload, "EX", ttl);
+      return;
+    }
+    await this.client.set(this.withPrefix(key), payload);
+  }
+  primarySerializer() {
+    const serializer = this.serializers[0];
+    if (!serializer) {
+      throw new Error("RedisLayer requires at least one serializer.");
+    }
+    return serializer;
   }
   isSerializablePayload(payload) {
     return typeof payload === "string" || Buffer.isBuffer(payload);
   }
-  encodePayload(payload) {
+  /**
+   * Compresses the payload asynchronously if compression is enabled and the
+   * payload exceeds the threshold. This avoids blocking the event loop.
+   */
+  async encodePayload(payload) {
     if (!this.compression) {
       return payload;
     }
@@ -2114,26 +3050,29 @@ var RedisLayer = class {
       return payload;
     }
     const header = Buffer.from(`LCZ1:${this.compression}:`);
-    const compressed = this.compression === "gzip" ? (0, import_node_zlib.gzipSync)(source) : (0, import_node_zlib.brotliCompressSync)(source);
+    const compressed = this.compression === "gzip" ? await gzipAsync(source) : await brotliCompressAsync(source);
     return Buffer.concat([header, compressed]);
   }
-  decodePayload(payload) {
+  /**
+   * Decompresses the payload asynchronously if a compression header is present.
+   */
+  async decodePayload(payload) {
     if (!Buffer.isBuffer(payload)) {
       return payload;
     }
     if (payload.subarray(0, 10).toString() === "LCZ1:gzip:") {
-      return (0, import_node_zlib.gunzipSync)(payload.subarray(10));
+      return gunzipAsync(payload.subarray(10));
     }
     if (payload.subarray(0, 12).toString() === "LCZ1:brotli:") {
-      return (0, import_node_zlib.brotliDecompressSync)(payload.subarray(12));
+      return brotliDecompressAsync(payload.subarray(12));
     }
     return payload;
   }
 };
 
 // src/layers/DiskLayer.ts
-var import_node_crypto2 = require("crypto");
-var import_node_fs2 = require("fs");
+var import_node_crypto = require("crypto");
+var import_node_fs = require("fs");
 var import_node_path = require("path");
 var DiskLayer = class {
   name;
@@ -2141,11 +3080,14 @@ var DiskLayer = class {
   isLocal = true;
   directory;
   serializer;
+  maxFiles;
+  writeQueue = Promise.resolve();
   constructor(options) {
     this.directory = options.directory;
     this.defaultTtl = options.ttl;
     this.name = options.name ?? "disk";
     this.serializer = options.serializer ?? new JsonSerializer();
+    this.maxFiles = options.maxFiles;
   }
   async get(key) {
     return unwrapStoredValue(await this.getEntry(key));
@@ -2154,7 +3096,7 @@ var DiskLayer = class {
     const filePath = this.keyToPath(key);
     let raw;
     try {
-      raw = await import_node_fs2.promises.readFile(filePath);
+      raw = await import_node_fs.promises.readFile(filePath);
     } catch {
       return null;
     }
@@ -2172,13 +3114,30 @@ var DiskLayer = class {
     return entry.value;
   }
   async set(key, value, ttl = this.defaultTtl) {
-    await import_node_fs2.promises.mkdir(this.directory, { recursive: true });
-    const entry = {
-      value,
-      expiresAt: ttl && ttl > 0 ? Date.now() + ttl * 1e3 : null
-    };
-    const payload = this.serializer.serialize(entry);
-    await import_node_fs2.promises.writeFile(this.keyToPath(key), payload);
+    await this.enqueueWrite(async () => {
+      await import_node_fs.promises.mkdir(this.directory, { recursive: true });
+      const entry = {
+        key,
+        value,
+        expiresAt: ttl && ttl > 0 ? Date.now() + ttl * 1e3 : null
+      };
+      const payload = this.serializer.serialize(entry);
+      const targetPath = this.keyToPath(key);
+      const tempPath = `${targetPath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+      await import_node_fs.promises.writeFile(tempPath, payload);
+      await import_node_fs.promises.rename(tempPath, targetPath);
+      if (this.maxFiles !== void 0) {
+        await this.enforceMaxFiles();
+      }
+    });
+  }
+  async getMany(keys) {
+    return Promise.all(keys.map((key) => this.getEntry(key)));
+  }
+  async setMany(entries) {
+    for (const entry of entries) {
+      await this.set(entry.key, entry.value, entry.ttl);
+    }
   }
   async has(key) {
     const value = await this.getEntry(key);
@@ -2188,7 +3147,7 @@ var DiskLayer = class {
     const filePath = this.keyToPath(key);
     let raw;
     try {
-      raw = await import_node_fs2.promises.readFile(filePath);
+      raw = await import_node_fs.promises.readFile(filePath);
     } catch {
       return null;
     }
@@ -2208,44 +3167,124 @@ var DiskLayer = class {
     return remaining;
   }
   async delete(key) {
-    await this.safeDelete(this.keyToPath(key));
+    await this.enqueueWrite(() => this.safeDelete(this.keyToPath(key)));
   }
   async deleteMany(keys) {
-    await Promise.all(keys.map((key) => this.delete(key)));
+    await this.enqueueWrite(async () => {
+      await Promise.all(keys.map((key) => this.safeDelete(this.keyToPath(key))));
+    });
   }
   async clear() {
-    let entries;
-    try {
-      entries = await import_node_fs2.promises.readdir(this.directory);
-    } catch {
-      return;
-    }
-    await Promise.all(
-      entries.filter((name) => name.endsWith(".lc")).map((name) => this.safeDelete((0, import_node_path.join)(this.directory, name)))
-    );
+    await this.enqueueWrite(async () => {
+      let entries;
+      try {
+        entries = await import_node_fs.promises.readdir(this.directory);
+      } catch {
+        return;
+      }
+      await Promise.all(
+        entries.filter((name) => name.endsWith(".lc")).map((name) => this.safeDelete((0, import_node_path.join)(this.directory, name)))
+      );
+    });
   }
+  /**
+   * Returns the original cache key strings stored on disk.
+   * Expired entries are skipped and cleaned up during the scan.
+   */
   async keys() {
     let entries;
     try {
-      entries = await import_node_fs2.promises.readdir(this.directory);
+      entries = await import_node_fs.promises.readdir(this.directory);
     } catch {
       return [];
     }
-    return entries.filter((name) => name.endsWith(".lc")).map((name) => name.slice(0, -3));
+    const lcFiles = entries.filter((name) => name.endsWith(".lc"));
+    const keys = [];
+    await Promise.all(
+      lcFiles.map(async (name) => {
+        const filePath = (0, import_node_path.join)(this.directory, name);
+        let raw;
+        try {
+          raw = await import_node_fs.promises.readFile(filePath);
+        } catch {
+          return;
+        }
+        let entry;
+        try {
+          entry = this.serializer.deserialize(raw);
+        } catch {
+          await this.safeDelete(filePath);
+          return;
+        }
+        if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
+          await this.safeDelete(filePath);
+          return;
+        }
+        keys.push(entry.key);
+      })
+    );
+    return keys;
   }
   async size() {
     const keys = await this.keys();
     return keys.length;
   }
+  async ping() {
+    try {
+      await import_node_fs.promises.mkdir(this.directory, { recursive: true });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async dispose() {
+  }
   keyToPath(key) {
-    const hash = (0, import_node_crypto2.createHash)("sha256").update(key).digest("hex");
+    const hash = (0, import_node_crypto.createHash)("sha256").update(key).digest("hex");
     return (0, import_node_path.join)(this.directory, `${hash}.lc`);
   }
   async safeDelete(filePath) {
     try {
-      await import_node_fs2.promises.unlink(filePath);
+      await import_node_fs.promises.unlink(filePath);
+    } catch {
+    }
+  }
+  enqueueWrite(operation) {
+    const next = this.writeQueue.then(operation, operation);
+    this.writeQueue = next.catch(() => void 0);
+    return next;
+  }
+  /**
+   * Removes the oldest files (by mtime) when the directory exceeds maxFiles.
+   */
+  async enforceMaxFiles() {
+    if (this.maxFiles === void 0) {
+      return;
+    }
+    let entries;
+    try {
+      entries = await import_node_fs.promises.readdir(this.directory);
     } catch {
+      return;
+    }
+    const lcFiles = entries.filter((name) => name.endsWith(".lc"));
+    if (lcFiles.length <= this.maxFiles) {
+      return;
     }
+    const withStats = await Promise.all(
+      lcFiles.map(async (name) => {
+        const filePath = (0, import_node_path.join)(this.directory, name);
+        try {
+          const stat = await import_node_fs.promises.stat(filePath);
+          return { filePath, mtimeMs: stat.mtimeMs };
+        } catch {
+          return { filePath, mtimeMs: 0 };
+        }
+      })
+    );
+    withStats.sort((a, b) => a.mtimeMs - b.mtimeMs);
+    const toEvict = withStats.slice(0, lcFiles.length - this.maxFiles);
+    await Promise.all(toEvict.map(({ filePath }) => this.safeDelete(filePath)));
   }
 };
 
@@ -2256,29 +3295,41 @@ var MemcachedLayer = class {
   isLocal = false;
   client;
   keyPrefix;
+  serializer;
   constructor(options) {
     this.client = options.client;
     this.defaultTtl = options.ttl;
     this.name = options.name ?? "memcached";
     this.keyPrefix = options.keyPrefix ?? "";
+    this.serializer = options.serializer ?? new JsonSerializer();
   }
   async get(key) {
+    return unwrapStoredValue(await this.getEntry(key));
+  }
+  async getEntry(key) {
     const result = await this.client.get(this.withPrefix(key));
     if (!result || result.value === null) {
       return null;
     }
     try {
-      return JSON.parse(result.value.toString("utf8"));
+      return this.serializer.deserialize(result.value);
     } catch {
       return null;
     }
   }
+  async getMany(keys) {
+    return Promise.all(keys.map((key) => this.getEntry(key)));
+  }
   async set(key, value, ttl = this.defaultTtl) {
-    const payload = JSON.stringify(value);
+    const payload = this.serializer.serialize(value);
     await this.client.set(this.withPrefix(key), payload, {
       expires: ttl && ttl > 0 ? ttl : void 0
     });
   }
+  async has(key) {
+    const result = await this.client.get(this.withPrefix(key));
+    return result !== null && result.value !== null;
+  }
   async delete(key) {
     await this.client.delete(this.withPrefix(key));
   }
@@ -2308,7 +3359,7 @@ var MsgpackSerializer = class {
 };
 
 // src/singleflight/RedisSingleFlightCoordinator.ts
-var import_node_crypto3 = require("crypto");
+var import_node_crypto2 = require("crypto");
 var RELEASE_SCRIPT = `
 if redis.call("get", KEYS[1]) == ARGV[1] then
   return redis.call("del", KEYS[1])
@@ -2324,7 +3375,7 @@ var RedisSingleFlightCoordinator = class {
   }
   async execute(key, options, worker, waiter) {
     const lockKey = `${this.prefix}:${encodeURIComponent(key)}`;
-    const token = (0, import_node_crypto3.randomUUID)();
+    const token = (0, import_node_crypto2.randomUUID)();
     const acquired = await this.client.set(lockKey, token, "PX", options.leaseMs, "NX");
     if (acquired === "OK") {
       try {
@@ -2372,6 +3423,12 @@ function createPrometheusMetricsExporter(stacks) {
     lines.push("# TYPE layercache_hits_by_layer_total counter");
     lines.push("# HELP layercache_misses_by_layer_total Misses broken down by layer");
     lines.push("# TYPE layercache_misses_by_layer_total counter");
+    lines.push("# HELP layercache_layer_latency_avg_ms Average read latency per layer in milliseconds");
+    lines.push("# TYPE layercache_layer_latency_avg_ms gauge");
+    lines.push("# HELP layercache_layer_latency_max_ms Maximum read latency per layer in milliseconds");
+    lines.push("# TYPE layercache_layer_latency_max_ms gauge");
+    lines.push("# HELP layercache_layer_latency_count Number of read latency samples per layer");
+    lines.push("# TYPE layercache_layer_latency_count counter");
     for (const { stack, name } of entries) {
       const m = stack.getMetrics();
       const hr = stack.getHitRate();
@@ -2395,6 +3452,12 @@ function createPrometheusMetricsExporter(stacks) {
       for (const [layerName, count] of Object.entries(m.missesByLayer)) {
         lines.push(`layercache_misses_by_layer_total{${label},layer="${sanitizeLabel(layerName)}"} ${count}`);
       }
+      for (const [layerName, latency] of Object.entries(m.latencyByLayer)) {
+        const layerLabel = `${label},layer="${sanitizeLabel(layerName)}"`;
+        lines.push(`layercache_layer_latency_avg_ms{${layerLabel}} ${latency.avgMs.toFixed(4)}`);
+        lines.push(`layercache_layer_latency_max_ms{${layerLabel}} ${latency.maxMs.toFixed(4)}`);
+        lines.push(`layercache_layer_latency_count{${layerLabel}} ${latency.count}`);
+      }
     }
     lines.push("");
     return lines.join("\n");
@@ -2405,6 +3468,7 @@ function sanitizeLabel(value) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CacheMissError,
   CacheNamespace,
   CacheStack,
   DiskLayer,
@@ -2422,7 +3486,10 @@ function sanitizeLabel(value) {
   cacheGraphqlResolver,
   createCacheStatsHandler,
   createCachedMethodDecorator,
+  createExpressCacheMiddleware,
   createFastifyLayercachePlugin,
+  createHonoCacheMiddleware,
+  createOpenTelemetryPlugin,
   createPrometheusMetricsExporter,
   createTrpcCacheMiddleware
 });