layercache 1.0.1 → 1.1.0

package/dist/index.js

@@ -1,5 +1,233 @@
+import {
+  PatternMatcher,
+  RedisTagIndex
+} from "./chunk-QUB5VZFZ.js";
+
 // src/CacheStack.ts
 import { randomUUID } from "crypto";
+import { EventEmitter } from "events";
+import { promises as fs } from "fs";
+
+// src/CacheNamespace.ts
+var CacheNamespace = class {
+  constructor(cache, prefix) {
+    this.cache = cache;
+    this.prefix = prefix;
+  }
+  cache;
+  prefix;
+  async get(key, fetcher, options) {
+    return this.cache.get(this.qualify(key), fetcher, options);
+  }
+  async getOrSet(key, fetcher, options) {
+    return this.cache.getOrSet(this.qualify(key), fetcher, options);
+  }
+  async has(key) {
+    return this.cache.has(this.qualify(key));
+  }
+  async ttl(key) {
+    return this.cache.ttl(this.qualify(key));
+  }
+  async set(key, value, options) {
+    await this.cache.set(this.qualify(key), value, options);
+  }
+  async delete(key) {
+    await this.cache.delete(this.qualify(key));
+  }
+  async mdelete(keys) {
+    await this.cache.mdelete(keys.map((k) => this.qualify(k)));
+  }
+  async clear() {
+    await this.cache.invalidateByPattern(`${this.prefix}:*`);
+  }
+  async mget(entries) {
+    return 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)
+      }))
+    );
+  }
+  async invalidateByTag(tag) {
+    await this.cache.invalidateByTag(tag);
+  }
+  async invalidateByPattern(pattern) {
+    await this.cache.invalidateByPattern(this.qualify(pattern));
+  }
+  wrap(keyPrefix, fetcher, options) {
+    return this.cache.wrap(`${this.prefix}:${keyPrefix}`, fetcher, options);
+  }
+  warm(entries, options) {
+    return this.cache.warm(
+      entries.map((entry) => ({
+        ...entry,
+        key: this.qualify(entry.key)
+      })),
+      options
+    );
+  }
+  getMetrics() {
+    return this.cache.getMetrics();
+  }
+  getHitRate() {
+    return this.cache.getHitRate();
+  }
+  qualify(key) {
+    return `${this.prefix}:${key}`;
+  }
+};
+
+// src/internal/CircuitBreakerManager.ts
+var CircuitBreakerManager = class {
+  breakers = /* @__PURE__ */ new Map();
+  maxEntries;
+  constructor(options) {
+    this.maxEntries = options.maxEntries;
+  }
+  /**
+   * Throws if the circuit is open for the given key.
+   * Automatically resets if the cooldown has elapsed.
+   */
+  assertClosed(key, options) {
+    const state = this.breakers.get(key);
+    if (!state?.openUntil) {
+      return;
+    }
+    const now = Date.now();
+    if (state.openUntil <= now) {
+      state.openUntil = null;
+      state.failures = 0;
+      this.breakers.set(key, state);
+      return;
+    }
+    const remainingMs = state.openUntil - now;
+    const remainingSecs = Math.ceil(remainingMs / 1e3);
+    throw new Error(`Circuit breaker is open for key "${key}" (resets in ${remainingSecs}s).`);
+  }
+  recordFailure(key, options) {
+    if (!options) {
+      return;
+    }
+    const failureThreshold = options.failureThreshold ?? 3;
+    const cooldownMs = options.cooldownMs ?? 3e4;
+    const state = this.breakers.get(key) ?? { failures: 0, openUntil: null };
+    state.failures += 1;
+    if (state.failures >= failureThreshold) {
+      state.openUntil = Date.now() + cooldownMs;
+    }
+    this.breakers.set(key, state);
+    this.pruneIfNeeded();
+  }
+  recordSuccess(key) {
+    this.breakers.delete(key);
+  }
+  isOpen(key) {
+    const state = this.breakers.get(key);
+    if (!state?.openUntil) {
+      return false;
+    }
+    if (state.openUntil <= Date.now()) {
+      state.openUntil = null;
+      state.failures = 0;
+      return false;
+    }
+    return true;
+  }
+  delete(key) {
+    this.breakers.delete(key);
+  }
+  clear() {
+    this.breakers.clear();
+  }
+  tripCount() {
+    let count = 0;
+    for (const state of this.breakers.values()) {
+      if (state.openUntil !== null) {
+        count += 1;
+      }
+    }
+    return count;
+  }
+  pruneIfNeeded() {
+    if (this.breakers.size <= this.maxEntries) {
+      return;
+    }
+    for (const [key, state] of this.breakers.entries()) {
+      if (this.breakers.size <= this.maxEntries) {
+        break;
+      }
+      if (!state.openUntil || state.openUntil <= Date.now()) {
+        this.breakers.delete(key);
+      }
+    }
+    for (const key of this.breakers.keys()) {
+      if (this.breakers.size <= this.maxEntries) {
+        break;
+      }
+      this.breakers.delete(key);
+    }
+  }
+};
+
+// src/internal/MetricsCollector.ts
+var MetricsCollector = class {
+  data = this.empty();
+  get snapshot() {
+    return { ...this.data };
+  }
+  increment(field, amount = 1) {
+    ;
+    this.data[field] += amount;
+  }
+  incrementLayer(map, layerName) {
+    this.data[map][layerName] = (this.data[map][layerName] ?? 0) + 1;
+  }
+  reset() {
+    this.data = this.empty();
+  }
+  hitRate() {
+    const total = this.data.hits + this.data.misses;
+    const overall = total === 0 ? 0 : this.data.hits / total;
+    const byLayer = {};
+    const allLayers = /* @__PURE__ */ new Set([...Object.keys(this.data.hitsByLayer), ...Object.keys(this.data.missesByLayer)]);
+    for (const layer of allLayers) {
+      const h = this.data.hitsByLayer[layer] ?? 0;
+      const m = this.data.missesByLayer[layer] ?? 0;
+      byLayer[layer] = h + m === 0 ? 0 : h / (h + m);
+    }
+    return { overall, byLayer };
+  }
+  empty() {
+    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: {},
+      resetAt: Date.now()
+    };
+  }
+};
 
 // src/internal/StoredValue.ts
 function isStoredValueEnvelope(value) {
@@ -19,7 +247,10 @@ function createStoredValueEnvelope(options) {
     value: options.value,
     freshUntil,
     staleUntil,
-    errorUntil
+    errorUntil,
+    freshTtlSeconds: freshTtlSeconds ?? null,
+    staleWhileRevalidateSeconds: staleWhileRevalidateSeconds ?? null,
+    staleIfErrorSeconds: staleIfErrorSeconds ?? null
   };
 }
 function resolveStoredValue(stored, now = Date.now()) {
@@ -60,6 +291,29 @@ function remainingStoredTtlSeconds(stored, now = Date.now()) {
   }
   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
@@ -76,12 +330,91 @@ function normalizePositiveSeconds(value) {
   return value;
 }
 
-// src/invalidation/PatternMatcher.ts
-var PatternMatcher = class {
-  static matches(pattern, value) {
-    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
-    const regex = new RegExp(`^${escaped.replace(/\*/g, ".*").replace(/\?/g, ".")}$`);
-    return regex.test(value);
+// src/internal/TtlResolver.ts
+var DEFAULT_NEGATIVE_TTL_SECONDS = 60;
+var TtlResolver = class {
+  accessProfiles = /* @__PURE__ */ new Map();
+  maxProfileEntries;
+  constructor(options) {
+    this.maxProfileEntries = options.maxProfileEntries;
+  }
+  recordAccess(key) {
+    const profile = this.accessProfiles.get(key) ?? { hits: 0, lastAccessAt: Date.now() };
+    profile.hits += 1;
+    profile.lastAccessAt = Date.now();
+    this.accessProfiles.set(key, profile);
+    this.pruneIfNeeded();
+  }
+  deleteProfile(key) {
+    this.accessProfiles.delete(key);
+  }
+  clearProfiles() {
+    this.accessProfiles.clear();
+  }
+  resolveFreshTtl(key, layerName, kind, options, fallbackTtl, globalNegativeTtl, globalTtl) {
+    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);
+    const adaptiveTtl = this.applyAdaptiveTtl(key, layerName, baseTtl, options?.adaptiveTtl);
+    const jitter = this.resolveLayerSeconds(layerName, options?.ttlJitter, void 0);
+    return this.applyJitter(adaptiveTtl, jitter);
+  }
+  resolveLayerSeconds(layerName, override, globalDefault, fallback) {
+    if (override !== void 0) {
+      return this.readLayerNumber(layerName, override) ?? fallback;
+    }
+    if (globalDefault !== void 0) {
+      return this.readLayerNumber(layerName, globalDefault) ?? fallback;
+    }
+    return fallback;
+  }
+  applyAdaptiveTtl(key, layerName, ttl, adaptiveTtl) {
+    if (!ttl || !adaptiveTtl) {
+      return ttl;
+    }
+    const profile = this.accessProfiles.get(key);
+    if (!profile) {
+      return ttl;
+    }
+    const config = adaptiveTtl === true ? {} : adaptiveTtl;
+    const hotAfter = config.hotAfter ?? 3;
+    if (profile.hits < hotAfter) {
+      return ttl;
+    }
+    const step = this.resolveLayerSeconds(layerName, config.step, void 0, Math.max(1, Math.round(ttl / 2))) ?? 0;
+    const maxTtl = this.resolveLayerSeconds(layerName, config.maxTtl, void 0, ttl + step * 4) ?? ttl;
+    const multiplier = Math.floor(profile.hits / hotAfter);
+    return Math.min(maxTtl, ttl + step * multiplier);
+  }
+  applyJitter(ttl, jitter) {
+    if (!ttl || ttl <= 0 || !jitter || jitter <= 0) {
+      return ttl;
+    }
+    const delta = (Math.random() * 2 - 1) * jitter;
+    return Math.max(1, Math.round(ttl + delta));
+  }
+  readLayerNumber(layerName, value) {
+    if (typeof value === "number") {
+      return value;
+    }
+    return value[layerName];
+  }
+  pruneIfNeeded() {
+    if (this.accessProfiles.size <= this.maxProfileEntries) {
+      return;
+    }
+    const toRemove = Math.ceil(this.maxProfileEntries * 0.1);
+    let removed = 0;
+    for (const key of this.accessProfiles.keys()) {
+      if (removed >= toRemove) {
+        break;
+      }
+      this.accessProfiles.delete(key);
+      removed += 1;
+    }
   }
 };
 
@@ -148,64 +481,75 @@ import { Mutex } from "async-mutex";
 var StampedeGuard = class {
   mutexes = /* @__PURE__ */ new Map();
   async execute(key, task) {
-    const mutex = this.getMutex(key);
+    const entry = this.getMutexEntry(key);
     try {
-      return await mutex.runExclusive(task);
+      return await entry.mutex.runExclusive(task);
     } finally {
-      if (!mutex.isLocked()) {
+      entry.references -= 1;
+      if (entry.references === 0 && !entry.mutex.isLocked()) {
         this.mutexes.delete(key);
       }
     }
   }
-  getMutex(key) {
-    let mutex = this.mutexes.get(key);
-    if (!mutex) {
-      mutex = new Mutex();
-      this.mutexes.set(key, mutex);
+  getMutexEntry(key) {
+    let entry = this.mutexes.get(key);
+    if (!entry) {
+      entry = { mutex: new Mutex(), references: 0 };
+      this.mutexes.set(key, entry);
     }
-    return mutex;
+    entry.references += 1;
+    return entry;
   }
 };
 
 // src/CacheStack.ts
-var DEFAULT_NEGATIVE_TTL_SECONDS = 60;
 var DEFAULT_SINGLE_FLIGHT_LEASE_MS = 3e4;
 var DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS = 5e3;
 var DEFAULT_SINGLE_FLIGHT_POLL_MS = 50;
-var EMPTY_METRICS = () => ({
-  hits: 0,
-  misses: 0,
-  fetches: 0,
-  sets: 0,
-  deletes: 0,
-  backfills: 0,
-  invalidations: 0,
-  staleHits: 0,
-  refreshes: 0,
-  refreshErrors: 0,
-  writeFailures: 0,
-  singleFlightWaits: 0
-});
+var MAX_CACHE_KEY_LENGTH = 1024;
+var DEFAULT_MAX_PROFILE_ENTRIES = 1e5;
 var DebugLogger = class {
   enabled;
   constructor(enabled) {
     this.enabled = enabled;
   }
   debug(message, context) {
+    this.write("debug", message, context);
+  }
+  info(message, context) {
+    this.write("info", message, context);
+  }
+  warn(message, context) {
+    this.write("warn", message, context);
+  }
+  error(message, context) {
+    this.write("error", message, context);
+  }
+  write(level, message, context) {
     if (!this.enabled) {
       return;
     }
     const suffix = context ? ` ${JSON.stringify(context)}` : "";
-    console.debug(`[layercache] ${message}${suffix}`);
+    console[level](`[layercache] ${message}${suffix}`);
   }
 };
-var CacheStack = class {
+var CacheStack = class extends EventEmitter {
   constructor(layers, options = {}) {
+    super();
     this.layers = layers;
     this.options = options;
     if (layers.length === 0) {
       throw new Error("CacheStack requires at least one cache layer.");
     }
+    this.validateConfiguration();
+    const maxProfileEntries = options.maxProfileEntries ?? DEFAULT_MAX_PROFILE_ENTRIES;
+    this.ttlResolver = new TtlResolver({ maxProfileEntries });
+    this.circuitBreakerManager = new CircuitBreakerManager({ maxEntries: maxProfileEntries });
+    if (options.publishSetInvalidation !== void 0) {
+      console.warn(
+        "[layercache] CacheStackOptions.publishSetInvalidation is deprecated. Use broadcastL1Invalidation instead."
+      );
+    }
     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();
@@ -214,112 +558,313 @@ var CacheStack = class {
   layers;
   options;
   stampedeGuard = new StampedeGuard();
-  metrics = EMPTY_METRICS();
+  metricsCollector = new MetricsCollector();
   instanceId = randomUUID();
   startup;
   unsubscribeInvalidation;
   logger;
   tagIndex;
   backgroundRefreshes = /* @__PURE__ */ new Map();
+  layerDegradedUntil = /* @__PURE__ */ new Map();
+  ttlResolver;
+  circuitBreakerManager;
+  isDisconnecting = false;
+  disconnectPromise;
+  /**
+   * Read-through cache get.
+   * Returns the cached value if present and fresh, or invokes `fetcher` on a miss
+   * and stores the result across all layers. Returns `null` if the key is not found
+   * and no `fetcher` is provided.
+   */
   async get(key, fetcher, options) {
+    const normalizedKey = this.validateCacheKey(key);
+    this.validateWriteOptions(options);
     await this.startup;
-    const hit = await this.readFromLayers(key, options, "allow-stale");
+    const hit = await this.readFromLayers(normalizedKey, options, "allow-stale");
     if (hit.found) {
+      this.ttlResolver.recordAccess(normalizedKey);
+      if (this.isNegativeStoredValue(hit.stored)) {
+        this.metricsCollector.increment("negativeCacheHits");
+      }
       if (hit.state === "fresh") {
-        this.metrics.hits += 1;
+        this.metricsCollector.increment("hits");
+        await this.applyFreshReadPolicies(normalizedKey, hit, options, fetcher);
         return hit.value;
       }
       if (hit.state === "stale-while-revalidate") {
-        this.metrics.hits += 1;
-        this.metrics.staleHits += 1;
+        this.metricsCollector.increment("hits");
+        this.metricsCollector.increment("staleHits");
+        this.emit("stale-serve", { key: normalizedKey, state: hit.state, layer: hit.layerName });
         if (fetcher) {
-          this.scheduleBackgroundRefresh(key, fetcher, options);
+          this.scheduleBackgroundRefresh(normalizedKey, fetcher, options);
         }
         return hit.value;
       }
       if (!fetcher) {
-        this.metrics.hits += 1;
-        this.metrics.staleHits += 1;
+        this.metricsCollector.increment("hits");
+        this.metricsCollector.increment("staleHits");
+        this.emit("stale-serve", { key: normalizedKey, state: hit.state, layer: hit.layerName });
         return hit.value;
       }
       try {
-        return await this.fetchWithGuards(key, fetcher, options);
+        return await this.fetchWithGuards(normalizedKey, fetcher, options);
       } catch (error) {
-        this.metrics.staleHits += 1;
-        this.metrics.refreshErrors += 1;
-        this.logger.debug("stale-if-error", { key, error: this.formatError(error) });
+        this.metricsCollector.increment("staleHits");
+        this.metricsCollector.increment("refreshErrors");
+        this.logger.debug?.("stale-if-error", { key: normalizedKey, error: this.formatError(error) });
         return hit.value;
       }
     }
-    this.metrics.misses += 1;
+    this.metricsCollector.increment("misses");
     if (!fetcher) {
       return null;
     }
-    return this.fetchWithGuards(key, fetcher, options);
+    return this.fetchWithGuards(normalizedKey, fetcher, options);
+  }
+  /**
+   * Alias for `get(key, fetcher, options)` — explicit get-or-set pattern.
+   * Fetches and caches the value if not already present.
+   */
+  async getOrSet(key, fetcher, options) {
+    return this.get(key, fetcher, options);
+  }
+  /**
+   * 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;
+    for (const layer of this.layers) {
+      if (this.shouldSkipLayer(layer)) {
+        continue;
+      }
+      if (layer.has) {
+        try {
+          const exists = await layer.has(normalizedKey);
+          if (exists) {
+            return true;
+          }
+        } catch {
+        }
+      } else {
+        try {
+          const value = await layer.get(normalizedKey);
+          if (value !== null) {
+            return true;
+          }
+        } catch {
+        }
+      }
+    }
+    return false;
+  }
+  /**
+   * Returns the remaining TTL in seconds for the key in the fastest layer
+   * 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;
+    for (const layer of this.layers) {
+      if (this.shouldSkipLayer(layer)) {
+        continue;
+      }
+      if (layer.ttl) {
+        try {
+          const remaining = await layer.ttl(normalizedKey);
+          if (remaining !== null) {
+            return remaining;
+          }
+        } catch {
+        }
+      }
+    }
+    return null;
   }
+  /**
+   * Stores a value in all cache layers. Overwrites any existing value.
+   */
   async set(key, value, options) {
+    const normalizedKey = this.validateCacheKey(key);
+    this.validateWriteOptions(options);
     await this.startup;
-    await this.storeEntry(key, "value", value, options);
+    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;
-    await this.deleteKeys([key]);
-    await this.publishInvalidation({ scope: "key", keys: [key], sourceId: this.instanceId, operation: "delete" });
+    await this.deleteKeys([normalizedKey]);
+    await this.publishInvalidation({
+      scope: "key",
+      keys: [normalizedKey],
+      sourceId: this.instanceId,
+      operation: "delete"
+    });
   }
   async clear() {
     await this.startup;
     await Promise.all(this.layers.map((layer) => layer.clear()));
     await this.tagIndex.clear();
-    this.metrics.invalidations += 1;
-    this.logger.debug("clear");
+    this.ttlResolver.clearProfiles();
+    this.circuitBreakerManager.clear();
+    this.metricsCollector.increment("invalidations");
+    this.logger.debug?.("clear");
     await this.publishInvalidation({ scope: "clear", sourceId: this.instanceId, operation: "clear" });
   }
+  /**
+   * Deletes multiple keys at once. More efficient than calling `delete()` in a loop.
+   */
+  async mdelete(keys) {
+    if (keys.length === 0) {
+      return;
+    }
+    await this.startup;
+    const normalizedKeys = keys.map((k) => this.validateCacheKey(k));
+    await this.deleteKeys(normalizedKeys);
+    await this.publishInvalidation({
+      scope: "keys",
+      keys: normalizedKeys,
+      sourceId: this.instanceId,
+      operation: "delete"
+    });
+  }
   async mget(entries) {
     if (entries.length === 0) {
       return [];
     }
-    const canFastPath = entries.every((entry) => entry.fetch === void 0 && entry.options === void 0);
+    const normalizedEntries = entries.map((entry) => ({
+      ...entry,
+      key: this.validateCacheKey(entry.key)
+    }));
+    normalizedEntries.forEach((entry) => this.validateWriteOptions(entry.options));
+    const canFastPath = normalizedEntries.every((entry) => entry.fetch === void 0 && entry.options === void 0);
     if (!canFastPath) {
-      return Promise.all(entries.map((entry) => this.get(entry.key, entry.fetch, entry.options)));
+      const pendingReads = /* @__PURE__ */ new Map();
+      return Promise.all(
+        normalizedEntries.map((entry) => {
+          const optionsSignature = this.serializeOptions(entry.options);
+          const existing = pendingReads.get(entry.key);
+          if (!existing) {
+            const promise = this.get(entry.key, entry.fetch, entry.options);
+            pendingReads.set(entry.key, {
+              promise,
+              fetch: entry.fetch,
+              optionsSignature
+            });
+            return promise;
+          }
+          if (existing.fetch !== entry.fetch || existing.optionsSignature !== optionsSignature) {
+            throw new Error(`mget received conflicting entries for key "${entry.key}".`);
+          }
+          return existing.promise;
+        })
+      );
     }
     await this.startup;
-    const pending = new Set(entries.map((_, index) => index));
-    const results = Array(entries.length).fill(null);
-    for (const layer of this.layers) {
-      const indexes = [...pending];
-      if (indexes.length === 0) {
+    const pending = /* @__PURE__ */ new Set();
+    const indexesByKey = /* @__PURE__ */ new Map();
+    const resultsByKey = /* @__PURE__ */ new Map();
+    for (let index = 0; index < normalizedEntries.length; index += 1) {
+      const entry = normalizedEntries[index];
+      if (!entry) continue;
+      const key = entry.key;
+      const indexes = indexesByKey.get(key) ?? [];
+      indexes.push(index);
+      indexesByKey.set(key, indexes);
+      pending.add(key);
+    }
+    for (let layerIndex = 0; layerIndex < this.layers.length; layerIndex += 1) {
+      const layer = this.layers[layerIndex];
+      if (!layer) continue;
+      const keys = [...pending];
+      if (keys.length === 0) {
         break;
       }
-      const keys = indexes.map((index) => entries[index].key);
       const values = layer.getMany ? await layer.getMany(keys) : await Promise.all(keys.map((key) => this.readLayerEntry(layer, key)));
       for (let offset = 0; offset < values.length; offset += 1) {
-        const index = indexes[offset];
+        const key = keys[offset];
         const stored = values[offset];
-        if (stored === null) {
+        if (!key || stored === null) {
           continue;
         }
         const resolved = resolveStoredValue(stored);
         if (resolved.state === "expired") {
-          await layer.delete(entries[index].key);
+          await layer.delete(key);
           continue;
         }
-        await this.tagIndex.touch(entries[index].key);
-        await this.backfill(entries[index].key, stored, this.layers.indexOf(layer) - 1, entries[index].options);
-        results[index] = resolved.value;
-        pending.delete(index);
-        this.metrics.hits += 1;
+        await this.tagIndex.touch(key);
+        await this.backfill(key, stored, layerIndex - 1);
+        resultsByKey.set(key, resolved.value);
+        pending.delete(key);
+        this.metricsCollector.increment("hits", indexesByKey.get(key)?.length ?? 1);
       }
     }
     if (pending.size > 0) {
-      for (const index of pending) {
-        await this.tagIndex.remove(entries[index].key);
-        this.metrics.misses += 1;
+      for (const key of pending) {
+        await this.tagIndex.remove(key);
+        this.metricsCollector.increment("misses", indexesByKey.get(key)?.length ?? 1);
       }
     }
-    return results;
+    return normalizedEntries.map((entry) => resultsByKey.get(entry.key) ?? null);
   }
   async mset(entries) {
-    await Promise.all(entries.map((entry) => this.set(entry.key, entry.value, entry.options)));
+    const normalizedEntries = entries.map((entry) => ({
+      ...entry,
+      key: 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)));
+  }
+  async warm(entries, options = {}) {
+    const concurrency = Math.max(1, options.concurrency ?? 4);
+    const total = entries.length;
+    let completed = 0;
+    const queue = [...entries].sort((left, right) => (right.priority ?? 0) - (left.priority ?? 0));
+    const workers = Array.from({ length: Math.min(concurrency, queue.length || 1) }, async () => {
+      while (queue.length > 0) {
+        const entry = queue.shift();
+        if (!entry) {
+          return;
+        }
+        let success = false;
+        try {
+          await this.get(entry.key, entry.fetcher, entry.options);
+          this.emit("warm", { key: entry.key });
+          success = true;
+        } catch (error) {
+          this.emitError("warm", { key: entry.key, error: this.formatError(error) });
+          if (!options.continueOnError) {
+            throw error;
+          }
+        } finally {
+          completed += 1;
+          const progress = { completed, total, key: entry.key, success };
+          options.onProgress?.(progress);
+        }
+      }
+    });
+    await Promise.all(workers);
+  }
+  /**
+   * Returns a cached version of `fetcher`. The cache key is derived from
+   * `prefix` plus the serialized arguments unless a `keyResolver` is provided.
+   */
+  wrap(prefix, fetcher, options = {}) {
+    return (...args) => {
+      const suffix = options.keyResolver ? options.keyResolver(...args) : args.map((argument) => this.serializeKeyPart(argument)).join(":");
+      const key = suffix.length > 0 ? `${prefix}:${suffix}` : prefix;
+      return this.get(key, () => fetcher(...args), options);
+    };
+  }
+  /**
+   * Creates a `CacheNamespace` that automatically prefixes all keys with
+   * `prefix:`. Useful for multi-tenant or module-level isolation.
+   */
+  namespace(prefix) {
+    return new CacheNamespace(this, prefix);
   }
   async invalidateByTag(tag) {
     await this.startup;
@@ -334,15 +879,94 @@ var CacheStack = class {
     await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
   }
   getMetrics() {
-    return { ...this.metrics };
+    return this.metricsCollector.snapshot;
+  }
+  getStats() {
+    return {
+      metrics: this.getMetrics(),
+      layers: this.layers.map((layer) => ({
+        name: layer.name,
+        isLocal: Boolean(layer.isLocal),
+        degradedUntil: this.layerDegradedUntil.get(layer.name) ?? null
+      })),
+      backgroundRefreshes: this.backgroundRefreshes.size
+    };
   }
   resetMetrics() {
-    Object.assign(this.metrics, EMPTY_METRICS());
+    this.metricsCollector.reset();
   }
-  async disconnect() {
+  /**
+   * Returns computed hit-rate statistics (overall and per-layer).
+   */
+  getHitRate() {
+    return this.metricsCollector.hitRate();
+  }
+  async exportState() {
+    await this.startup;
+    const exported = /* @__PURE__ */ new Map();
+    for (const layer of this.layers) {
+      if (!layer.keys) {
+        continue;
+      }
+      const keys = await layer.keys();
+      for (const key of keys) {
+        if (exported.has(key)) {
+          continue;
+        }
+        const stored = await this.readLayerEntry(layer, key);
+        if (stored === null) {
+          continue;
+        }
+        exported.set(key, {
+          key,
+          value: stored,
+          ttl: remainingStoredTtlSeconds(stored)
+        });
+      }
+    }
+    return [...exported.values()];
+  }
+  async importState(entries) {
     await this.startup;
-    await this.unsubscribeInvalidation?.();
-    await Promise.allSettled(this.backgroundRefreshes.values());
+    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);
+      })
+    );
+  }
+  async persistToFile(filePath) {
+    const snapshot = await this.exportState();
+    await fs.writeFile(filePath, JSON.stringify(snapshot, null, 2), "utf8");
+  }
+  async restoreFromFile(filePath) {
+    const raw = await fs.readFile(filePath, "utf8");
+    let parsed;
+    try {
+      parsed = JSON.parse(raw, (_key, value) => {
+        if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+          return Object.assign(/* @__PURE__ */ Object.create(null), value);
+        }
+        return value;
+      });
+    } catch (cause) {
+      throw new Error(`Invalid snapshot file: could not parse JSON (${this.formatError(cause)})`);
+    }
+    if (!this.isCacheSnapshotEntries(parsed)) {
+      throw new Error("Invalid snapshot file: expected an array of { key: string, value, ttl? } entries");
+    }
+    await this.importState(parsed);
+  }
+  async disconnect() {
+    if (!this.disconnectPromise) {
+      this.isDisconnecting = true;
+      this.disconnectPromise = (async () => {
+        await this.startup;
+        await this.unsubscribeInvalidation?.();
+        await Promise.allSettled([...this.backgroundRefreshes.values()]);
+      })();
+    }
+    await this.disconnectPromise;
   }
   async initialize() {
     if (!this.options.invalidationBus) {
@@ -356,7 +980,7 @@ var CacheStack = class {
     const fetchTask = async () => {
       const secondHit = await this.readFromLayers(key, options, "fresh-only");
       if (secondHit.found) {
-        this.metrics.hits += 1;
+        this.metricsCollector.increment("hits");
         return secondHit.value;
       }
       return this.fetchAndPopulate(key, fetcher, options);
@@ -381,11 +1005,12 @@ var CacheStack = class {
     const timeoutMs = this.options.singleFlightTimeoutMs ?? DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS;
     const pollIntervalMs = this.options.singleFlightPollMs ?? DEFAULT_SINGLE_FLIGHT_POLL_MS;
     const deadline = Date.now() + timeoutMs;
-    this.metrics.singleFlightWaits += 1;
+    this.metricsCollector.increment("singleFlightWaits");
+    this.emit("stampede-dedupe", { key });
     while (Date.now() < deadline) {
       const hit = await this.readFromLayers(key, options, "fresh-only");
       if (hit.found) {
-        this.metrics.hits += 1;
+        this.metricsCollector.increment("hits");
         return hit.value;
       }
       await this.sleep(pollIntervalMs);
@@ -393,8 +1018,18 @@ var CacheStack = class {
     return this.fetchAndPopulate(key, fetcher, options);
   }
   async fetchAndPopulate(key, fetcher, options) {
-    this.metrics.fetches += 1;
-    const fetched = await fetcher();
+    this.circuitBreakerManager.assertClosed(key, options?.circuitBreaker ?? this.options.circuitBreaker);
+    this.metricsCollector.increment("fetches");
+    const fetchStart = Date.now();
+    let fetched;
+    try {
+      fetched = await fetcher();
+      this.circuitBreakerManager.recordSuccess(key);
+      this.logger.debug?.("fetch", { key, durationMs: Date.now() - fetchStart });
+    } catch (error) {
+      this.recordCircuitFailure(key, options?.circuitBreaker ?? this.options.circuitBreaker, error);
+      throw error;
+    }
     if (fetched === null || fetched === void 0) {
       if (!this.shouldNegativeCache(options)) {
         return null;
@@ -412,9 +1047,10 @@ var CacheStack = class {
     } else {
       await this.tagIndex.touch(key);
     }
-    this.metrics.sets += 1;
-    this.logger.debug("set", { key, kind, tags: options?.tags });
-    if (this.options.publishSetInvalidation !== false) {
+    this.metricsCollector.increment("sets");
+    this.logger.debug?.("set", { key, kind, tags: options?.tags });
+    this.emit("set", { key, kind, tags: options?.tags });
+    if (this.shouldBroadcastL1Invalidation()) {
       await this.publishInvalidation({ scope: "key", keys: [key], sourceId: this.instanceId, operation: "write" });
     }
   }
@@ -422,8 +1058,10 @@ var CacheStack = class {
     let sawRetainableValue = false;
     for (let index = 0; index < this.layers.length; index += 1) {
       const layer = this.layers[index];
+      if (!layer) continue;
       const stored = await this.readLayerEntry(layer, key);
       if (stored === null) {
+        this.metricsCollector.incrementLayer("missesByLayer", layer.name);
         continue;
       }
       const resolved = resolveStoredValue(stored);
@@ -437,20 +1075,41 @@ var CacheStack = class {
       }
       await this.tagIndex.touch(key);
       await this.backfill(key, stored, index - 1, options);
-      this.logger.debug("hit", { key, layer: layer.name, state: resolved.state });
-      return { found: true, value: resolved.value, stored, state: resolved.state };
+      this.metricsCollector.incrementLayer("hitsByLayer", layer.name);
+      this.logger.debug?.("hit", { key, layer: layer.name, state: resolved.state });
+      this.emit("hit", { key, layer: layer.name, state: resolved.state });
+      return {
+        found: true,
+        value: resolved.value,
+        stored,
+        state: resolved.state,
+        layerIndex: index,
+        layerName: layer.name
+      };
     }
     if (!sawRetainableValue) {
       await this.tagIndex.remove(key);
     }
-    this.logger.debug("miss", { key, mode });
+    this.logger.debug?.("miss", { key, mode });
+    this.emit("miss", { key, mode });
     return { found: false, value: null, stored: null, state: "miss" };
   }
   async readLayerEntry(layer, key) {
+    if (this.shouldSkipLayer(layer)) {
+      return null;
+    }
     if (layer.getEntry) {
-      return layer.getEntry(key);
+      try {
+        return await layer.getEntry(key);
+      } catch (error) {
+        return this.handleLayerFailure(layer, "read", error);
+      }
+    }
+    try {
+      return await layer.get(key);
+    } catch (error) {
+      return this.handleLayerFailure(layer, "read", error);
     }
-    return layer.get(key);
   }
   async backfill(key, stored, upToIndex, options) {
     if (upToIndex < 0) {
@@ -458,26 +1117,34 @@ var CacheStack = class {
     }
     for (let index = 0; index <= upToIndex; index += 1) {
       const layer = this.layers[index];
+      if (!layer || this.shouldSkipLayer(layer)) {
+        continue;
+      }
       const ttl = remainingStoredTtlSeconds(stored) ?? this.resolveLayerSeconds(layer.name, options?.ttl, void 0, layer.defaultTtl);
-      await layer.set(key, stored, ttl);
-      this.metrics.backfills += 1;
-      this.logger.debug("backfill", { key, layer: layer.name });
+      try {
+        await layer.set(key, stored, ttl);
+      } catch (error) {
+        await this.handleLayerFailure(layer, "backfill", error);
+        continue;
+      }
+      this.metricsCollector.increment("backfills");
+      this.logger.debug?.("backfill", { key, layer: layer.name });
+      this.emit("backfill", { key, layer: layer.name });
     }
   }
   async writeAcrossLayers(key, kind, value, options) {
     const now = Date.now();
     const operations = this.layers.map((layer) => async () => {
-      const freshTtl = this.resolveFreshTtl(layer.name, kind, options, layer.defaultTtl);
+      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 staleIfError = this.resolveLayerSeconds(layer.name, options?.staleIfError, this.options.staleIfError);
       const payload = createStoredValueEnvelope({
         kind,
         value,
@@ -487,7 +1154,11 @@ var CacheStack = class {
         now
       });
       const ttl = remainingStoredTtlSeconds(payload, now) ?? freshTtl;
-      await layer.set(key, payload, ttl);
+      try {
+        await layer.set(key, payload, ttl);
+      } catch (error) {
+        await this.handleLayerFailure(layer, "write", error);
+      }
     });
     await this.executeLayerOperations(operations, { key, action: kind === "empty" ? "negative-set" : "set" });
   }
@@ -501,8 +1172,8 @@ var CacheStack = class {
     if (failures.length === 0) {
       return;
     }
-    this.metrics.writeFailures += failures.length;
-    this.logger.debug("write-failure", {
+    this.metricsCollector.increment("writeFailures", failures.length);
+    this.logger.debug?.("write-failure", {
       ...context,
       failures: failures.map((failure) => this.formatError(failure.reason))
     });
@@ -513,52 +1184,26 @@ var CacheStack = class {
       );
     }
   }
-  resolveFreshTtl(layerName, kind, options, fallbackTtl) {
-    const baseTtl = kind === "empty" ? this.resolveLayerSeconds(
-      layerName,
-      options?.negativeTtl,
-      this.options.negativeTtl,
-      this.resolveLayerSeconds(layerName, options?.ttl, void 0, fallbackTtl) ?? DEFAULT_NEGATIVE_TTL_SECONDS
-    ) : this.resolveLayerSeconds(layerName, options?.ttl, void 0, fallbackTtl);
-    const jitter = this.resolveLayerSeconds(layerName, options?.ttlJitter, this.options.ttlJitter);
-    return this.applyJitter(baseTtl, jitter);
+  resolveFreshTtl(key, layerName, kind, options, fallbackTtl) {
+    return this.ttlResolver.resolveFreshTtl(key, layerName, kind, options, fallbackTtl, this.options.negativeTtl);
   }
   resolveLayerSeconds(layerName, override, globalDefault, fallback) {
-    if (override !== void 0) {
-      return this.readLayerNumber(layerName, override) ?? fallback;
-    }
-    if (globalDefault !== void 0) {
-      return this.readLayerNumber(layerName, globalDefault) ?? fallback;
-    }
-    return fallback;
-  }
-  readLayerNumber(layerName, value) {
-    if (typeof value === "number") {
-      return value;
-    }
-    return value[layerName];
-  }
-  applyJitter(ttl, jitter) {
-    if (!ttl || ttl <= 0 || !jitter || jitter <= 0) {
-      return ttl;
-    }
-    const delta = (Math.random() * 2 - 1) * jitter;
-    return Math.max(1, Math.round(ttl + delta));
+    return this.ttlResolver.resolveLayerSeconds(layerName, override, globalDefault, fallback);
   }
   shouldNegativeCache(options) {
     return options?.negativeCache ?? this.options.negativeCaching ?? false;
   }
   scheduleBackgroundRefresh(key, fetcher, options) {
-    if (this.backgroundRefreshes.has(key)) {
+    if (this.isDisconnecting || this.backgroundRefreshes.has(key)) {
       return;
     }
     const refresh = (async () => {
-      this.metrics.refreshes += 1;
+      this.metricsCollector.increment("refreshes");
       try {
         await this.fetchWithGuards(key, fetcher, options);
       } catch (error) {
-        this.metrics.refreshErrors += 1;
-        this.logger.debug("refresh-error", { key, error: this.formatError(error) });
+        this.metricsCollector.increment("refreshErrors");
+        this.logger.debug?.("refresh-error", { key, error: this.formatError(error) });
       } finally {
         this.backgroundRefreshes.delete(key);
       }
@@ -576,21 +1221,16 @@ var CacheStack = class {
     if (keys.length === 0) {
       return;
     }
-    await Promise.all(
-      this.layers.map(async (layer) => {
-        if (layer.deleteMany) {
-          await layer.deleteMany(keys);
-          return;
-        }
-        await Promise.all(keys.map((key) => layer.delete(key)));
-      })
-    );
+    await this.deleteKeysFromLayers(this.layers, keys);
     for (const key of keys) {
       await this.tagIndex.remove(key);
+      this.ttlResolver.deleteProfile(key);
+      this.circuitBreakerManager.delete(key);
     }
-    this.metrics.deletes += keys.length;
-    this.metrics.invalidations += 1;
-    this.logger.debug("delete", { keys });
+    this.metricsCollector.increment("deletes", keys.length);
+    this.metricsCollector.increment("invalidations");
+    this.logger.debug?.("delete", { keys });
+    this.emit("delete", { keys });
   }
   async publishInvalidation(message) {
     if (!this.options.invalidationBus) {
@@ -609,21 +1249,15 @@ var CacheStack = class {
     if (message.scope === "clear") {
       await Promise.all(localLayers.map((layer) => layer.clear()));
       await this.tagIndex.clear();
+      this.ttlResolver.clearProfiles();
       return;
     }
     const keys = message.keys ?? [];
-    await Promise.all(
-      localLayers.map(async (layer) => {
-        if (layer.deleteMany) {
-          await layer.deleteMany(keys);
-          return;
-        }
-        await Promise.all(keys.map((key) => layer.delete(key)));
-      })
-    );
+    await this.deleteKeysFromLayers(localLayers, keys);
     if (message.operation !== "write") {
       for (const key of keys) {
         await this.tagIndex.remove(key);
+        this.ttlResolver.deleteProfile(key);
       }
     }
   }
@@ -636,6 +1270,210 @@ var CacheStack = class {
   sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
+  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;
+        }
+        if (layer.deleteMany) {
+          try {
+            await layer.deleteMany(keys);
+          } catch (error) {
+            await this.handleLayerFailure(layer, "delete", error);
+          }
+          return;
+        }
+        await Promise.all(
+          keys.map(async (key) => {
+            try {
+              await layer.delete(key);
+            } catch (error) {
+              await this.handleLayerFailure(layer, "delete", error);
+            }
+          })
+        );
+      })
+    );
+  }
+  validateConfiguration() {
+    if (this.options.broadcastL1Invalidation !== void 0 && this.options.publishSetInvalidation !== void 0 && this.options.broadcastL1Invalidation !== this.options.publishSetInvalidation) {
+      throw new Error("broadcastL1Invalidation and publishSetInvalidation cannot conflict.");
+    }
+    if (this.options.stampedePrevention === false && this.options.singleFlightCoordinator) {
+      throw new Error("singleFlightCoordinator requires stampedePrevention to remain enabled.");
+    }
+    this.validateLayerNumberOption("negativeTtl", this.options.negativeTtl);
+    this.validateLayerNumberOption("staleWhileRevalidate", this.options.staleWhileRevalidate);
+    this.validateLayerNumberOption("staleIfError", this.options.staleIfError);
+    this.validateLayerNumberOption("ttlJitter", this.options.ttlJitter);
+    this.validateLayerNumberOption("refreshAhead", this.options.refreshAhead);
+    this.validatePositiveNumber("singleFlightLeaseMs", this.options.singleFlightLeaseMs);
+    this.validatePositiveNumber("singleFlightTimeoutMs", this.options.singleFlightTimeoutMs);
+    this.validatePositiveNumber("singleFlightPollMs", this.options.singleFlightPollMs);
+    this.validateAdaptiveTtlOptions(this.options.adaptiveTtl);
+    this.validateCircuitBreakerOptions(this.options.circuitBreaker);
+  }
+  validateWriteOptions(options) {
+    if (!options) {
+      return;
+    }
+    this.validateLayerNumberOption("options.ttl", options.ttl);
+    this.validateLayerNumberOption("options.negativeTtl", options.negativeTtl);
+    this.validateLayerNumberOption("options.staleWhileRevalidate", options.staleWhileRevalidate);
+    this.validateLayerNumberOption("options.staleIfError", options.staleIfError);
+    this.validateLayerNumberOption("options.ttlJitter", options.ttlJitter);
+    this.validateLayerNumberOption("options.refreshAhead", options.refreshAhead);
+    this.validateAdaptiveTtlOptions(options.adaptiveTtl);
+    this.validateCircuitBreakerOptions(options.circuitBreaker);
+  }
+  validateLayerNumberOption(name, value) {
+    if (value === void 0) {
+      return;
+    }
+    if (typeof value === "number") {
+      this.validateNonNegativeNumber(name, value);
+      return;
+    }
+    for (const [layerName, layerValue] of Object.entries(value)) {
+      if (layerValue === void 0) {
+        continue;
+      }
+      this.validateNonNegativeNumber(`${name}.${layerName}`, layerValue);
+    }
+  }
+  validatePositiveNumber(name, value) {
+    if (value === void 0) {
+      return;
+    }
+    if (!Number.isFinite(value) || value <= 0) {
+      throw new Error(`${name} must be a positive finite number.`);
+    }
+  }
+  validateNonNegativeNumber(name, value) {
+    if (!Number.isFinite(value) || value < 0) {
+      throw new Error(`${name} must be a non-negative finite number.`);
+    }
+  }
+  validateCacheKey(key) {
+    if (key.length === 0) {
+      throw new Error("Cache key must not be empty.");
+    }
+    if (key.length > MAX_CACHE_KEY_LENGTH) {
+      throw new Error(`Cache key length must be at most ${MAX_CACHE_KEY_LENGTH} characters.`);
+    }
+    if (/[\u0000-\u001F\u007F]/.test(key)) {
+      throw new Error("Cache key contains unsupported control characters.");
+    }
+    return key;
+  }
+  serializeOptions(options) {
+    return JSON.stringify(this.normalizeForSerialization(options) ?? null);
+  }
+  validateAdaptiveTtlOptions(options) {
+    if (!options || options === true) {
+      return;
+    }
+    this.validatePositiveNumber("adaptiveTtl.hotAfter", options.hotAfter);
+    this.validateLayerNumberOption("adaptiveTtl.step", options.step);
+    this.validateLayerNumberOption("adaptiveTtl.maxTtl", options.maxTtl);
+  }
+  validateCircuitBreakerOptions(options) {
+    if (!options) {
+      return;
+    }
+    this.validatePositiveNumber("circuitBreaker.failureThreshold", options.failureThreshold);
+    this.validatePositiveNumber("circuitBreaker.cooldownMs", options.cooldownMs);
+  }
+  async applyFreshReadPolicies(key, hit, options, fetcher) {
+    const refreshAhead = this.resolveLayerSeconds(hit.layerName, options?.refreshAhead, this.options.refreshAhead, 0) ?? 0;
+    const remainingFreshTtl = remainingFreshTtlSeconds(hit.stored) ?? 0;
+    if ((options?.slidingTtl ?? false) && isStoredValueEnvelope(hit.stored)) {
+      const refreshed = refreshStoredEnvelope(hit.stored);
+      const ttl = remainingStoredTtlSeconds(refreshed);
+      for (let index = 0; index <= hit.layerIndex; index += 1) {
+        const layer = this.layers[index];
+        if (!layer || this.shouldSkipLayer(layer)) {
+          continue;
+        }
+        try {
+          await layer.set(key, refreshed, ttl);
+        } catch (error) {
+          await this.handleLayerFailure(layer, "sliding-ttl", error);
+        }
+      }
+    }
+    if (fetcher && refreshAhead > 0 && remainingFreshTtl > 0 && remainingFreshTtl <= refreshAhead) {
+      this.scheduleBackgroundRefresh(key, fetcher, options);
+    }
+  }
+  shouldSkipLayer(layer) {
+    const degradedUntil = this.layerDegradedUntil.get(layer.name);
+    return degradedUntil !== void 0 && degradedUntil > Date.now();
+  }
+  async handleLayerFailure(layer, operation, error) {
+    if (!this.isGracefulDegradationEnabled()) {
+      throw error;
+    }
+    const retryAfterMs = typeof this.options.gracefulDegradation === "object" ? this.options.gracefulDegradation.retryAfterMs ?? 1e4 : 1e4;
+    this.layerDegradedUntil.set(layer.name, Date.now() + retryAfterMs);
+    this.metricsCollector.increment("degradedOperations");
+    this.logger.warn?.("layer-degraded", { layer: layer.name, operation, error: this.formatError(error) });
+    this.emitError(operation, { layer: layer.name, degraded: true, error: this.formatError(error) });
+    return null;
+  }
+  isGracefulDegradationEnabled() {
+    return Boolean(this.options.gracefulDegradation);
+  }
+  recordCircuitFailure(key, options, error) {
+    if (!options) {
+      return;
+    }
+    this.circuitBreakerManager.recordFailure(key, options);
+    if (this.circuitBreakerManager.isOpen(key)) {
+      this.metricsCollector.increment("circuitBreakerTrips");
+    }
+    this.emitError("fetch", { key, error: this.formatError(error) });
+  }
+  isNegativeStoredValue(stored) {
+    return isStoredValueEnvelope(stored) && stored.kind === "empty";
+  }
+  emitError(operation, context) {
+    this.logger.error?.(operation, context);
+    if (this.listenerCount("error") > 0) {
+      this.emit("error", { operation, ...context });
+    }
+  }
+  serializeKeyPart(value) {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      return String(value);
+    }
+    return JSON.stringify(this.normalizeForSerialization(value));
+  }
+  isCacheSnapshotEntries(value) {
+    return Array.isArray(value) && value.every((entry) => {
+      if (!entry || typeof entry !== "object") {
+        return false;
+      }
+      const candidate = entry;
+      return typeof candidate.key === "string";
+    });
+  }
+  normalizeForSerialization(value) {
+    if (Array.isArray(value)) {
+      return value.map((entry) => this.normalizeForSerialization(entry));
+    }
+    if (value && typeof value === "object") {
+      return Object.keys(value).sort().reduce((normalized, key) => {
+        normalized[key] = this.normalizeForSerialization(value[key]);
+        return normalized;
+      }, {});
+    }
+    return value;
+  }
 };
 
 // src/invalidation/RedisInvalidationBus.ts
@@ -643,19 +1481,27 @@ var RedisInvalidationBus = class {
   channel;
   publisher;
   subscriber;
+  activeListener;
   constructor(options) {
     this.publisher = options.publisher;
     this.subscriber = options.subscriber ?? options.publisher.duplicate();
     this.channel = options.channel ?? "layercache:invalidation";
   }
   async subscribe(handler) {
-    const listener = async (_channel, payload) => {
-      const message = JSON.parse(payload);
-      await handler(message);
+    if (this.activeListener) {
+      throw new Error("RedisInvalidationBus already has an active subscription.");
+    }
+    const listener = (_channel, payload) => {
+      void this.handleMessage(payload, handler);
     };
+    this.activeListener = listener;
     this.subscriber.on("message", listener);
     await this.subscriber.subscribe(this.channel);
     return async () => {
+      if (this.activeListener !== listener) {
+        return;
+      }
+      this.activeListener = void 0;
       this.subscriber.off("message", listener);
       await this.subscriber.unsubscribe(this.channel);
     };
@@ -663,109 +1509,130 @@ var RedisInvalidationBus = class {
   async publish(message) {
     await this.publisher.publish(this.channel, JSON.stringify(message));
   }
-};
-
-// src/invalidation/RedisTagIndex.ts
-var RedisTagIndex = class {
-  client;
-  prefix;
-  scanCount;
-  constructor(options) {
-    this.client = options.client;
-    this.prefix = options.prefix ?? "layercache:tag-index";
-    this.scanCount = options.scanCount ?? 100;
-  }
-  async touch(key) {
-    await this.client.sadd(this.knownKeysKey(), key);
-  }
-  async track(key, tags) {
-    const keyTagsKey = this.keyTagsKey(key);
-    const existingTags = await this.client.smembers(keyTagsKey);
-    const pipeline = this.client.pipeline();
-    pipeline.sadd(this.knownKeysKey(), key);
-    for (const tag of existingTags) {
-      pipeline.srem(this.tagKeysKey(tag), key);
-    }
-    pipeline.del(keyTagsKey);
-    if (tags.length > 0) {
-      pipeline.sadd(keyTagsKey, ...tags);
-      for (const tag of new Set(tags)) {
-        pipeline.sadd(this.tagKeysKey(tag), key);
+  async handleMessage(payload, handler) {
+    let message;
+    try {
+      const parsed = JSON.parse(payload);
+      if (!this.isInvalidationMessage(parsed)) {
+        throw new Error("Invalid invalidation payload shape.");
       }
+      message = parsed;
+    } catch (error) {
+      this.reportError("invalid invalidation payload", error);
+      return;
     }
-    await pipeline.exec();
-  }
-  async remove(key) {
-    const keyTagsKey = this.keyTagsKey(key);
-    const existingTags = await this.client.smembers(keyTagsKey);
-    const pipeline = this.client.pipeline();
-    pipeline.srem(this.knownKeysKey(), key);
-    pipeline.del(keyTagsKey);
-    for (const tag of existingTags) {
-      pipeline.srem(this.tagKeysKey(tag), key);
+    try {
+      await handler(message);
+    } catch (error) {
+      this.reportError("invalidation handler failed", error);
     }
-    await pipeline.exec();
-  }
-  async keysForTag(tag) {
-    return this.client.smembers(this.tagKeysKey(tag));
-  }
-  async matchPattern(pattern) {
-    const matches = [];
-    let cursor = "0";
-    do {
-      const [nextCursor, keys] = await this.client.sscan(
-        this.knownKeysKey(),
-        cursor,
-        "MATCH",
-        pattern,
-        "COUNT",
-        this.scanCount
-      );
-      cursor = nextCursor;
-      matches.push(...keys.filter((key) => PatternMatcher.matches(pattern, key)));
-    } while (cursor !== "0");
-    return matches;
   }
-  async clear() {
-    const indexKeys = await this.scanIndexKeys();
-    if (indexKeys.length === 0) {
-      return;
+  isInvalidationMessage(value) {
+    if (!value || typeof value !== "object") {
+      return false;
     }
-    await this.client.del(...indexKeys);
-  }
-  async scanIndexKeys() {
-    const matches = [];
-    let cursor = "0";
-    const pattern = `${this.prefix}:*`;
-    do {
-      const [nextCursor, keys] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount);
-      cursor = nextCursor;
-      matches.push(...keys);
-    } while (cursor !== "0");
-    return matches;
-  }
-  knownKeysKey() {
-    return `${this.prefix}:keys`;
-  }
-  keyTagsKey(key) {
-    return `${this.prefix}:key:${encodeURIComponent(key)}`;
+    const candidate = value;
+    const validScope = candidate.scope === "key" || candidate.scope === "keys" || candidate.scope === "clear";
+    const validOperation = candidate.operation === void 0 || candidate.operation === "write" || candidate.operation === "delete" || candidate.operation === "invalidate" || candidate.operation === "clear";
+    const validKeys = candidate.keys === void 0 || Array.isArray(candidate.keys) && candidate.keys.every((key) => typeof key === "string");
+    return validScope && typeof candidate.sourceId === "string" && candidate.sourceId.length > 0 && validOperation && validKeys;
   }
-  tagKeysKey(tag) {
-    return `${this.prefix}:tag:${encodeURIComponent(tag)}`;
+  reportError(message, error) {
+    console.error(`[layercache] ${message}`, error);
   }
 };
 
+// src/http/createCacheStatsHandler.ts
+function createCacheStatsHandler(cache) {
+  return async (_request, response) => {
+    response.statusCode = 200;
+    response.setHeader?.("content-type", "application/json; charset=utf-8");
+    response.end(JSON.stringify(cache.getStats(), null, 2));
+  };
+}
+
+// src/decorators/createCachedMethodDecorator.ts
+function createCachedMethodDecorator(options) {
+  const wrappedByInstance = /* @__PURE__ */ new WeakMap();
+  return ((_, propertyKey, descriptor) => {
+    const original = descriptor.value;
+    if (typeof original !== "function") {
+      throw new Error("createCachedMethodDecorator can only be applied to methods.");
+    }
+    descriptor.value = async function(...args) {
+      const instance = this;
+      let wrapped = wrappedByInstance.get(instance);
+      if (!wrapped) {
+        const cache = options.cache(instance);
+        wrapped = cache.wrap(
+          options.prefix ?? String(propertyKey),
+          (...methodArgs) => Promise.resolve(original.apply(instance, methodArgs)),
+          options
+        );
+        wrappedByInstance.set(instance, wrapped);
+      }
+      return wrapped(...args);
+    };
+  });
+}
+
+// src/integrations/fastify.ts
+function createFastifyLayercachePlugin(cache, options = {}) {
+  return async (fastify) => {
+    fastify.decorate("cache", cache);
+    if (options.exposeStatsRoute !== false && fastify.get) {
+      fastify.get(options.statsPath ?? "/cache/stats", async () => cache.getStats());
+    }
+  };
+}
+
+// src/integrations/graphql.ts
+function cacheGraphqlResolver(cache, prefix, resolver, options = {}) {
+  const wrapped = cache.wrap(prefix, resolver, {
+    ...options,
+    keyResolver: options.keyResolver
+  });
+  return (...args) => wrapped(...args);
+}
+
+// src/integrations/trpc.ts
+function createTrpcCacheMiddleware(cache, prefix, options = {}) {
+  return async (context) => {
+    const key = options.keyResolver ? `${prefix}:${options.keyResolver(context.rawInput, context.path, context.type)}` : `${prefix}:${context.path ?? "procedure"}:${JSON.stringify(context.rawInput ?? null)}`;
+    let didFetch = false;
+    let fetchedResult = null;
+    const cached = await cache.get(
+      key,
+      async () => {
+        didFetch = true;
+        fetchedResult = await context.next();
+        return fetchedResult;
+      },
+      options
+    );
+    if (cached !== null) {
+      return cached;
+    }
+    if (didFetch) {
+      return fetchedResult;
+    }
+    return context.next();
+  };
+}
+
 // 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);
@@ -780,8 +1647,13 @@ var MemoryLayer = class {
       this.entries.delete(key);
       return null;
     }
-    this.entries.delete(key);
-    this.entries.set(key, entry);
+    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) {
@@ -795,15 +1667,42 @@ var MemoryLayer = class {
     this.entries.delete(key);
     this.entries.set(key, {
       value,
-      expiresAt: ttl && ttl > 0 ? Date.now() + ttl * 1e3 : null
+      expiresAt: ttl && ttl > 0 ? Date.now() + ttl * 1e3 : null,
+      frequency: 0,
+      insertedAt: Date.now()
     });
     while (this.entries.size > this.maxSize) {
-      const oldestKey = this.entries.keys().next().value;
-      if (!oldestKey) {
-        break;
-      }
-      this.entries.delete(oldestKey);
+      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);
@@ -820,6 +1719,52 @@ var MemoryLayer = class {
     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)) {
@@ -832,6 +1777,9 @@ var MemoryLayer = class {
   }
 };
 
+// src/layers/RedisLayer.ts
+import { brotliCompressSync, brotliDecompressSync, gunzipSync, gzipSync } from "zlib";
+
 // src/serialization/JsonSerializer.ts
 var JsonSerializer = class {
   serialize(value) {
@@ -844,6 +1792,7 @@ var JsonSerializer = class {
 };
 
 // src/layers/RedisLayer.ts
+var BATCH_DELETE_SIZE = 500;
 var RedisLayer = class {
   name;
   defaultTtl;
@@ -853,6 +1802,8 @@ var RedisLayer = class {
   prefix;
   allowUnprefixedClear;
   scanCount;
+  compression;
+  compressionThreshold;
   constructor(options) {
     this.client = options.client;
     this.defaultTtl = options.ttl;
@@ -861,6 +1812,8 @@ var RedisLayer = class {
     this.prefix = options.prefix ?? "";
     this.allowUnprefixedClear = options.allowUnprefixedClear ?? false;
     this.scanCount = options.scanCount ?? 100;
+    this.compression = options.compression;
+    this.compressionThreshold = options.compressionThreshold ?? 1024;
   }
   async get(key) {
     const payload = await this.getEntry(key);
@@ -871,7 +1824,7 @@ var RedisLayer = class {
     if (payload === null) {
       return null;
     }
-    return this.serializer.deserialize(payload);
+    return this.deserializeOrDelete(key, payload);
   }
   async getMany(keys) {
     if (keys.length === 0) {
@@ -885,16 +1838,18 @@ var RedisLayer = class {
     if (results === null) {
       return keys.map(() => null);
     }
-    return results.map((result) => {
-      const [, payload] = result;
-      if (payload === null) {
-        return null;
-      }
-      return this.serializer.deserialize(payload);
-    });
+    return Promise.all(
+      results.map(async (result, index) => {
+        const [error, payload] = result;
+        if (error || payload === null || !this.isSerializablePayload(payload)) {
+          return null;
+        }
+        return this.deserializeOrDelete(keys[index] ?? "", payload);
+      })
+    );
   }
   async set(key, value, ttl = this.defaultTtl) {
-    const payload = this.serializer.serialize(value);
+    const payload = this.encodePayload(this.serializer.serialize(value));
     const normalizedKey = this.withPrefix(key);
     if (ttl && ttl > 0) {
       await this.client.set(normalizedKey, payload, "EX", ttl);
@@ -911,14 +1866,44 @@ var RedisLayer = class {
     }
     await this.client.del(...keys.map((key) => this.withPrefix(key)));
   }
-  async clear() {
-    if (!this.prefix && !this.allowUnprefixedClear) {
-      throw new Error("RedisLayer.clear() requires a prefix or allowUnprefixedClear=true to avoid deleting unrelated keys.");
+  async has(key) {
+    const exists = await this.client.exists(this.withPrefix(key));
+    return exists > 0;
+  }
+  async ttl(key) {
+    const remaining = await this.client.ttl(this.withPrefix(key));
+    if (remaining < 0) {
+      return null;
     }
+    return remaining;
+  }
+  async size() {
     const keys = await this.keys();
-    if (keys.length > 0) {
-      await this.deleteMany(keys);
+    return keys.length;
+  }
+  /**
+   * Deletes all keys matching the layer's prefix in batches to avoid
+   * loading millions of keys into memory at once.
+   */
+  async clear() {
+    if (!this.prefix && !this.allowUnprefixedClear) {
+      throw new Error(
+        "RedisLayer.clear() requires a prefix or allowUnprefixedClear=true to avoid deleting unrelated keys."
+      );
     }
+    const pattern = `${this.prefix}*`;
+    let cursor = "0";
+    do {
+      const [nextCursor, keys] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount);
+      cursor = nextCursor;
+      if (keys.length === 0) {
+        continue;
+      }
+      for (let i = 0; i < keys.length; i += BATCH_DELETE_SIZE) {
+        const batch = keys.slice(i, i + BATCH_DELETE_SIZE);
+        await this.client.del(...batch);
+      }
+    } while (cursor !== "0");
   }
   async keys() {
     const pattern = `${this.prefix}*`;
@@ -941,6 +1926,205 @@ var RedisLayer = class {
   withPrefix(key) {
     return `${this.prefix}${key}`;
   }
+  async deserializeOrDelete(key, payload) {
+    try {
+      return this.serializer.deserialize(this.decodePayload(payload));
+    } catch {
+      await this.client.del(this.withPrefix(key)).catch(() => void 0);
+      return null;
+    }
+  }
+  isSerializablePayload(payload) {
+    return typeof payload === "string" || Buffer.isBuffer(payload);
+  }
+  encodePayload(payload) {
+    if (!this.compression) {
+      return payload;
+    }
+    const source = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+    if (source.byteLength < this.compressionThreshold) {
+      return payload;
+    }
+    const header = Buffer.from(`LCZ1:${this.compression}:`);
+    const compressed = this.compression === "gzip" ? gzipSync(source) : brotliCompressSync(source);
+    return Buffer.concat([header, compressed]);
+  }
+  decodePayload(payload) {
+    if (!Buffer.isBuffer(payload)) {
+      return payload;
+    }
+    if (payload.subarray(0, 10).toString() === "LCZ1:gzip:") {
+      return gunzipSync(payload.subarray(10));
+    }
+    if (payload.subarray(0, 12).toString() === "LCZ1:brotli:") {
+      return brotliDecompressSync(payload.subarray(12));
+    }
+    return payload;
+  }
+};
+
+// src/layers/DiskLayer.ts
+import { createHash } from "crypto";
+import { promises as fs2 } from "fs";
+import { join } from "path";
+var DiskLayer = class {
+  name;
+  defaultTtl;
+  isLocal = true;
+  directory;
+  serializer;
+  constructor(options) {
+    this.directory = options.directory;
+    this.defaultTtl = options.ttl;
+    this.name = options.name ?? "disk";
+    this.serializer = options.serializer ?? new JsonSerializer();
+  }
+  async get(key) {
+    return unwrapStoredValue(await this.getEntry(key));
+  }
+  async getEntry(key) {
+    const filePath = this.keyToPath(key);
+    let raw;
+    try {
+      raw = await fs2.readFile(filePath);
+    } catch {
+      return null;
+    }
+    let entry;
+    try {
+      entry = this.serializer.deserialize(raw);
+    } catch {
+      await this.safeDelete(filePath);
+      return null;
+    }
+    if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
+      await this.safeDelete(filePath);
+      return null;
+    }
+    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);
+  }
+  async has(key) {
+    const value = await this.getEntry(key);
+    return value !== null;
+  }
+  async ttl(key) {
+    const filePath = this.keyToPath(key);
+    let raw;
+    try {
+      raw = await fs2.readFile(filePath);
+    } catch {
+      return null;
+    }
+    let entry;
+    try {
+      entry = this.serializer.deserialize(raw);
+    } catch {
+      return null;
+    }
+    if (entry.expiresAt === null) {
+      return null;
+    }
+    const remaining = Math.ceil((entry.expiresAt - Date.now()) / 1e3);
+    if (remaining <= 0) {
+      return null;
+    }
+    return remaining;
+  }
+  async delete(key) {
+    await this.safeDelete(this.keyToPath(key));
+  }
+  async deleteMany(keys) {
+    await Promise.all(keys.map((key) => this.delete(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)))
+    );
+  }
+  async keys() {
+    let entries;
+    try {
+      entries = await fs2.readdir(this.directory);
+    } catch {
+      return [];
+    }
+    return entries.filter((name) => name.endsWith(".lc")).map((name) => name.slice(0, -3));
+  }
+  async size() {
+    const keys = await this.keys();
+    return keys.length;
+  }
+  keyToPath(key) {
+    const hash = createHash("sha256").update(key).digest("hex");
+    return join(this.directory, `${hash}.lc`);
+  }
+  async safeDelete(filePath) {
+    try {
+      await fs2.unlink(filePath);
+    } catch {
+    }
+  }
+};
+
+// src/layers/MemcachedLayer.ts
+var MemcachedLayer = class {
+  name;
+  defaultTtl;
+  isLocal = false;
+  client;
+  keyPrefix;
+  constructor(options) {
+    this.client = options.client;
+    this.defaultTtl = options.ttl;
+    this.name = options.name ?? "memcached";
+    this.keyPrefix = options.keyPrefix ?? "";
+  }
+  async get(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"));
+    } catch {
+      return null;
+    }
+  }
+  async set(key, value, ttl = this.defaultTtl) {
+    const payload = JSON.stringify(value);
+    await this.client.set(this.withPrefix(key), payload, {
+      expires: ttl && ttl > 0 ? ttl : void 0
+    });
+  }
+  async delete(key) {
+    await this.client.delete(this.withPrefix(key));
+  }
+  async deleteMany(keys) {
+    await Promise.all(keys.map((key) => this.delete(key)));
+  }
+  async clear() {
+    throw new Error(
+      "MemcachedLayer.clear() is not supported. Use a key prefix and rotate it to effectively invalidate all keys."
+    );
+  }
+  withPrefix(key) {
+    return `${this.keyPrefix}${key}`;
+  }
 };
 
 // src/serialization/MsgpackSerializer.ts
@@ -984,9 +2168,79 @@ var RedisSingleFlightCoordinator = class {
     return waiter();
   }
 };
+
+// src/metrics/PrometheusExporter.ts
+function createPrometheusMetricsExporter(stacks) {
+  return () => {
+    const entries = Array.isArray(stacks) ? stacks : [{ stack: stacks, name: "default" }];
+    const lines = [];
+    lines.push("# HELP layercache_hits_total Total number of cache hits");
+    lines.push("# TYPE layercache_hits_total counter");
+    lines.push("# HELP layercache_misses_total Total number of cache misses");
+    lines.push("# TYPE layercache_misses_total counter");
+    lines.push("# HELP layercache_fetches_total Total fetcher invocations (full misses)");
+    lines.push("# TYPE layercache_fetches_total counter");
+    lines.push("# HELP layercache_sets_total Total number of cache sets");
+    lines.push("# TYPE layercache_sets_total counter");
+    lines.push("# HELP layercache_deletes_total Total number of cache deletes");
+    lines.push("# TYPE layercache_deletes_total counter");
+    lines.push("# HELP layercache_backfills_total Total number of backfill operations");
+    lines.push("# TYPE layercache_backfills_total counter");
+    lines.push("# HELP layercache_stale_hits_total Total number of stale hits served");
+    lines.push("# TYPE layercache_stale_hits_total counter");
+    lines.push("# HELP layercache_refreshes_total Background refreshes triggered");
+    lines.push("# TYPE layercache_refreshes_total counter");
+    lines.push("# HELP layercache_refresh_errors_total Background refresh errors");
+    lines.push("# TYPE layercache_refresh_errors_total counter");
+    lines.push("# HELP layercache_negative_cache_hits_total Negative cache hits");
+    lines.push("# TYPE layercache_negative_cache_hits_total counter");
+    lines.push("# HELP layercache_circuit_breaker_trips_total Circuit breaker trips");
+    lines.push("# TYPE layercache_circuit_breaker_trips_total counter");
+    lines.push("# HELP layercache_degraded_operations_total Operations run in degraded mode");
+    lines.push("# TYPE layercache_degraded_operations_total counter");
+    lines.push("# HELP layercache_hit_rate Overall cache hit rate (0-1)");
+    lines.push("# TYPE layercache_hit_rate gauge");
+    lines.push("# HELP layercache_hits_by_layer_total Hits broken down by layer");
+    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");
+    for (const { stack, name } of entries) {
+      const m = stack.getMetrics();
+      const hr = stack.getHitRate();
+      const label = `cache="${sanitizeLabel(name)}"`;
+      lines.push(`layercache_hits_total{${label}} ${m.hits}`);
+      lines.push(`layercache_misses_total{${label}} ${m.misses}`);
+      lines.push(`layercache_fetches_total{${label}} ${m.fetches}`);
+      lines.push(`layercache_sets_total{${label}} ${m.sets}`);
+      lines.push(`layercache_deletes_total{${label}} ${m.deletes}`);
+      lines.push(`layercache_backfills_total{${label}} ${m.backfills}`);
+      lines.push(`layercache_stale_hits_total{${label}} ${m.staleHits}`);
+      lines.push(`layercache_refreshes_total{${label}} ${m.refreshes}`);
+      lines.push(`layercache_refresh_errors_total{${label}} ${m.refreshErrors}`);
+      lines.push(`layercache_negative_cache_hits_total{${label}} ${m.negativeCacheHits}`);
+      lines.push(`layercache_circuit_breaker_trips_total{${label}} ${m.circuitBreakerTrips}`);
+      lines.push(`layercache_degraded_operations_total{${label}} ${m.degradedOperations}`);
+      lines.push(`layercache_hit_rate{${label}} ${hr.overall.toFixed(6)}`);
+      for (const [layerName, count] of Object.entries(m.hitsByLayer)) {
+        lines.push(`layercache_hits_by_layer_total{${label},layer="${sanitizeLabel(layerName)}"} ${count}`);
+      }
+      for (const [layerName, count] of Object.entries(m.missesByLayer)) {
+        lines.push(`layercache_misses_by_layer_total{${label},layer="${sanitizeLabel(layerName)}"} ${count}`);
+      }
+    }
+    lines.push("");
+    return lines.join("\n");
+  };
+}
+function sanitizeLabel(value) {
+  return value.replace(/["\\\n]/g, "_");
+}
 export {
+  CacheNamespace,
   CacheStack,
+  DiskLayer,
   JsonSerializer,
+  MemcachedLayer,
   MemoryLayer,
   MsgpackSerializer,
   PatternMatcher,
@@ -995,5 +2249,11 @@ export {
   RedisSingleFlightCoordinator,
   RedisTagIndex,
   StampedeGuard,
-  TagIndex
+  TagIndex,
+  cacheGraphqlResolver,
+  createCacheStatsHandler,
+  createCachedMethodDecorator,
+  createFastifyLayercachePlugin,
+  createPrometheusMetricsExporter,
+  createTrpcCacheMiddleware
 };