layercache 1.1.0 → 1.2.1

package/dist/index.js

@@ -1,66 +1,103 @@
 import {
-  PatternMatcher,
   RedisTagIndex
-} from "./chunk-QUB5VZFZ.js";
+} from "./chunk-GF47Y3XR.js";
+import {
+  MemoryLayer,
+  TagIndex,
+  createHonoCacheMiddleware
+} from "./chunk-46UH7LNM.js";
+import {
+  PatternMatcher,
+  createStoredValueEnvelope,
+  isStoredValueEnvelope,
+  refreshStoredEnvelope,
+  remainingFreshTtlSeconds,
+  remainingStoredTtlSeconds,
+  resolveStoredValue,
+  unwrapStoredValue
+} from "./chunk-ZMDB5KOK.js";
 
 // src/CacheStack.ts
-import { randomUUID } from "crypto";
 import { EventEmitter } from "events";
-import { promises as fs } from "fs";
 
 // src/CacheNamespace.ts
-var CacheNamespace = class {
+import { Mutex } from "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);
@@ -75,15 +112,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 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 {
@@ -177,11 +358,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) {
     ;
@@ -190,6 +465,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();
   }
@@ -224,112 +515,12 @@ var MetricsCollector = class {
       degradedOperations: 0,
       hitsByLayer: {},
       missesByLayer: {},
+      latencyByLayer: {},
       resetAt: Date.now()
     };
   }
 };
 
-// src/internal/StoredValue.ts
-function isStoredValueEnvelope(value) {
-  return typeof value === "object" && value !== null && "__layercache" in value && value.__layercache === 1 && "kind" in value;
-}
-function createStoredValueEnvelope(options) {
-  const now = options.now ?? Date.now();
-  const freshTtlSeconds = normalizePositiveSeconds(options.freshTtlSeconds);
-  const staleWhileRevalidateSeconds = normalizePositiveSeconds(options.staleWhileRevalidateSeconds);
-  const staleIfErrorSeconds = normalizePositiveSeconds(options.staleIfErrorSeconds);
-  const freshUntil = freshTtlSeconds ? now + freshTtlSeconds * 1e3 : null;
-  const staleUntil = freshUntil && staleWhileRevalidateSeconds ? freshUntil + staleWhileRevalidateSeconds * 1e3 : null;
-  const errorUntil = freshUntil && staleIfErrorSeconds ? freshUntil + staleIfErrorSeconds * 1e3 : null;
-  return {
-    __layercache: 1,
-    kind: options.kind,
-    value: options.value,
-    freshUntil,
-    staleUntil,
-    errorUntil,
-    freshTtlSeconds: freshTtlSeconds ?? null,
-    staleWhileRevalidateSeconds: staleWhileRevalidateSeconds ?? null,
-    staleIfErrorSeconds: staleIfErrorSeconds ?? null
-  };
-}
-function resolveStoredValue(stored, now = Date.now()) {
-  if (!isStoredValueEnvelope(stored)) {
-    return { state: "fresh", value: stored, stored };
-  }
-  if (stored.freshUntil === null || stored.freshUntil > now) {
-    return { state: "fresh", value: unwrapStoredValue(stored), stored, envelope: stored };
-  }
-  if (stored.staleUntil !== null && stored.staleUntil > now) {
-    return { state: "stale-while-revalidate", value: unwrapStoredValue(stored), stored, envelope: stored };
-  }
-  if (stored.errorUntil !== null && stored.errorUntil > now) {
-    return { state: "stale-if-error", value: unwrapStoredValue(stored), stored, envelope: stored };
-  }
-  return { state: "expired", value: null, stored, envelope: stored };
-}
-function unwrapStoredValue(stored) {
-  if (!isStoredValueEnvelope(stored)) {
-    return stored;
-  }
-  if (stored.kind === "empty") {
-    return null;
-  }
-  return stored.value ?? null;
-}
-function remainingStoredTtlSeconds(stored, now = Date.now()) {
-  if (!isStoredValueEnvelope(stored)) {
-    return void 0;
-  }
-  const expiry = maxExpiry(stored);
-  if (expiry === null) {
-    return void 0;
-  }
-  const remainingMs = expiry - now;
-  if (remainingMs <= 0) {
-    return 1;
-  }
-  return Math.max(1, Math.ceil(remainingMs / 1e3));
-}
-function remainingFreshTtlSeconds(stored, now = Date.now()) {
-  if (!isStoredValueEnvelope(stored) || stored.freshUntil === null) {
-    return void 0;
-  }
-  const remainingMs = stored.freshUntil - now;
-  if (remainingMs <= 0) {
-    return 0;
-  }
-  return Math.max(1, Math.ceil(remainingMs / 1e3));
-}
-function refreshStoredEnvelope(stored, now = Date.now()) {
-  if (!isStoredValueEnvelope(stored)) {
-    return stored;
-  }
-  return createStoredValueEnvelope({
-    kind: stored.kind,
-    value: stored.value,
-    freshTtlSeconds: stored.freshTtlSeconds ?? void 0,
-    staleWhileRevalidateSeconds: stored.staleWhileRevalidateSeconds ?? void 0,
-    staleIfErrorSeconds: stored.staleIfErrorSeconds ?? void 0,
-    now
-  });
-}
-function maxExpiry(stored) {
-  const values = [stored.freshUntil, stored.staleUntil, stored.errorUntil].filter(
-    (value) => value !== null
-  );
-  if (values.length === 0) {
-    return null;
-  }
-  return Math.max(...values);
-}
-function normalizePositiveSeconds(value) {
-  if (!value || value <= 0) {
-    return void 0;
-  }
-  return value;
-}
-
 // src/internal/TtlResolver.ts
 var DEFAULT_NEGATIVE_TTL_SECONDS = 60;
 var TtlResolver = class {
@@ -351,13 +542,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);
@@ -396,6 +588,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;
@@ -418,66 +633,8 @@ var TtlResolver = class {
   }
 };
 
-// src/invalidation/TagIndex.ts
-var TagIndex = class {
-  tagToKeys = /* @__PURE__ */ new Map();
-  keyToTags = /* @__PURE__ */ new Map();
-  knownKeys = /* @__PURE__ */ new Set();
-  async touch(key) {
-    this.knownKeys.add(key);
-  }
-  async track(key, tags) {
-    this.knownKeys.add(key);
-    if (tags.length === 0) {
-      return;
-    }
-    const existingTags = this.keyToTags.get(key);
-    if (existingTags) {
-      for (const tag of existingTags) {
-        this.tagToKeys.get(tag)?.delete(key);
-      }
-    }
-    const tagSet = new Set(tags);
-    this.keyToTags.set(key, tagSet);
-    for (const tag of tagSet) {
-      const keys = this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set();
-      keys.add(key);
-      this.tagToKeys.set(tag, keys);
-    }
-  }
-  async remove(key) {
-    this.knownKeys.delete(key);
-    const tags = this.keyToTags.get(key);
-    if (!tags) {
-      return;
-    }
-    for (const tag of tags) {
-      const keys = this.tagToKeys.get(tag);
-      if (!keys) {
-        continue;
-      }
-      keys.delete(key);
-      if (keys.size === 0) {
-        this.tagToKeys.delete(tag);
-      }
-    }
-    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
-import { Mutex } from "async-mutex";
+import { Mutex as Mutex2 } from "async-mutex";
 var StampedeGuard = class {
   mutexes = /* @__PURE__ */ new Map();
   async execute(key, task) {
@@ -494,7 +651,7 @@ var StampedeGuard = class {
   getMutexEntry(key) {
     let entry = this.mutexes.get(key);
     if (!entry) {
-      entry = { mutex: new Mutex(), references: 0 };
+      entry = { mutex: new Mutex2(), references: 0 };
       this.mutexes.set(key, entry);
     }
     entry.references += 1;
@@ -502,6 +659,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;
@@ -545,6 +712,7 @@ var CacheStack = class extends 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."
@@ -553,21 +721,27 @@ var CacheStack = class extends 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 = 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;
   /**
@@ -577,9 +751,9 @@ var CacheStack = class extends 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);
@@ -628,12 +802,24 @@ var CacheStack = class extends 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;
@@ -663,8 +849,8 @@ var CacheStack = class extends 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;
@@ -685,17 +871,17 @@ var CacheStack = class extends 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",
@@ -705,7 +891,7 @@ var CacheStack = class extends 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();
@@ -721,23 +907,25 @@ var CacheStack = class extends 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);
@@ -763,7 +951,7 @@ var CacheStack = class extends EventEmitter {
         })
       );
     }
-    await this.startup;
+    await this.awaitStartup("mget");
     const pending = /* @__PURE__ */ new Set();
     const indexesByKey = /* @__PURE__ */ new Map();
     const resultsByKey = /* @__PURE__ */ new Map();
@@ -811,14 +999,17 @@ var CacheStack = class extends 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;
@@ -867,14 +1058,31 @@ var CacheStack = class extends 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" });
   }
@@ -901,8 +1109,77 @@ var CacheStack = class extends 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) {
@@ -910,15 +1187,16 @@ var CacheStack = class extends 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)
         });
@@ -927,20 +1205,25 @@ var CacheStack = class extends 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 fs.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 fs.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) => {
@@ -963,7 +1246,13 @@ var CacheStack = class extends 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;
@@ -1023,7 +1312,10 @@ var CacheStack = class extends 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) {
@@ -1037,6 +1329,9 @@ var CacheStack = class extends 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;
   }
@@ -1054,12 +1349,70 @@ var CacheStack = class extends 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;
@@ -1134,33 +1487,28 @@ var CacheStack = class extends 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") {
@@ -1184,8 +1532,17 @@ var CacheStack = class extends 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);
@@ -1261,6 +1618,12 @@ var CacheStack = class extends EventEmitter {
       }
     }
   }
+  async getTagsForKey(key) {
+    if (this.tagIndex.tagsForKey) {
+      return this.tagIndex.tagsForKey(key);
+    }
+    return [];
+  }
   formatError(error) {
     if (error instanceof Error) {
       return error.message;
@@ -1273,11 +1636,110 @@ var CacheStack = class extends EventEmitter {
   shouldBroadcastL1Invalidation() {
     return this.options.broadcastL1Invalidation ?? this.options.publishSetInvalidation ?? true;
   }
-  async deleteKeysFromLayers(layers, keys) {
-    await Promise.all(
-      layers.map(async (layer) => {
-        if (this.shouldSkipLayer(layer)) {
-          return;
+  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) => {
+        if (this.shouldSkipLayer(layer)) {
+          return;
         }
         if (layer.deleteMany) {
           try {
@@ -1316,6 +1778,9 @@ var CacheStack = class extends 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) {
@@ -1327,6 +1792,7 @@ var CacheStack = class extends 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);
   }
@@ -1370,6 +1836,26 @@ var CacheStack = class extends 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);
   }
@@ -1475,41 +1961,47 @@ var CacheStack = class extends 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);
@@ -1521,11 +2013,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") {
@@ -1538,6 +2034,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);
   }
 };
@@ -1586,6 +2086,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, {
@@ -1595,6 +2132,68 @@ function cacheGraphqlResolver(cache, prefix, resolver, options = {}) {
   return (...args) => wrapped(...args);
 }
 
+// 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) => {
@@ -1620,165 +2219,9 @@ function createTrpcCacheMiddleware(cache, prefix, options = {}) {
   };
 }
 
-// src/layers/MemoryLayer.ts
-var MemoryLayer = class {
-  name;
-  defaultTtl;
-  isLocal = true;
-  maxSize;
-  evictionPolicy;
-  entries = /* @__PURE__ */ new Map();
-  constructor(options = {}) {
-    this.name = options.name ?? "memory";
-    this.defaultTtl = options.ttl;
-    this.maxSize = options.maxSize ?? 1e3;
-    this.evictionPolicy = options.evictionPolicy ?? "lru";
-  }
-  async get(key) {
-    const value = await this.getEntry(key);
-    return unwrapStoredValue(value);
-  }
-  async getEntry(key) {
-    const entry = this.entries.get(key);
-    if (!entry) {
-      return null;
-    }
-    if (this.isExpired(entry)) {
-      this.entries.delete(key);
-      return null;
-    }
-    if (this.evictionPolicy === "lru") {
-      this.entries.delete(key);
-      entry.frequency += 1;
-      this.entries.set(key, entry);
-    } else {
-      entry.frequency += 1;
-    }
-    return entry.value;
-  }
-  async getMany(keys) {
-    const values = [];
-    for (const key of keys) {
-      values.push(await this.getEntry(key));
-    }
-    return values;
-  }
-  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,
-      insertedAt: Date.now()
-    });
-    while (this.entries.size > this.maxSize) {
-      this.evict();
-    }
-  }
-  async has(key) {
-    const entry = this.entries.get(key);
-    if (!entry) {
-      return false;
-    }
-    if (this.isExpired(entry)) {
-      this.entries.delete(key);
-      return false;
-    }
-    return true;
-  }
-  async ttl(key) {
-    const entry = this.entries.get(key);
-    if (!entry) {
-      return null;
-    }
-    if (this.isExpired(entry)) {
-      this.entries.delete(key);
-      return null;
-    }
-    if (entry.expiresAt === null) {
-      return null;
-    }
-    return Math.max(0, Math.ceil((entry.expiresAt - Date.now()) / 1e3));
-  }
-  async size() {
-    this.pruneExpired();
-    return this.entries.size;
-  }
-  async delete(key) {
-    this.entries.delete(key);
-  }
-  async deleteMany(keys) {
-    for (const key of keys) {
-      this.entries.delete(key);
-    }
-  }
-  async clear() {
-    this.entries.clear();
-  }
-  async keys() {
-    this.pruneExpired();
-    return [...this.entries.keys()];
-  }
-  exportState() {
-    this.pruneExpired();
-    return [...this.entries.entries()].map(([key, entry]) => ({
-      key,
-      value: entry.value,
-      expiresAt: entry.expiresAt
-    }));
-  }
-  importState(entries) {
-    for (const entry of entries) {
-      if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
-        continue;
-      }
-      this.entries.set(entry.key, {
-        value: entry.value,
-        expiresAt: entry.expiresAt,
-        frequency: 0,
-        insertedAt: Date.now()
-      });
-    }
-    while (this.entries.size > this.maxSize) {
-      this.evict();
-    }
-  }
-  evict() {
-    if (this.evictionPolicy === "lru" || this.evictionPolicy === "fifo") {
-      const oldestKey = this.entries.keys().next().value;
-      if (oldestKey !== void 0) {
-        this.entries.delete(oldestKey);
-      }
-      return;
-    }
-    let victimKey;
-    let minFreq = 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;
-        minInsertedAt = entry.insertedAt;
-        victimKey = key;
-      }
-    }
-    if (victimKey !== void 0) {
-      this.entries.delete(victimKey);
-    }
-  }
-  pruneExpired() {
-    for (const [key, entry] of this.entries.entries()) {
-      if (this.isExpired(entry)) {
-        this.entries.delete(key);
-      }
-    }
-  }
-  isExpired(entry) {
-    return entry.expiresAt !== null && entry.expiresAt <= Date.now();
-  }
-};
-
 // src/layers/RedisLayer.ts
-import { brotliCompressSync, brotliDecompressSync, gunzipSync, gzipSync } from "zlib";
+import { promisify } from "util";
+import { brotliCompress, brotliDecompress, gunzip, gzip } from "zlib";
 
 // src/serialization/JsonSerializer.ts
 var JsonSerializer = class {
@@ -1793,27 +2236,33 @@ var JsonSerializer = class {
 
 // src/layers/RedisLayer.ts
 var BATCH_DELETE_SIZE = 500;
+var gzipAsync = promisify(gzip);
+var gunzipAsync = promisify(gunzip);
+var brotliCompressAsync = promisify(brotliCompress);
+var brotliDecompressAsync = promisify(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);
@@ -1848,8 +2297,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);
@@ -1881,6 +2348,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.
@@ -1927,17 +2406,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;
     }
@@ -1946,18 +2456,21 @@ var RedisLayer = class {
       return payload;
     }
     const header = Buffer.from(`LCZ1:${this.compression}:`);
-    const compressed = this.compression === "gzip" ? gzipSync(source) : 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 gunzipSync(payload.subarray(10));
+      return gunzipAsync(payload.subarray(10));
     }
     if (payload.subarray(0, 12).toString() === "LCZ1:brotli:") {
-      return brotliDecompressSync(payload.subarray(12));
+      return brotliDecompressAsync(payload.subarray(12));
     }
     return payload;
   }
@@ -1965,7 +2478,7 @@ var RedisLayer = class {
 
 // src/layers/DiskLayer.ts
 import { createHash } from "crypto";
-import { promises as fs2 } from "fs";
+import { promises as fs } from "fs";
 import { join } from "path";
 var DiskLayer = class {
   name;
@@ -1973,11 +2486,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));
@@ -1986,7 +2502,7 @@ var DiskLayer = class {
     const filePath = this.keyToPath(key);
     let raw;
     try {
-      raw = await fs2.readFile(filePath);
+      raw = await fs.readFile(filePath);
     } catch {
       return null;
     }
@@ -2004,13 +2520,30 @@ var DiskLayer = class {
     return entry.value;
   }
   async set(key, value, ttl = this.defaultTtl) {
-    await fs2.mkdir(this.directory, { recursive: true });
-    const entry = {
-      value,
-      expiresAt: ttl && ttl > 0 ? Date.now() + ttl * 1e3 : null
-    };
-    const payload = this.serializer.serialize(entry);
-    await fs2.writeFile(this.keyToPath(key), payload);
+    await this.enqueueWrite(async () => {
+      await fs.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 fs.writeFile(tempPath, payload);
+      await fs.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);
@@ -2020,7 +2553,7 @@ var DiskLayer = class {
     const filePath = this.keyToPath(key);
     let raw;
     try {
-      raw = await fs2.readFile(filePath);
+      raw = await fs.readFile(filePath);
     } catch {
       return null;
     }
@@ -2040,45 +2573,125 @@ 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 fs2.readdir(this.directory);
-    } catch {
-      return;
-    }
-    await Promise.all(
-      entries.filter((name) => name.endsWith(".lc")).map((name) => this.safeDelete(join(this.directory, name)))
-    );
+    await this.enqueueWrite(async () => {
+      let entries;
+      try {
+        entries = await fs.readdir(this.directory);
+      } catch {
+        return;
+      }
+      await Promise.all(
+        entries.filter((name) => name.endsWith(".lc")).map((name) => this.safeDelete(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 fs2.readdir(this.directory);
+      entries = await fs.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 = join(this.directory, name);
+        let raw;
+        try {
+          raw = await fs.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 fs.mkdir(this.directory, { recursive: true });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async dispose() {
+  }
   keyToPath(key) {
     const hash = createHash("sha256").update(key).digest("hex");
     return join(this.directory, `${hash}.lc`);
   }
   async safeDelete(filePath) {
     try {
-      await fs2.unlink(filePath);
+      await fs.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 fs.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 = join(this.directory, name);
+        try {
+          const stat = await fs.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)));
+  }
 };
 
 // src/layers/MemcachedLayer.ts
@@ -2088,29 +2701,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));
   }
@@ -2140,7 +2765,7 @@ var MsgpackSerializer = class {
 };
 
 // src/singleflight/RedisSingleFlightCoordinator.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID } from "crypto";
 var RELEASE_SCRIPT = `
 if redis.call("get", KEYS[1]) == ARGV[1] then
   return redis.call("del", KEYS[1])
@@ -2156,7 +2781,7 @@ var RedisSingleFlightCoordinator = class {
   }
   async execute(key, options, worker, waiter) {
     const lockKey = `${this.prefix}:${encodeURIComponent(key)}`;
-    const token = randomUUID2();
+    const token = randomUUID();
     const acquired = await this.client.set(lockKey, token, "PX", options.leaseMs, "NX");
     if (acquired === "OK") {
       try {
@@ -2204,6 +2829,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();
@@ -2227,6 +2858,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");
@@ -2236,6 +2873,7 @@ function sanitizeLabel(value) {
   return value.replace(/["\\\n]/g, "_");
 }
 export {
+  CacheMissError,
   CacheNamespace,
   CacheStack,
   DiskLayer,
@@ -2253,7 +2891,10 @@ export {
   cacheGraphqlResolver,
   createCacheStatsHandler,
   createCachedMethodDecorator,
+  createExpressCacheMiddleware,
   createFastifyLayercachePlugin,
+  createHonoCacheMiddleware,
+  createOpenTelemetryPlugin,
   createPrometheusMetricsExporter,
   createTrpcCacheMiddleware
 };