layercache 1.0.2 → 1.1.0

package/packages/nestjs/dist/index.js

@@ -47,8 +47,229 @@ import { Global, Inject, Module } from "@nestjs/common";
 
 // ../../src/CacheStack.ts
 import { randomUUID } from "crypto";
-import { promises as fs } from "fs";
 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) {
@@ -151,67 +372,129 @@ function normalizePositiveSeconds(value) {
   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));
+// ../../src/internal/TtlResolver.ts
+var DEFAULT_NEGATIVE_TTL_SECONDS = 60;
+var TtlResolver = class {
+  accessProfiles = /* @__PURE__ */ new Map();
+  maxProfileEntries;
+  constructor(options) {
+    this.maxProfileEntries = options.maxProfileEntries;
   }
-  async clear() {
-    await this.cache.invalidateByPattern(`${this.prefix}:*`);
+  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();
   }
-  async mget(entries) {
-    return this.cache.mget(entries.map((entry) => ({
-      ...entry,
-      key: this.qualify(entry.key)
-    })));
+  deleteProfile(key) {
+    this.accessProfiles.delete(key);
   }
-  async mset(entries) {
-    await this.cache.mset(entries.map((entry) => ({
-      ...entry,
-      key: this.qualify(entry.key)
-    })));
+  clearProfiles() {
+    this.accessProfiles.clear();
   }
-  async invalidateByTag(tag) {
-    await this.cache.invalidateByTag(tag);
+  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);
   }
-  async invalidateByPattern(pattern) {
-    await this.cache.invalidateByPattern(this.qualify(pattern));
+  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;
   }
-  wrap(keyPrefix, fetcher, options) {
-    return this.cache.wrap(`${this.prefix}:${keyPrefix}`, 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);
   }
-  warm(entries, options) {
-    return this.cache.warm(entries.map((entry) => ({
-      ...entry,
-      key: this.qualify(entry.key)
-    })), options);
+  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));
   }
-  getMetrics() {
-    return this.cache.getMetrics();
+  readLayerNumber(layerName, value) {
+    if (typeof value === "number") {
+      return value;
+    }
+    return value[layerName];
   }
-  qualify(key) {
-    return `${this.prefix}:${key}`;
+  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;
+    }
   }
 };
 
 // ../../src/invalidation/PatternMatcher.ts
-var PatternMatcher = class {
+var PatternMatcher = class _PatternMatcher {
+  /**
+   * Tests whether a glob-style pattern matches a value.
+   * Supports `*` (any sequence of characters) and `?` (any single character).
+   * Uses a linear-time algorithm to avoid ReDoS vulnerabilities.
+   */
   static matches(pattern, value) {
-    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
-    const regex = new RegExp(`^${escaped.replace(/\*/g, ".*").replace(/\?/g, ".")}$`);
-    return regex.test(value);
+    return _PatternMatcher.matchLinear(pattern, value);
+  }
+  /**
+   * Linear-time glob matching using dynamic programming.
+   * Avoids catastrophic backtracking that RegExp-based glob matching can cause.
+   */
+  static matchLinear(pattern, value) {
+    const m = pattern.length;
+    const n = value.length;
+    const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(false));
+    dp[0][0] = true;
+    for (let i = 1; i <= m; i++) {
+      if (pattern[i - 1] === "*") {
+        dp[i][0] = dp[i - 1]?.[0];
+      }
+    }
+    for (let i = 1; i <= m; i++) {
+      for (let j = 1; j <= n; j++) {
+        const pc = pattern[i - 1];
+        if (pc === "*") {
+          dp[i][j] = dp[i - 1]?.[j] || dp[i]?.[j - 1];
+        } else if (pc === "?" || pc === value[j - 1]) {
+          dp[i][j] = dp[i - 1]?.[j - 1];
+        }
+      }
+    }
+    return dp[m]?.[n];
   }
 };
 
@@ -474,30 +757,11 @@ var StampedeGuard = class {
 };
 
 // ../../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,
-  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: {}
-});
+var DEFAULT_MAX_PROFILE_ENTRIES = 1e5;
 var DebugLogger = class {
   enabled;
   constructor(enabled) {
@@ -532,6 +796,14 @@ var CacheStack = class extends EventEmitter {
       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();
@@ -540,36 +812,42 @@ var CacheStack = class extends EventEmitter {
   layers;
   options;
   stampedeGuard = new StampedeGuard();
-  metrics = EMPTY_METRICS();
+  metricsCollector = new MetricsCollector();
   instanceId = randomUUID();
   startup;
   unsubscribeInvalidation;
   logger;
   tagIndex;
   backgroundRefreshes = /* @__PURE__ */ new Map();
-  accessProfiles = /* @__PURE__ */ new Map();
   layerDegradedUntil = /* @__PURE__ */ new Map();
-  circuitBreakers = /* @__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(normalizedKey, options, "allow-stale");
     if (hit.found) {
-      this.recordAccess(normalizedKey);
+      this.ttlResolver.recordAccess(normalizedKey);
       if (this.isNegativeStoredValue(hit.stored)) {
-        this.metrics.negativeCacheHits += 1;
+        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(normalizedKey, fetcher, options);
@@ -577,47 +855,136 @@ var CacheStack = class extends EventEmitter {
         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(normalizedKey, fetcher, options);
       } catch (error) {
-        this.metrics.staleHits += 1;
-        this.metrics.refreshErrors += 1;
+        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(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(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([normalizedKey]);
-    await this.publishInvalidation({ scope: "key", keys: [normalizedKey], sourceId: this.instanceId, operation: "delete" });
+    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.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 [];
@@ -655,7 +1022,9 @@ var CacheStack = class extends EventEmitter {
     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 entry = normalizedEntries[index];
+      if (!entry) continue;
+      const key = entry.key;
       const indexes = indexesByKey.get(key) ?? [];
       indexes.push(index);
       indexesByKey.set(key, indexes);
@@ -663,6 +1032,7 @@ var CacheStack = class extends EventEmitter {
     }
     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;
@@ -671,7 +1041,7 @@ var CacheStack = class extends EventEmitter {
       for (let offset = 0; offset < values.length; offset += 1) {
         const key = keys[offset];
         const stored = values[offset];
-        if (stored === null) {
+        if (!key || stored === null) {
           continue;
         }
         const resolved = resolveStoredValue(stored);
@@ -683,13 +1053,13 @@ var CacheStack = class extends EventEmitter {
         await this.backfill(key, stored, layerIndex - 1);
         resultsByKey.set(key, resolved.value);
         pending.delete(key);
-        this.metrics.hits += indexesByKey.get(key)?.length ?? 1;
+        this.metricsCollector.increment("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;
+        this.metricsCollector.increment("misses", indexesByKey.get(key)?.length ?? 1);
       }
     }
     return normalizedEntries.map((entry) => resultsByKey.get(entry.key) ?? null);
@@ -704,26 +1074,38 @@ var CacheStack = class extends EventEmitter {
   }
   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) }, async () => {
+    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(":");
@@ -731,6 +1113,10 @@ var CacheStack = class extends EventEmitter {
       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);
   }
@@ -747,7 +1133,7 @@ var CacheStack = class extends EventEmitter {
     await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
   }
   getMetrics() {
-    return { ...this.metrics };
+    return this.metricsCollector.snapshot;
   }
   getStats() {
     return {
@@ -761,7 +1147,13 @@ var CacheStack = class extends EventEmitter {
     };
   }
   resetMetrics() {
-    Object.assign(this.metrics, EMPTY_METRICS());
+    this.metricsCollector.reset();
+  }
+  /**
+   * Returns computed hit-rate statistics (overall and per-layer).
+   */
+  getHitRate() {
+    return this.metricsCollector.hitRate();
   }
   async exportState() {
     await this.startup;
@@ -790,10 +1182,12 @@ var CacheStack = class extends EventEmitter {
   }
   async importState(entries) {
     await this.startup;
-    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);
-    }));
+    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();
@@ -801,11 +1195,21 @@ var CacheStack = class extends EventEmitter {
   }
   async restoreFromFile(filePath) {
     const raw = await fs.readFile(filePath, "utf8");
-    const snapshot = JSON.parse(raw);
-    if (!this.isCacheSnapshotEntries(snapshot)) {
-      throw new Error("Invalid snapshot file: expected CacheSnapshotEntry[]");
+    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)})`);
     }
-    await this.importState(snapshot);
+    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) {
@@ -830,7 +1234,7 @@ var CacheStack = class extends EventEmitter {
     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);
@@ -855,12 +1259,12 @@ var CacheStack = class extends EventEmitter {
     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);
@@ -868,12 +1272,14 @@ var CacheStack = class extends EventEmitter {
     return this.fetchAndPopulate(key, fetcher, options);
   }
   async fetchAndPopulate(key, fetcher, options) {
-    this.assertCircuitClosed(key, options?.circuitBreaker ?? this.options.circuitBreaker);
-    this.metrics.fetches += 1;
+    this.circuitBreakerManager.assertClosed(key, options?.circuitBreaker ?? this.options.circuitBreaker);
+    this.metricsCollector.increment("fetches");
+    const fetchStart = Date.now();
     let fetched;
     try {
       fetched = await fetcher();
-      this.resetCircuitBreaker(key);
+      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;
@@ -895,7 +1301,7 @@ var CacheStack = class extends EventEmitter {
     } else {
       await this.tagIndex.touch(key);
     }
-    this.metrics.sets += 1;
+    this.metricsCollector.increment("sets");
     this.logger.debug?.("set", { key, kind, tags: options?.tags });
     this.emit("set", { key, kind, tags: options?.tags });
     if (this.shouldBroadcastL1Invalidation()) {
@@ -906,9 +1312,10 @@ var CacheStack = class extends EventEmitter {
     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.incrementMetricMap(this.metrics.missesByLayer, layer.name);
+        this.metricsCollector.incrementLayer("missesByLayer", layer.name);
         continue;
       }
       const resolved = resolveStoredValue(stored);
@@ -922,10 +1329,17 @@ var CacheStack = class extends EventEmitter {
       }
       await this.tagIndex.touch(key);
       await this.backfill(key, stored, index - 1, options);
-      this.incrementMetricMap(this.metrics.hitsByLayer, layer.name);
+      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 };
+      return {
+        found: true,
+        value: resolved.value,
+        stored,
+        state: resolved.state,
+        layerIndex: index,
+        layerName: layer.name
+      };
     }
     if (!sawRetainableValue) {
       await this.tagIndex.remove(key);
@@ -957,7 +1371,7 @@ var CacheStack = class extends EventEmitter {
     }
     for (let index = 0; index <= upToIndex; index += 1) {
       const layer = this.layers[index];
-      if (this.shouldSkipLayer(layer)) {
+      if (!layer || this.shouldSkipLayer(layer)) {
         continue;
       }
       const ttl = remainingStoredTtlSeconds(stored) ?? this.resolveLayerSeconds(layer.name, options?.ttl, void 0, layer.defaultTtl);
@@ -967,7 +1381,7 @@ var CacheStack = class extends EventEmitter {
         await this.handleLayerFailure(layer, "backfill", error);
         continue;
       }
-      this.metrics.backfills += 1;
+      this.metricsCollector.increment("backfills");
       this.logger.debug?.("backfill", { key, layer: layer.name });
       this.emit("backfill", { key, layer: layer.name });
     }
@@ -984,11 +1398,7 @@ var CacheStack = class extends EventEmitter {
         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,
@@ -1016,7 +1426,7 @@ var CacheStack = class extends EventEmitter {
     if (failures.length === 0) {
       return;
     }
-    this.metrics.writeFailures += failures.length;
+    this.metricsCollector.increment("writeFailures", failures.length);
     this.logger.debug?.("write-failure", {
       ...context,
       failures: failures.map((failure) => this.formatError(failure.reason))
@@ -1029,42 +1439,10 @@ var CacheStack = class extends EventEmitter {
     }
   }
   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);
+    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;
@@ -1074,11 +1452,11 @@ var CacheStack = class extends EventEmitter {
       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.metricsCollector.increment("refreshErrors");
         this.logger.debug?.("refresh-error", { key, error: this.formatError(error) });
       } finally {
         this.backgroundRefreshes.delete(key);
@@ -1100,10 +1478,11 @@ var CacheStack = class extends EventEmitter {
     await this.deleteKeysFromLayers(this.layers, keys);
     for (const key of keys) {
       await this.tagIndex.remove(key);
-      this.accessProfiles.delete(key);
+      this.ttlResolver.deleteProfile(key);
+      this.circuitBreakerManager.delete(key);
     }
-    this.metrics.deletes += keys.length;
-    this.metrics.invalidations += 1;
+    this.metricsCollector.increment("deletes", keys.length);
+    this.metricsCollector.increment("invalidations");
     this.logger.debug?.("delete", { keys });
     this.emit("delete", { keys });
   }
@@ -1124,7 +1503,7 @@ var CacheStack = class extends EventEmitter {
     if (message.scope === "clear") {
       await Promise.all(localLayers.map((layer) => layer.clear()));
       await this.tagIndex.clear();
-      this.accessProfiles.clear();
+      this.ttlResolver.clearProfiles();
       return;
     }
     const keys = message.keys ?? [];
@@ -1132,7 +1511,7 @@ var CacheStack = class extends EventEmitter {
     if (message.operation !== "write") {
       for (const key of keys) {
         await this.tagIndex.remove(key);
-        this.accessProfiles.delete(key);
+        this.ttlResolver.deleteProfile(key);
       }
     }
   }
@@ -1162,13 +1541,15 @@ var CacheStack = class extends EventEmitter {
           }
           return;
         }
-        await Promise.all(keys.map(async (key) => {
-          try {
-            await layer.delete(key);
-          } catch (error) {
-            await this.handleLayerFailure(layer, "delete", error);
-          }
-        }));
+        await Promise.all(
+          keys.map(async (key) => {
+            try {
+              await layer.delete(key);
+            } catch (error) {
+              await this.handleLayerFailure(layer, "delete", error);
+            }
+          })
+        );
       })
     );
   }
@@ -1269,7 +1650,7 @@ var CacheStack = class extends EventEmitter {
       const ttl = remainingStoredTtlSeconds(refreshed);
       for (let index = 0; index <= hit.layerIndex; index += 1) {
         const layer = this.layers[index];
-        if (this.shouldSkipLayer(layer)) {
+        if (!layer || this.shouldSkipLayer(layer)) {
           continue;
         }
         try {
@@ -1283,33 +1664,6 @@ var CacheStack = class extends EventEmitter {
       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();
@@ -1320,7 +1674,7 @@ var CacheStack = class extends EventEmitter {
     }
     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.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;
@@ -1328,37 +1682,15 @@ var CacheStack = class extends EventEmitter {
   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.circuitBreakerManager.recordFailure(key, options);
+    if (this.circuitBreakerManager.isOpen(key)) {
+      this.metricsCollector.increment("circuitBreakerTrips");
     }
-    this.circuitBreakers.set(key, state);
-    this.emitError("fetch", { key, error: this.formatError(error), failures: state.failures });
-  }
-  resetCircuitBreaker(key) {
-    this.circuitBreakers.delete(key);
+    this.emitError("fetch", { key, error: this.formatError(error) });
   }
   isNegativeStoredValue(stored) {
     return isStoredValueEnvelope(stored) && stored.kind === "empty";