layercache 1.0.0 → 1.0.2

package/packages/nestjs/dist/index.cjs

@@ -30,6 +30,7 @@ var index_exports = {};
 __export(index_exports, {
   CACHE_STACK: () => CACHE_STACK,
   CacheStackModule: () => CacheStackModule,
+  Cacheable: () => Cacheable,
   InjectCacheStack: () => InjectCacheStack
 });
 module.exports = __toCommonJS(index_exports);
@@ -37,11 +38,199 @@ module.exports = __toCommonJS(index_exports);
 // src/constants.ts
 var CACHE_STACK = /* @__PURE__ */ Symbol("CACHE_STACK");
 
+// ../../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/decorators.ts
+function Cacheable(options) {
+  return createCachedMethodDecorator(options);
+}
+
 // src/module.ts
 var import_common = require("@nestjs/common");
 
 // ../../src/CacheStack.ts
 var import_node_crypto = require("crypto");
+var import_node_fs = require("fs");
+var import_node_events = require("events");
+
+// ../../src/internal/StoredValue.ts
+function isStoredValueEnvelope(value) {
+  return typeof value === "object" && value !== null && "__layercache" in value && value.__layercache === 1 && "kind" in value;
+}
+function createStoredValueEnvelope(options) {
+  const now = options.now ?? Date.now();
+  const freshTtlSeconds = normalizePositiveSeconds(options.freshTtlSeconds);
+  const staleWhileRevalidateSeconds = normalizePositiveSeconds(options.staleWhileRevalidateSeconds);
+  const staleIfErrorSeconds = normalizePositiveSeconds(options.staleIfErrorSeconds);
+  const freshUntil = freshTtlSeconds ? now + freshTtlSeconds * 1e3 : null;
+  const staleUntil = freshUntil && staleWhileRevalidateSeconds ? freshUntil + staleWhileRevalidateSeconds * 1e3 : null;
+  const errorUntil = freshUntil && staleIfErrorSeconds ? freshUntil + staleIfErrorSeconds * 1e3 : null;
+  return {
+    __layercache: 1,
+    kind: options.kind,
+    value: options.value,
+    freshUntil,
+    staleUntil,
+    errorUntil,
+    freshTtlSeconds: freshTtlSeconds ?? null,
+    staleWhileRevalidateSeconds: staleWhileRevalidateSeconds ?? null,
+    staleIfErrorSeconds: staleIfErrorSeconds ?? null
+  };
+}
+function resolveStoredValue(stored, now = Date.now()) {
+  if (!isStoredValueEnvelope(stored)) {
+    return { state: "fresh", value: stored, stored };
+  }
+  if (stored.freshUntil === null || stored.freshUntil > now) {
+    return { state: "fresh", value: unwrapStoredValue(stored), stored, envelope: stored };
+  }
+  if (stored.staleUntil !== null && stored.staleUntil > now) {
+    return { state: "stale-while-revalidate", value: unwrapStoredValue(stored), stored, envelope: stored };
+  }
+  if (stored.errorUntil !== null && stored.errorUntil > now) {
+    return { state: "stale-if-error", value: unwrapStoredValue(stored), stored, envelope: stored };
+  }
+  return { state: "expired", value: null, stored, envelope: stored };
+}
+function unwrapStoredValue(stored) {
+  if (!isStoredValueEnvelope(stored)) {
+    return stored;
+  }
+  if (stored.kind === "empty") {
+    return null;
+  }
+  return stored.value ?? null;
+}
+function remainingStoredTtlSeconds(stored, now = Date.now()) {
+  if (!isStoredValueEnvelope(stored)) {
+    return void 0;
+  }
+  const expiry = maxExpiry(stored);
+  if (expiry === null) {
+    return void 0;
+  }
+  const remainingMs = expiry - now;
+  if (remainingMs <= 0) {
+    return 1;
+  }
+  return Math.max(1, Math.ceil(remainingMs / 1e3));
+}
+function remainingFreshTtlSeconds(stored, now = Date.now()) {
+  if (!isStoredValueEnvelope(stored) || stored.freshUntil === null) {
+    return void 0;
+  }
+  const remainingMs = stored.freshUntil - now;
+  if (remainingMs <= 0) {
+    return 0;
+  }
+  return Math.max(1, Math.ceil(remainingMs / 1e3));
+}
+function refreshStoredEnvelope(stored, now = Date.now()) {
+  if (!isStoredValueEnvelope(stored)) {
+    return stored;
+  }
+  return createStoredValueEnvelope({
+    kind: stored.kind,
+    value: stored.value,
+    freshTtlSeconds: stored.freshTtlSeconds ?? void 0,
+    staleWhileRevalidateSeconds: stored.staleWhileRevalidateSeconds ?? void 0,
+    staleIfErrorSeconds: stored.staleIfErrorSeconds ?? void 0,
+    now
+  });
+}
+function maxExpiry(stored) {
+  const values = [stored.freshUntil, stored.staleUntil, stored.errorUntil].filter(
+    (value) => value !== null
+  );
+  if (values.length === 0) {
+    return null;
+  }
+  return Math.max(...values);
+}
+function normalizePositiveSeconds(value) {
+  if (!value || value <= 0) {
+    return void 0;
+  }
+  return value;
+}
+
+// ../../src/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 set(key, value, options) {
+    await this.cache.set(this.qualify(key), value, options);
+  }
+  async delete(key) {
+    await this.cache.delete(this.qualify(key));
+  }
+  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();
+  }
+  qualify(key) {
+    return `${this.prefix}:${key}`;
+  }
+};
 
 // ../../src/invalidation/PatternMatcher.ts
 var PatternMatcher = class {
@@ -289,26 +478,33 @@ var Mutex = class {
 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 MAX_CACHE_KEY_LENGTH = 1024;
 var EMPTY_METRICS = () => ({
   hits: 0,
   misses: 0,
@@ -316,7 +512,17 @@ var EMPTY_METRICS = () => ({
   sets: 0,
   deletes: 0,
   backfills: 0,
-  invalidations: 0
+  invalidations: 0,
+  staleHits: 0,
+  refreshes: 0,
+  refreshErrors: 0,
+  writeFailures: 0,
+  singleFlightWaits: 0,
+  negativeCacheHits: 0,
+  circuitBreakerTrips: 0,
+  degradedOperations: 0,
+  hitsByLayer: {},
+  missesByLayer: {}
 });
 var DebugLogger = class {
   enabled;
@@ -324,21 +530,35 @@ var DebugLogger = class {
     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(`[cachestack] ${message}${suffix}`);
+    console[level](`[layercache] ${message}${suffix}`);
   }
 };
-var CacheStack = class {
+var CacheStack = class extends import_node_events.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.");
     }
-    const debugEnv = process.env.DEBUG?.split(",").includes("cachestack:debug") ?? false;
+    this.validateConfiguration();
+    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.startup = this.initialize();
@@ -352,68 +572,193 @@ var CacheStack = class {
   unsubscribeInvalidation;
   logger;
   tagIndex;
+  backgroundRefreshes = /* @__PURE__ */ new Map();
+  accessProfiles = /* @__PURE__ */ new Map();
+  layerDegradedUntil = /* @__PURE__ */ new Map();
+  circuitBreakers = /* @__PURE__ */ new Map();
+  isDisconnecting = false;
+  disconnectPromise;
   async get(key, fetcher, options) {
+    const normalizedKey = this.validateCacheKey(key);
+    this.validateWriteOptions(options);
     await this.startup;
-    const hit = await this.getFromLayers(key, options);
+    const hit = await this.readFromLayers(normalizedKey, options, "allow-stale");
     if (hit.found) {
-      this.metrics.hits += 1;
-      return hit.value;
+      this.recordAccess(normalizedKey);
+      if (this.isNegativeStoredValue(hit.stored)) {
+        this.metrics.negativeCacheHits += 1;
+      }
+      if (hit.state === "fresh") {
+        this.metrics.hits += 1;
+        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.emit("stale-serve", { key: normalizedKey, state: hit.state, layer: hit.layerName });
+        if (fetcher) {
+          this.scheduleBackgroundRefresh(normalizedKey, fetcher, options);
+        }
+        return hit.value;
+      }
+      if (!fetcher) {
+        this.metrics.hits += 1;
+        this.metrics.staleHits += 1;
+        this.emit("stale-serve", { key: normalizedKey, state: hit.state, layer: hit.layerName });
+        return hit.value;
+      }
+      try {
+        return await this.fetchWithGuards(normalizedKey, fetcher, options);
+      } catch (error) {
+        this.metrics.staleHits += 1;
+        this.metrics.refreshErrors += 1;
+        this.logger.debug?.("stale-if-error", { key: normalizedKey, error: this.formatError(error) });
+        return hit.value;
+      }
     }
     this.metrics.misses += 1;
     if (!fetcher) {
       return null;
     }
-    const runFetch = async () => {
-      const secondHit = await this.getFromLayers(key, options);
-      if (secondHit.found) {
-        this.metrics.hits += 1;
-        return secondHit.value;
-      }
-      this.metrics.fetches += 1;
-      const fetched = await fetcher();
-      if (fetched === null || fetched === void 0) {
-        return null;
-      }
-      await this.set(key, fetched, options);
-      return fetched;
-    };
-    if (this.options.stampedePrevention === false) {
-      return runFetch();
-    }
-    return this.stampedeGuard.execute(key, runFetch);
+    return this.fetchWithGuards(normalizedKey, fetcher, options);
   }
   async set(key, value, options) {
+    const normalizedKey = this.validateCacheKey(key);
+    this.validateWriteOptions(options);
     await this.startup;
-    await this.setAcrossLayers(key, value, options);
-    if (options?.tags) {
-      await this.tagIndex.track(key, options.tags);
-    } else {
-      await this.tagIndex.touch(key);
-    }
-    this.metrics.sets += 1;
-    this.logger.debug("set", { key, tags: options?.tags });
-    if (this.options.publishSetInvalidation !== false) {
-      await this.publishInvalidation({ scope: "key", keys: [key], sourceId: this.instanceId, operation: "write" });
-    }
+    await this.storeEntry(normalizedKey, "value", value, options);
   }
   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.accessProfiles.clear();
     this.metrics.invalidations += 1;
-    this.logger.debug("clear");
+    this.logger.debug?.("clear");
     await this.publishInvalidation({ scope: "clear", sourceId: this.instanceId, operation: "clear" });
   }
   async mget(entries) {
-    return Promise.all(entries.map((entry) => this.get(entry.key, entry.fetch, entry.options)));
+    if (entries.length === 0) {
+      return [];
+    }
+    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) {
+      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 = /* @__PURE__ */ new Set();
+    const indexesByKey = /* @__PURE__ */ new Map();
+    const resultsByKey = /* @__PURE__ */ new Map();
+    for (let index = 0; index < normalizedEntries.length; index += 1) {
+      const key = normalizedEntries[index].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];
+      const keys = [...pending];
+      if (keys.length === 0) {
+        break;
+      }
+      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 key = keys[offset];
+        const stored = values[offset];
+        if (stored === null) {
+          continue;
+        }
+        const resolved = resolveStoredValue(stored);
+        if (resolved.state === "expired") {
+          await layer.delete(key);
+          continue;
+        }
+        await this.tagIndex.touch(key);
+        await this.backfill(key, stored, layerIndex - 1);
+        resultsByKey.set(key, resolved.value);
+        pending.delete(key);
+        this.metrics.hits += indexesByKey.get(key)?.length ?? 1;
+      }
+    }
+    if (pending.size > 0) {
+      for (const key of pending) {
+        await this.tagIndex.remove(key);
+        this.metrics.misses += indexesByKey.get(key)?.length ?? 1;
+      }
+    }
+    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 queue = [...entries].sort((left, right) => (right.priority ?? 0) - (left.priority ?? 0));
+    const workers = Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+      while (queue.length > 0) {
+        const entry = queue.shift();
+        if (!entry) {
+          return;
+        }
+        try {
+          await this.get(entry.key, entry.fetcher, entry.options);
+          this.emit("warm", { key: entry.key });
+        } catch (error) {
+          this.emitError("warm", { key: entry.key, error: this.formatError(error) });
+          if (!options.continueOnError) {
+            throw error;
+          }
+        }
+      }
+    });
+    await Promise.all(workers);
+  }
+  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);
+    };
+  }
+  namespace(prefix) {
+    return new CacheNamespace(this, prefix);
   }
   async invalidateByTag(tag) {
     await this.startup;
@@ -430,12 +775,74 @@ var CacheStack = class {
   getMetrics() {
     return { ...this.metrics };
   }
+  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());
   }
-  async disconnect() {
+  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.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 import_node_fs.promises.writeFile(filePath, JSON.stringify(snapshot, null, 2), "utf8");
+  }
+  async restoreFromFile(filePath) {
+    const raw = await import_node_fs.promises.readFile(filePath, "utf8");
+    const snapshot = JSON.parse(raw);
+    if (!this.isCacheSnapshotEntries(snapshot)) {
+      throw new Error("Invalid snapshot file: expected CacheSnapshotEntry[]");
+    }
+    await this.importState(snapshot);
+  }
+  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) {
@@ -445,66 +852,286 @@ var CacheStack = class {
       await this.handleInvalidationMessage(message);
     });
   }
-  async getFromLayers(key, options) {
+  async fetchWithGuards(key, fetcher, options) {
+    const fetchTask = async () => {
+      const secondHit = await this.readFromLayers(key, options, "fresh-only");
+      if (secondHit.found) {
+        this.metrics.hits += 1;
+        return secondHit.value;
+      }
+      return this.fetchAndPopulate(key, fetcher, options);
+    };
+    const singleFlightTask = async () => {
+      if (!this.options.singleFlightCoordinator) {
+        return fetchTask();
+      }
+      return this.options.singleFlightCoordinator.execute(
+        key,
+        this.resolveSingleFlightOptions(),
+        fetchTask,
+        () => this.waitForFreshValue(key, fetcher, options)
+      );
+    };
+    if (this.options.stampedePrevention === false) {
+      return singleFlightTask();
+    }
+    return this.stampedeGuard.execute(key, singleFlightTask);
+  }
+  async waitForFreshValue(key, fetcher, options) {
+    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.emit("stampede-dedupe", { key });
+    while (Date.now() < deadline) {
+      const hit = await this.readFromLayers(key, options, "fresh-only");
+      if (hit.found) {
+        this.metrics.hits += 1;
+        return hit.value;
+      }
+      await this.sleep(pollIntervalMs);
+    }
+    return this.fetchAndPopulate(key, fetcher, options);
+  }
+  async fetchAndPopulate(key, fetcher, options) {
+    this.assertCircuitClosed(key, options?.circuitBreaker ?? this.options.circuitBreaker);
+    this.metrics.fetches += 1;
+    let fetched;
+    try {
+      fetched = await fetcher();
+      this.resetCircuitBreaker(key);
+    } 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;
+      }
+      await this.storeEntry(key, "empty", null, options);
+      return null;
+    }
+    await this.storeEntry(key, "value", fetched, options);
+    return fetched;
+  }
+  async storeEntry(key, kind, value, options) {
+    await this.writeAcrossLayers(key, kind, value, options);
+    if (options?.tags) {
+      await this.tagIndex.track(key, options.tags);
+    } else {
+      await this.tagIndex.touch(key);
+    }
+    this.metrics.sets += 1;
+    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" });
+    }
+  }
+  async readFromLayers(key, options, mode) {
+    let sawRetainableValue = false;
     for (let index = 0; index < this.layers.length; index += 1) {
       const layer = this.layers[index];
-      const value = await layer.get(key);
-      if (value === null) {
+      const stored = await this.readLayerEntry(layer, key);
+      if (stored === null) {
+        this.incrementMetricMap(this.metrics.missesByLayer, layer.name);
+        continue;
+      }
+      const resolved = resolveStoredValue(stored);
+      if (resolved.state === "expired") {
+        await layer.delete(key);
+        continue;
+      }
+      sawRetainableValue = true;
+      if (mode === "fresh-only" && resolved.state !== "fresh") {
         continue;
       }
       await this.tagIndex.touch(key);
-      await this.backfill(key, value, index - 1, options);
-      this.logger.debug("hit", { key, layer: layer.name });
-      return { found: true, value };
+      await this.backfill(key, stored, index - 1, options);
+      this.incrementMetricMap(this.metrics.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);
     }
-    await this.tagIndex.remove(key);
-    this.logger.debug("miss", { key });
-    return { found: false, value: null };
+    this.logger.debug?.("miss", { key, mode });
+    this.emit("miss", { key, mode });
+    return { found: false, value: null, stored: null, state: "miss" };
   }
-  async backfill(key, value, upToIndex, options) {
+  async readLayerEntry(layer, key) {
+    if (this.shouldSkipLayer(layer)) {
+      return null;
+    }
+    if (layer.getEntry) {
+      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);
+    }
+  }
+  async backfill(key, stored, upToIndex, options) {
     if (upToIndex < 0) {
       return;
     }
     for (let index = 0; index <= upToIndex; index += 1) {
       const layer = this.layers[index];
-      await layer.set(key, value, this.resolveTtl(layer.name, layer.defaultTtl, options?.ttl));
+      if (this.shouldSkipLayer(layer)) {
+        continue;
+      }
+      const ttl = remainingStoredTtlSeconds(stored) ?? this.resolveLayerSeconds(layer.name, options?.ttl, void 0, layer.defaultTtl);
+      try {
+        await layer.set(key, stored, ttl);
+      } catch (error) {
+        await this.handleLayerFailure(layer, "backfill", error);
+        continue;
+      }
       this.metrics.backfills += 1;
-      this.logger.debug("backfill", { key, layer: layer.name });
+      this.logger.debug?.("backfill", { key, layer: layer.name });
+      this.emit("backfill", { key, layer: layer.name });
     }
   }
-  async setAcrossLayers(key, value, options) {
-    await Promise.all(
-      this.layers.map((layer) => layer.set(key, value, this.resolveTtl(layer.name, layer.defaultTtl, options?.ttl)))
+  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);
+      }
+    });
+    await this.executeLayerOperations(operations, { key, action: kind === "empty" ? "negative-set" : "set" });
+  }
+  async executeLayerOperations(operations, context) {
+    if (this.options.writePolicy !== "best-effort") {
+      await Promise.all(operations.map((operation) => operation()));
+      return;
+    }
+    const results = await Promise.allSettled(operations.map((operation) => operation()));
+    const failures = results.filter((result) => result.status === "rejected");
+    if (failures.length === 0) {
+      return;
+    }
+    this.metrics.writeFailures += failures.length;
+    this.logger.debug?.("write-failure", {
+      ...context,
+      failures: failures.map((failure) => this.formatError(failure.reason))
+    });
+    if (failures.length === operations.length) {
+      throw new AggregateError(
+        failures.map((failure) => failure.reason),
+        `${context.action} failed for every cache layer`
+      );
+    }
+  }
+  resolveFreshTtl(key, 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 adaptiveTtl = this.applyAdaptiveTtl(
+      key,
+      layerName,
+      baseTtl,
+      options?.adaptiveTtl ?? this.options.adaptiveTtl
     );
+    const jitter = this.resolveLayerSeconds(layerName, options?.ttlJitter, this.options.ttlJitter);
+    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;
+  }
+  readLayerNumber(layerName, value) {
+    if (typeof value === "number") {
+      return value;
+    }
+    return value[layerName];
   }
-  resolveTtl(layerName, fallbackTtl, ttlOverride) {
-    if (ttlOverride === void 0) {
-      return fallbackTtl;
+  applyJitter(ttl, jitter) {
+    if (!ttl || ttl <= 0 || !jitter || jitter <= 0) {
+      return ttl;
     }
-    if (typeof ttlOverride === "number") {
-      return ttlOverride;
+    const delta = (Math.random() * 2 - 1) * jitter;
+    return Math.max(1, Math.round(ttl + delta));
+  }
+  shouldNegativeCache(options) {
+    return options?.negativeCache ?? this.options.negativeCaching ?? false;
+  }
+  scheduleBackgroundRefresh(key, fetcher, options) {
+    if (this.isDisconnecting || this.backgroundRefreshes.has(key)) {
+      return;
     }
-    return ttlOverride[layerName] ?? fallbackTtl;
+    const refresh = (async () => {
+      this.metrics.refreshes += 1;
+      try {
+        await this.fetchWithGuards(key, fetcher, options);
+      } catch (error) {
+        this.metrics.refreshErrors += 1;
+        this.logger.debug?.("refresh-error", { key, error: this.formatError(error) });
+      } finally {
+        this.backgroundRefreshes.delete(key);
+      }
+    })();
+    this.backgroundRefreshes.set(key, refresh);
+  }
+  resolveSingleFlightOptions() {
+    return {
+      leaseMs: this.options.singleFlightLeaseMs ?? DEFAULT_SINGLE_FLIGHT_LEASE_MS,
+      waitTimeoutMs: this.options.singleFlightTimeoutMs ?? DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS,
+      pollIntervalMs: this.options.singleFlightPollMs ?? DEFAULT_SINGLE_FLIGHT_POLL_MS
+    };
   }
   async deleteKeys(keys) {
     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.accessProfiles.delete(key);
     }
     this.metrics.deletes += keys.length;
     this.metrics.invalidations += 1;
-    this.logger.debug("delete", { keys });
+    this.logger.debug?.("delete", { keys });
+    this.emit("delete", { keys });
   }
   async publishInvalidation(message) {
     if (!this.options.invalidationBus) {
@@ -523,23 +1150,277 @@ var CacheStack = class {
     if (message.scope === "clear") {
       await Promise.all(localLayers.map((layer) => layer.clear()));
       await this.tagIndex.clear();
+      this.accessProfiles.clear();
       return;
     }
     const keys = message.keys ?? [];
+    await this.deleteKeysFromLayers(localLayers, keys);
+    if (message.operation !== "write") {
+      for (const key of keys) {
+        await this.tagIndex.remove(key);
+        this.accessProfiles.delete(key);
+      }
+    }
+  }
+  formatError(error) {
+    if (error instanceof Error) {
+      return error.message;
+    }
+    return String(error);
+  }
+  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(
-      localLayers.map(async (layer) => {
+      layers.map(async (layer) => {
+        if (this.shouldSkipLayer(layer)) {
+          return;
+        }
         if (layer.deleteMany) {
-          await layer.deleteMany(keys);
+          try {
+            await layer.deleteMany(keys);
+          } catch (error) {
+            await this.handleLayerFailure(layer, "delete", error);
+          }
           return;
         }
-        await Promise.all(keys.map((key) => layer.delete(key)));
+        await Promise.all(keys.map(async (key) => {
+          try {
+            await layer.delete(key);
+          } catch (error) {
+            await this.handleLayerFailure(layer, "delete", error);
+          }
+        }));
       })
     );
-    if (message.operation !== "write") {
-      for (const key of keys) {
-        await this.tagIndex.remove(key);
+  }
+  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 (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);
+    }
+  }
+  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);
+  }
+  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);
+  }
+  incrementMetricMap(target, key) {
+    target[key] = (target[key] ?? 0) + 1;
+  }
+  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.metrics.degradedOperations += 1;
+    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);
+  }
+  assertCircuitClosed(key, options) {
+    const state = this.circuitBreakers.get(key);
+    if (!state?.openUntil) {
+      return;
+    }
+    if (state.openUntil <= Date.now()) {
+      state.openUntil = null;
+      state.failures = 0;
+      this.circuitBreakers.set(key, state);
+      return;
+    }
+    this.emitError("circuit-breaker-open", { key, openUntil: state.openUntil });
+    throw new Error(`Circuit breaker is open for key "${key}".`);
+  }
+  recordCircuitFailure(key, options, error) {
+    if (!options) {
+      return;
+    }
+    const failureThreshold = options.failureThreshold ?? 3;
+    const cooldownMs = options.cooldownMs ?? 3e4;
+    const state = this.circuitBreakers.get(key) ?? { failures: 0, openUntil: null };
+    state.failures += 1;
+    if (state.failures >= failureThreshold) {
+      state.openUntil = Date.now() + cooldownMs;
+      this.metrics.circuitBreakerTrips += 1;
+    }
+    this.circuitBreakers.set(key, state);
+    this.emitError("fetch", { key, error: this.formatError(error), failures: state.failures });
+  }
+  resetCircuitBreaker(key) {
+    this.circuitBreakers.delete(key);
+  }
+  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;
   }
 };
 
@@ -567,5 +1448,6 @@ CacheStackModule = __decorateClass([
 0 && (module.exports = {
   CACHE_STACK,
   CacheStackModule,
+  Cacheable,
   InjectCacheStack
 });