layercache 1.2.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,6 +17,14 @@ 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
@@ -40,17 +50,18 @@ __export(index_exports, {
   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 import_async_mutex = require("async-mutex");
 var CacheNamespace = class _CacheNamespace {
   constructor(cache, prefix) {
     this.cache = cache;
@@ -58,57 +69,69 @@ var CacheNamespace = class _CacheNamespace {
   }
   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.cache.getOrThrow(this.qualify(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.
@@ -129,10 +152,19 @@ var CacheNamespace = class _CacheNamespace {
     );
   }
   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:`.
@@ -149,7 +181,130 @@ var CacheNamespace = class _CacheNamespace {
   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 {
@@ -243,6 +398,95 @@ 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();
@@ -439,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);
@@ -484,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;
@@ -511,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;
+    }
+    while (patternIndex < pattern.length && pattern[patternIndex] === "*") {
+      patternIndex += 1;
     }
-    return dp[m]?.[n];
+    return patternIndex === pattern.length;
   }
 };
 
@@ -578,26 +856,14 @@ var TagIndex = class {
     }
   }
   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);
+    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()];
   }
@@ -619,15 +885,32 @@ var TagIndex = class {
       if (removed >= toRemove) {
         break;
       }
-      this.knownKeys.delete(key);
-      this.keyToTags.delete(key);
+      this.removeKey(key);
       removed += 1;
     }
   }
+  removeKey(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);
+  }
 };
 
 // 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) {
@@ -644,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;
@@ -705,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."
@@ -713,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;
   /**
@@ -737,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);
@@ -804,8 +1094,8 @@ var CacheStack = class extends import_node_events.EventEmitter {
    * 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;
@@ -835,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;
@@ -857,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",
@@ -877,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();
@@ -893,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);
@@ -935,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();
@@ -983,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;
@@ -1039,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" });
   }
@@ -1073,14 +1385,43 @@ var CacheStack = class extends import_node_events.EventEmitter {
   getHitRate() {
     return this.metricsCollector.hitRate();
   }
+  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 normalizedKey = this.validateCacheKey(key);
-    await this.startup;
+    const userKey = this.validateCacheKey(key);
+    const normalizedKey = this.qualifyKey(userKey);
+    await this.awaitStartup("inspect");
     const foundInLayers = [];
     let freshTtlSeconds = null;
     let staleTtlSeconds = null;
@@ -1111,10 +1452,10 @@ var CacheStack = class extends import_node_events.EventEmitter {
       return null;
     }
     const tags = await this.getTagsForKey(normalizedKey);
-    return { key: normalizedKey, foundInLayers, freshTtlSeconds, staleTtlSeconds, errorTtlSeconds, isStale, tags };
+    return { key: userKey, foundInLayers, freshTtlSeconds, staleTtlSeconds, errorTtlSeconds, isStale, tags };
   }
   async exportState() {
-    await this.startup;
+    await this.awaitStartup("exportState");
     const exported = /* @__PURE__ */ new Map();
     for (const layer of this.layers) {
       if (!layer.keys) {
@@ -1122,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)
         });
@@ -1139,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) => {
@@ -1175,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;
@@ -1235,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) {
@@ -1269,6 +1625,61 @@ 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) {
@@ -1352,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") {
@@ -1402,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);
@@ -1497,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) => {
@@ -1540,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) {
@@ -1551,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);
   }
@@ -1594,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);
   }
@@ -1699,18 +2237,23 @@ 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;
+  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.handlers.size === 0) {
@@ -1767,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);
   }
 };
@@ -1815,6 +2362,16 @@ 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));
   }
@@ -1912,32 +2469,36 @@ function createFastifyLayercachePlugin(cache, options = {}) {
 function createExpressCacheMiddleware(cache, options = {}) {
   const allowedMethods = new Set((options.methods ?? ["GET"]).map((m) => m.toUpperCase()));
   return async (req, res, next) => {
-    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));
+    try {
+      const method = (req.method ?? "GET").toUpperCase();
+      if (!allowedMethods.has(method)) {
+        next();
+        return;
       }
-      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);
-      };
+      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);
     }
-    next();
   };
 }
 
@@ -1950,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) => {
@@ -1982,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);
@@ -2018,6 +2677,11 @@ 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, {
@@ -2070,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()];
@@ -2102,7 +2775,11 @@ 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;
     }
@@ -2117,7 +2794,11 @@ var MemoryLayer = class {
       }
     }
     if (victimKey !== void 0) {
+      const victim = this.entries.get(victimKey);
       this.entries.delete(victimKey);
+      if (victim) {
+        this.onEvict?.(victimKey, unwrapStoredValue(victim.value));
+      }
     }
   }
   pruneExpired() {
@@ -2158,22 +2839,24 @@ var RedisLayer = class {
   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);
@@ -2208,8 +2891,25 @@ 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 serialized = 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) {
@@ -2242,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.
@@ -2288,12 +3000,39 @@ 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(await 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);
@@ -2332,8 +3071,8 @@ var RedisLayer = class {
 };
 
 // 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;
@@ -2342,6 +3081,7 @@ var DiskLayer = class {
   directory;
   serializer;
   maxFiles;
+  writeQueue = Promise.resolve();
   constructor(options) {
     this.directory = options.directory;
     this.defaultTtl = options.ttl;
@@ -2356,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;
     }
@@ -2374,16 +3114,29 @@ 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 = {
-      key,
-      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);
-    if (this.maxFiles !== void 0) {
-      await this.enforceMaxFiles();
+    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) {
@@ -2394,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;
     }
@@ -2414,21 +3167,25 @@ 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.
@@ -2437,7 +3194,7 @@ var DiskLayer = class {
   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 [];
     }
@@ -2448,7 +3205,7 @@ var DiskLayer = class {
         const filePath = (0, import_node_path.join)(this.directory, name);
         let raw;
         try {
-          raw = await import_node_fs2.promises.readFile(filePath);
+          raw = await import_node_fs.promises.readFile(filePath);
         } catch {
           return;
         }
@@ -2472,16 +3229,31 @@ var DiskLayer = class {
     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.
    */
@@ -2491,7 +3263,7 @@ var DiskLayer = class {
     }
     let entries;
     try {
-      entries = await import_node_fs2.promises.readdir(this.directory);
+      entries = await import_node_fs.promises.readdir(this.directory);
     } catch {
       return;
     }
@@ -2503,7 +3275,7 @@ var DiskLayer = class {
       lcFiles.map(async (name) => {
         const filePath = (0, import_node_path.join)(this.directory, name);
         try {
-          const stat = await import_node_fs2.promises.stat(filePath);
+          const stat = await import_node_fs.promises.stat(filePath);
           return { filePath, mtimeMs: stat.mtimeMs };
         } catch {
           return { filePath, mtimeMs: 0 };
@@ -2587,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])
@@ -2603,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 {
@@ -2716,6 +3488,8 @@ function sanitizeLabel(value) {
   createCachedMethodDecorator,
   createExpressCacheMiddleware,
   createFastifyLayercachePlugin,
+  createHonoCacheMiddleware,
+  createOpenTelemetryPlugin,
   createPrometheusMetricsExporter,
   createTrpcCacheMiddleware
 });