layercache 3.0.0 → 3.1.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { I as InvalidationBus, C as CacheLogger, a as InvalidationMessage, b as CacheTagIndex, c as CacheStack, d as CacheWrapOptions, e as CacheGetOptions, f as CacheLayer, g as CacheSerializer, h as CacheLayerSetManyEntry, i as CacheSingleFlightCoordinator, j as CacheSingleFlightExecutionOptions } from './edge-BDyuPmIq.cjs';
-export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheContextOptionsContext, n as CacheDegradationOptions, o as CacheEntryWriteKind, p as CacheEntryWriteOptions, q as CacheFetcher, r as CacheFetcherContext, s as CacheHealthCheckResult, t as CacheHitRateSnapshot, u as CacheInspectResult, v as CacheLayerLatency, w as CacheMGetEntry, x as CacheMSetEntry, y as CacheMetricsSnapshot, z as CacheMissError, A as CacheNamespace, B as CacheRateLimitOptions, D as CacheSnapshotEntry, E as CacheStackEvents, F as CacheStackOptions, G as CacheStatsSnapshot, H as CacheTtlPolicy, J as CacheTtlPolicyContext, K as CacheWarmEntry, L as CacheWarmOptions, M as CacheWarmProgress, N as CacheWriteBehindOptions, O as CacheWriteOptions, P as EvictionPolicy, Q as LayerTtlMap, R as MemoryLayer, S as MemoryLayerOptions, T as MemoryLayerSnapshotEntry, U as PatternMatcher, V as TagIndex, W as createHonoCacheMiddleware } from './edge-BDyuPmIq.cjs';
+import { I as InvalidationBus, C as CacheLogger, a as InvalidationMessage, b as CacheTagIndex, c as CacheStack, d as CacheWrapOptions, e as CacheGetOptions, f as CacheLayer, g as CacheSerializer, h as CacheLayerSetManyEntry, i as CacheSingleFlightCoordinator, j as CacheSingleFlightExecutionOptions } from './edge-LBUuZAdr.cjs';
+export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheContextOptionsContext, n as CacheDegradationOptions, o as CacheEntryResult, p as CacheEntryWriteKind, q as CacheEntryWriteOptions, r as CacheFetcher, s as CacheFetcherContext, t as CacheHealthCheckResult, u as CacheHitRateSnapshot, v as CacheInspectResult, w as CacheLayerLatency, x as CacheMGetEntry, y as CacheMSetEntry, z as CacheMetricsSnapshot, A as CacheMissError, B as CacheNamespace, D as CacheRateLimitOptions, E as CacheSnapshotEntry, F as CacheStackEvents, G as CacheStackOptions, H as CacheStatsSnapshot, J as CacheTtlPolicy, K as CacheTtlPolicyContext, L as CacheWarmEntry, M as CacheWarmOptions, N as CacheWarmProgress, O as CacheWriteBehindOptions, P as CacheWriteOptions, Q as EvictionPolicy, R as LayerTtlMap, S as MemoryLayer, T as MemoryLayerOptions, U as MemoryLayerSnapshotEntry, V as PatternMatcher, W as TagIndex, X as createHonoCacheMiddleware } from './edge-LBUuZAdr.cjs';
 import Redis from 'ioredis';
 import 'node:events';
 
@@ -480,6 +480,11 @@ interface DiskLayerOptions {
      * Set to `false` to disable the limit.
      */
     maxEntryBytes?: number | false;
+    /**
+     * Maximum pending write operations allowed in the serialized write queue.
+     * Defaults to 10,000. Set to `false` to disable the guard.
+     */
+    maxWriteQueueDepth?: number | false;
     /**
      * Encrypt cached data at rest using AES-256-GCM. Accepts a string or Buffer.
      * The key material is hashed with SHA-256 to derive the actual cipher key.
@@ -513,8 +518,10 @@ declare class DiskLayer implements CacheLayer {
     private readonly serializer;
     private readonly maxFiles;
     private readonly maxEntryBytes;
+    private readonly maxWriteQueueDepth;
     private readonly protection;
     private writeQueue;
+    private writeQueueDepth;
     /**
      * Creates a disk-backed cache layer.
      */
@@ -584,6 +591,7 @@ declare class DiskLayer implements CacheLayer {
     private resolveDirectory;
     private normalizeMaxFiles;
     private normalizeMaxEntryBytes;
+    private normalizeMaxWriteQueueDepth;
     private readEntryFile;
     private readHandleWithLimit;
     private scanEntries;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { I as InvalidationBus, C as CacheLogger, a as InvalidationMessage, b as CacheTagIndex, c as CacheStack, d as CacheWrapOptions, e as CacheGetOptions, f as CacheLayer, g as CacheSerializer, h as CacheLayerSetManyEntry, i as CacheSingleFlightCoordinator, j as CacheSingleFlightExecutionOptions } from './edge-BDyuPmIq.js';
-export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheContextOptionsContext, n as CacheDegradationOptions, o as CacheEntryWriteKind, p as CacheEntryWriteOptions, q as CacheFetcher, r as CacheFetcherContext, s as CacheHealthCheckResult, t as CacheHitRateSnapshot, u as CacheInspectResult, v as CacheLayerLatency, w as CacheMGetEntry, x as CacheMSetEntry, y as CacheMetricsSnapshot, z as CacheMissError, A as CacheNamespace, B as CacheRateLimitOptions, D as CacheSnapshotEntry, E as CacheStackEvents, F as CacheStackOptions, G as CacheStatsSnapshot, H as CacheTtlPolicy, J as CacheTtlPolicyContext, K as CacheWarmEntry, L as CacheWarmOptions, M as CacheWarmProgress, N as CacheWriteBehindOptions, O as CacheWriteOptions, P as EvictionPolicy, Q as LayerTtlMap, R as MemoryLayer, S as MemoryLayerOptions, T as MemoryLayerSnapshotEntry, U as PatternMatcher, V as TagIndex, W as createHonoCacheMiddleware } from './edge-BDyuPmIq.js';
+import { I as InvalidationBus, C as CacheLogger, a as InvalidationMessage, b as CacheTagIndex, c as CacheStack, d as CacheWrapOptions, e as CacheGetOptions, f as CacheLayer, g as CacheSerializer, h as CacheLayerSetManyEntry, i as CacheSingleFlightCoordinator, j as CacheSingleFlightExecutionOptions } from './edge-LBUuZAdr.js';
+export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheContextOptionsContext, n as CacheDegradationOptions, o as CacheEntryResult, p as CacheEntryWriteKind, q as CacheEntryWriteOptions, r as CacheFetcher, s as CacheFetcherContext, t as CacheHealthCheckResult, u as CacheHitRateSnapshot, v as CacheInspectResult, w as CacheLayerLatency, x as CacheMGetEntry, y as CacheMSetEntry, z as CacheMetricsSnapshot, A as CacheMissError, B as CacheNamespace, D as CacheRateLimitOptions, E as CacheSnapshotEntry, F as CacheStackEvents, G as CacheStackOptions, H as CacheStatsSnapshot, J as CacheTtlPolicy, K as CacheTtlPolicyContext, L as CacheWarmEntry, M as CacheWarmOptions, N as CacheWarmProgress, O as CacheWriteBehindOptions, P as CacheWriteOptions, Q as EvictionPolicy, R as LayerTtlMap, S as MemoryLayer, T as MemoryLayerOptions, U as MemoryLayerSnapshotEntry, V as PatternMatcher, W as TagIndex, X as createHonoCacheMiddleware } from './edge-LBUuZAdr.js';
 import Redis from 'ioredis';
 import 'node:events';
 
@@ -480,6 +480,11 @@ interface DiskLayerOptions {
      * Set to `false` to disable the limit.
      */
     maxEntryBytes?: number | false;
+    /**
+     * Maximum pending write operations allowed in the serialized write queue.
+     * Defaults to 10,000. Set to `false` to disable the guard.
+     */
+    maxWriteQueueDepth?: number | false;
     /**
      * Encrypt cached data at rest using AES-256-GCM. Accepts a string or Buffer.
      * The key material is hashed with SHA-256 to derive the actual cipher key.
@@ -513,8 +518,10 @@ declare class DiskLayer implements CacheLayer {
     private readonly serializer;
     private readonly maxFiles;
     private readonly maxEntryBytes;
+    private readonly maxWriteQueueDepth;
     private readonly protection;
     private writeQueue;
+    private writeQueueDepth;
     /**
      * Creates a disk-backed cache layer.
      */
@@ -584,6 +591,7 @@ declare class DiskLayer implements CacheLayer {
     private resolveDirectory;
     private normalizeMaxFiles;
     private normalizeMaxEntryBytes;
+    private normalizeMaxWriteQueueDepth;
     private readEntryFile;
     private readHandleWithLimit;
     private scanEntries;

package/dist/index.js

@@ -12,13 +12,13 @@ import {
   validateTag,
   validateTags,
   validateTtlPolicy
-} from "./chunk-NBMG7DHT.js";
+} from "./chunk-L6L7QXYF.js";
 import {
   MemoryLayer,
   TagIndex,
   createHonoCacheMiddleware,
   normalizeHttpCacheUrl
-} from "./chunk-5CIBABDH.js";
+} from "./chunk-XMUT66SH.js";
 import {
   PatternMatcher,
   createStoredValueEnvelope,
@@ -71,39 +71,6 @@ function cloneNamespaceMetrics(metrics) {
     )
   };
 }
-function diffNamespaceMetrics(before, after) {
-  const latencyByLayer = Object.fromEntries(
-    Object.entries(after.latencyByLayer).map(([layer, value]) => [
-      layer,
-      {
-        avgMs: value.avgMs,
-        maxMs: value.maxMs,
-        count: Math.max(0, value.count - (before.latencyByLayer[layer]?.count ?? 0))
-      }
-    ])
-  );
-  return {
-    hits: after.hits - before.hits,
-    misses: after.misses - before.misses,
-    fetches: after.fetches - before.fetches,
-    sets: after.sets - before.sets,
-    deletes: after.deletes - before.deletes,
-    backfills: after.backfills - before.backfills,
-    invalidations: after.invalidations - before.invalidations,
-    staleHits: after.staleHits - before.staleHits,
-    refreshes: after.refreshes - before.refreshes,
-    refreshErrors: after.refreshErrors - before.refreshErrors,
-    writeFailures: after.writeFailures - before.writeFailures,
-    singleFlightWaits: after.singleFlightWaits - before.singleFlightWaits,
-    negativeCacheHits: after.negativeCacheHits - before.negativeCacheHits,
-    circuitBreakerTrips: after.circuitBreakerTrips - before.circuitBreakerTrips,
-    degradedOperations: after.degradedOperations - before.degradedOperations,
-    hitsByLayer: diffMetricMap(before.hitsByLayer, after.hitsByLayer),
-    missesByLayer: diffMetricMap(before.missesByLayer, after.missesByLayer),
-    latencyByLayer,
-    resetAt: after.resetAt
-  };
-}
 function addNamespaceMetrics(base, delta) {
   return {
     hits: base.hits + delta.hits,
@@ -139,14 +106,6 @@ function computeNamespaceHitRate(metrics) {
   }
   return { overall, byLayer };
 }
-function diffMetricMap(before, after) {
-  const keys = /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)]);
-  const result = {};
-  for (const key of keys) {
-    result[key] = (after[key] ?? 0) - (before[key] ?? 0);
-  }
-  return result;
-}
 function addMetricMap(base, delta) {
   const keys = /* @__PURE__ */ new Set([...Object.keys(base), ...Object.keys(delta)]);
   const result = {};
@@ -183,6 +142,20 @@ var CacheNamespace = class _CacheNamespace {
   async getOrSet(key, fetcher, options) {
     return this.trackMetrics(() => this.cache.getOrSet(this.qualify(key), fetcher, this.qualifyGetOptions(options)));
   }
+  /**
+   * Returns a namespaced cache entry, or `null` on miss.
+   * Unlike `get()`, this distinguishes a stored `null` value from an absent key.
+   */
+  async getEntry(key) {
+    const entry = await this.trackMetrics(() => this.cache.getEntry(this.qualify(key)));
+    if (entry === null) {
+      return null;
+    }
+    return {
+      ...entry,
+      key
+    };
+  }
   /**
    * Like `get()`, but throws `CacheMissError` instead of returning `null`.
    */
@@ -417,13 +390,24 @@ var CacheNamespace = class _CacheNamespace {
     };
   }
   async trackMetrics(operation) {
-    return this.getMetricsMutex().runExclusive(async () => {
-      const before = this.cache.getMetrics();
-      const result = await operation();
-      const after = this.cache.getMetrics();
-      this.metrics = addNamespaceMetrics(this.metrics, diffNamespaceMetrics(before, after));
-      return result;
+    let result;
+    let metrics;
+    try {
+      ;
+      ({ result, metrics } = await this.cache.captureMetrics(operation));
+    } catch (error) {
+      const capturedMetrics = error.metrics;
+      if (capturedMetrics) {
+        await this.getMetricsMutex().runExclusive(() => {
+          this.metrics = addNamespaceMetrics(this.metrics, capturedMetrics);
+        });
+      }
+      throw error;
+    }
+    await this.getMetricsMutex().runExclusive(() => {
+      this.metrics = addNamespaceMetrics(this.metrics, metrics);
     });
+    return result;
   }
   getMetricsMutex() {
     const existing = _CacheNamespace.metricsMutexes.get(this.cache);
@@ -1027,6 +1011,9 @@ var DEFAULT_SINGLE_FLIGHT_LEASE_MS = 3e4;
 var DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS = 5e3;
 var DEFAULT_SINGLE_FLIGHT_POLL_MS = 50;
 var DEFAULT_BACKGROUND_REFRESH_TIMEOUT_MS = 3e4;
+var SINGLE_FLIGHT_BACKOFF_FACTOR = 2;
+var SINGLE_FLIGHT_BACKOFF_JITTER = 0.2;
+var SINGLE_FLIGHT_MAX_POLL_MS = 1e3;
 var CacheStackReader = class {
   constructor(options) {
     this.options = options;
@@ -1250,6 +1237,7 @@ var CacheStackReader = 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;
+    let nextPollMs = pollIntervalMs;
     this.options.metricsCollector.increment("singleFlightWaits");
     this.options.emit("stampede-dedupe", { key });
     while (Date.now() < deadline) {
@@ -1258,7 +1246,13 @@ var CacheStackReader = class {
         this.options.metricsCollector.increment("hits");
         return hit.value;
       }
-      await this.options.sleep(pollIntervalMs);
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) {
+        break;
+      }
+      const delayMs = Math.min(this.jitterSingleFlightPoll(nextPollMs), remainingMs);
+      await this.options.sleep(delayMs);
+      nextPollMs = Math.min(nextPollMs * SINGLE_FLIGHT_BACKOFF_FACTOR, SINGLE_FLIGHT_MAX_POLL_MS, timeoutMs);
     }
     if (!this.options.singleFlightCoordinator) {
       return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext);
@@ -1270,12 +1264,18 @@ var CacheStackReader = class {
       () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext)
     );
   }
+  jitterSingleFlightPoll(delayMs) {
+    const jitterRange = delayMs * SINGLE_FLIGHT_BACKOFF_JITTER;
+    return Math.max(1, Math.round(delayMs - jitterRange + Math.random() * jitterRange * 2));
+  }
   async fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext = {
     key,
     currentValue: void 0,
     state: "miss"
   }) {
-    this.options.circuitBreakerManager.assertClosed(key, options?.circuitBreaker ?? this.options.circuitBreaker);
+    const circuitBreakerOptions = options?.circuitBreaker ?? this.options.circuitBreaker;
+    const breakerKey = this.resolveCircuitBreakerKey(key, circuitBreakerOptions);
+    this.options.circuitBreakerManager.assertClosed(breakerKey, circuitBreakerOptions);
     this.options.metricsCollector.increment("fetches");
     const fetchStart = Date.now();
     let fetched;
@@ -1285,13 +1285,13 @@ var CacheStackReader = class {
         { key, fetcher },
         () => fetcher(fetcherContext)
       );
-      this.options.circuitBreakerManager.recordSuccess(key);
+      this.options.circuitBreakerManager.recordSuccess(breakerKey);
       this.options.logger.debug?.("fetch", { key, durationMs: Date.now() - fetchStart });
     } catch (error) {
-      this.options.recordCircuitFailure(key, options?.circuitBreaker ?? this.options.circuitBreaker, error);
+      this.options.recordCircuitFailure(key, breakerKey, circuitBreakerOptions, error);
       throw error;
     }
-    if (fetched === null || fetched === void 0) {
+    if (fetched === void 0 || fetched === null && !this.shouldCacheNullValues(options)) {
       if (!this.shouldNegativeCache(options)) {
         return null;
       }
@@ -1333,6 +1333,18 @@ var CacheStackReader = class {
     await this.options.storeEntry(key, "value", fetched, options);
     return fetched;
   }
+  resolveCircuitBreakerKey(key, options) {
+    if (!options) {
+      return `key:${key}`;
+    }
+    if (options.breakerKey) {
+      return `custom:${options.breakerKey}`;
+    }
+    if (options.scope === "shared") {
+      return "scope:shared";
+    }
+    return `key:${key}`;
+  }
   runScheduleBackgroundRefresh(key, fetcher, options, fetcherContext) {
     this.scheduleBackgroundRefresh(key, fetcher, options, fetcherContext);
   }
@@ -1433,6 +1445,9 @@ var CacheStackReader = class {
   shouldNegativeCache(options) {
     return options?.negativeCache ?? this.options.negativeCaching ?? false;
   }
+  shouldCacheNullValues(options) {
+    return options?.cacheNullValues ?? this.options.cacheNullValues ?? false;
+  }
   isNegativeStoredValue(stored) {
     return isStoredValueEnvelope(stored) && stored.kind === "empty";
   }
@@ -1834,6 +1849,7 @@ var CircuitBreakerManager = class {
 // src/internal/FetchRateLimiter.ts
 var MAX_BUCKETS = 1e4;
 var MAX_QUEUE_PER_BUCKET = 1e4;
+var DEFAULT_QUEUE_OVERFLOW_POLICY = "reject";
 var FetchRateLimiter = class {
   buckets = /* @__PURE__ */ new Map();
   queuesByBucket = /* @__PURE__ */ new Map();
@@ -1858,15 +1874,24 @@ var FetchRateLimiter = class {
       const bucketKey = this.resolveBucketKey(normalized, context);
       const queue = this.queuesByBucket.get(bucketKey) ?? [];
       if (queue.length >= MAX_QUEUE_PER_BUCKET) {
-        this.rateLimitBypasses += 1;
-        task().then(resolve2, reject);
+        if ((normalized.queueOverflow ?? DEFAULT_QUEUE_OVERFLOW_POLICY) === "bypass") {
+          this.rateLimitBypasses += 1;
+          task().then(resolve2, reject);
+          return;
+        }
+        reject(new Error(`FetchRateLimiter queue overflow for bucket "${bucketKey}".`));
         return;
       }
       queue.push({
         bucketKey,
         options: normalized,
-        task,
-        resolve: resolve2,
+        run: async () => {
+          try {
+            resolve2(await task());
+          } catch (error) {
+            reject(error);
+          }
+        },
         reject
       });
       this.queuesByBucket.set(bucketKey, queue);
@@ -1907,7 +1932,8 @@ var FetchRateLimiter = class {
       intervalMs,
       maxPerInterval,
       scope: options.scope ?? "global",
-      bucketKey: options.bucketKey
+      bucketKey: options.bucketKey,
+      queueOverflow: options.queueOverflow
     };
   }
   resolveBucketKey(options, context) {
@@ -1990,7 +2016,7 @@ var FetchRateLimiter = class {
       if (next.options.intervalMs && next.options.maxPerInterval) {
         bucket.startedAt.push(Date.now());
       }
-      void next.task().then(next.resolve, next.reject).finally(() => {
+      void next.run().finally(() => {
         bucket.active -= 1;
         if ((this.queuesByBucket.get(next.bucketKey)?.length ?? 0) > 0) {
           this.pendingBuckets.add(next.bucketKey);
@@ -2092,7 +2118,9 @@ var FetchRateLimiter = class {
 };
 
 // src/internal/MetricsCollector.ts
+import { AsyncLocalStorage } from "async_hooks";
 var MetricsCollector = class {
+  captures = new AsyncLocalStorage();
   data = this.empty();
   get snapshot() {
     return {
@@ -2105,18 +2133,46 @@ var MetricsCollector = class {
   increment(field, amount = 1) {
     ;
     this.data[field] += amount;
+    for (const capture of this.captures.getStore() ?? []) {
+      ;
+      capture[field] += amount;
+    }
   }
   incrementLayer(map, layerName) {
     this.data[map][layerName] = (this.data[map][layerName] ?? 0) + 1;
+    for (const capture of this.captures.getStore() ?? []) {
+      capture[map][layerName] = (capture[map][layerName] ?? 0) + 1;
+    }
   }
   /**
    * Records a read latency sample for the given layer.
    * Maintains a rolling average and max using Welford's online algorithm.
    */
   recordLatency(layerName, durationMs) {
-    const existing = this.data.latencyByLayer[layerName];
+    this.recordLatencySample(this.data, layerName, durationMs);
+    for (const capture of this.captures.getStore() ?? []) {
+      this.recordLatencySample(capture, layerName, durationMs);
+    }
+  }
+  async capture(operation) {
+    const metrics = this.empty();
+    const activeCaptures = this.captures.getStore();
+    const captures = activeCaptures ? [...activeCaptures, metrics] : [metrics];
+    try {
+      const result = await this.captures.run(captures, operation);
+      return { result, metrics };
+    } catch (error) {
+      if ((typeof error === "object" || typeof error === "function") && error !== null) {
+        ;
+        error.metrics = metrics;
+      }
+      throw error;
+    }
+  }
+  recordLatencySample(metrics, layerName, durationMs) {
+    const existing = metrics.latencyByLayer[layerName];
     if (!existing) {
-      this.data.latencyByLayer[layerName] = { avgMs: durationMs, maxMs: durationMs, count: 1 };
+      metrics.latencyByLayer[layerName] = { avgMs: durationMs, maxMs: durationMs, count: 1 };
       return;
     }
     existing.count += 1;
@@ -2529,7 +2585,7 @@ var CacheStack = class extends EventEmitter {
       emitError: (operation, context) => this.emitError(operation, context),
       formatError: (error) => this.formatError(error),
       storeEntry: (key, kind, value, options2) => this.storeEntry(key, kind, value, options2),
-      recordCircuitFailure: (key, options2, error) => this.recordCircuitFailure(key, options2, error),
+      recordCircuitFailure: (key, breakerKey, options2, error) => this.recordCircuitFailure(key, breakerKey, options2, error),
       resolveLayerMs: (layerName, override, globalDefault, fallback) => this.resolveLayerMs(layerName, override, globalDefault, fallback),
       sleep: (ms) => this.sleep(ms),
       withTimeout: (promise, ms, createError) => this.withTimeout(promise, ms, createError),
@@ -2544,6 +2600,7 @@ var CacheStack = class extends EventEmitter {
       singleFlightRenewIntervalMs: options.singleFlightRenewIntervalMs,
       backgroundRefreshTimeoutMs: options.backgroundRefreshTimeoutMs,
       negativeCaching: options.negativeCaching,
+      cacheNullValues: options.cacheNullValues,
       refreshAhead: options.refreshAhead,
       circuitBreaker: options.circuitBreaker,
       fetcherRateLimit: options.fetcherRateLimit
@@ -2596,6 +2653,64 @@ var CacheStack = class extends EventEmitter {
   async getOrSet(key, fetcher, options) {
     return this.get(key, fetcher, options);
   }
+  /**
+   * Returns a discriminated cache entry, or `null` on miss.
+   * Unlike `get()`, this distinguishes a stored `null` value from an absent key.
+   */
+  async getEntry(key) {
+    return this.observeOperation("layercache.get_entry", { "layercache.key": String(key ?? "") }, async () => {
+      const userKey = validateCacheKey(key);
+      const normalizedKey = this.qualifyKey(userKey);
+      await this.awaitStartup("getEntry");
+      let sawRetainableValue = false;
+      for (let index = 0; index < this.layers.length; index += 1) {
+        const layer = this.layers[index];
+        if (!layer || this.shouldSkipLayer(layer)) {
+          continue;
+        }
+        const readStart = performance.now();
+        const stored = await this.readLayerEntry(layer, normalizedKey);
+        this.metricsCollector.recordLatency(layer.name, performance.now() - readStart);
+        if (stored === null) {
+          this.metricsCollector.incrementLayer("missesByLayer", layer.name);
+          continue;
+        }
+        const resolved = resolveStoredValue(stored);
+        if (resolved.state === "expired") {
+          await layer.delete(normalizedKey);
+          continue;
+        }
+        sawRetainableValue = true;
+        await this.tagIndex.touch(normalizedKey);
+        await this.reader.backfill(normalizedKey, stored, index - 1);
+        this.metricsCollector.increment("hits");
+        if (resolved.state === "stale-while-revalidate" || resolved.state === "stale-if-error") {
+          this.metricsCollector.increment("staleHits");
+        }
+        this.metricsCollector.incrementLayer("hitsByLayer", layer.name);
+        this.logger.debug?.("hit", { key: normalizedKey, layer: layer.name, state: resolved.state });
+        this.emit("hit", {
+          key: normalizedKey,
+          layer: layer.name,
+          state: resolved.state
+        });
+        return {
+          key: userKey,
+          value: resolved.value,
+          kind: resolved.envelope?.kind ?? "value",
+          state: resolved.state,
+          layer: layer.name
+        };
+      }
+      if (!sawRetainableValue) {
+        await this.tagIndex.remove(normalizedKey);
+      }
+      this.metricsCollector.increment("misses");
+      this.logger.debug?.("miss", { key: normalizedKey, mode: "getEntry" });
+      this.emit("miss", { key: normalizedKey, mode: "getEntry" });
+      return null;
+    });
+  }
   /**
    * Like `get()`, but throws `CacheMissError` instead of returning `null`.
    * Useful when the value is expected to exist or the fetcher is expected to
@@ -3060,6 +3175,13 @@ var CacheStack = class extends EventEmitter {
   getMetrics() {
     return this.metricsCollector.snapshot;
   }
+  /**
+   * Runs an operation while collecting only the metrics emitted by its async context.
+   * Used by namespaces so metrics tracking does not serialize the operation itself.
+   */
+  async captureMetrics(operation) {
+    return this.metricsCollector.capture(operation);
+  }
   /**
    * Returns metrics plus layer degradation state and active background refresh count.
    */
@@ -3363,7 +3485,7 @@ var CacheStack = class extends EventEmitter {
     for (const key of keys) {
       await this.tagIndex.remove(key);
       this.ttlResolver.deleteProfile(key);
-      this.circuitBreakerManager.delete(key);
+      this.circuitBreakerManager.delete(`key:${key}`);
     }
     this.metricsCollector.increment("deletes", keys.length);
     this.metricsCollector.increment("invalidations");
@@ -3382,7 +3504,7 @@ var CacheStack = class extends EventEmitter {
       }
       await this.tagIndex.remove(key);
       this.ttlResolver.deleteProfile(key);
-      this.circuitBreakerManager.delete(key);
+      this.circuitBreakerManager.delete(`key:${key}`);
     }
     this.metricsCollector.increment("invalidations");
     this.logger.debug?.("expire", { keys });
@@ -3424,7 +3546,7 @@ var CacheStack = class extends EventEmitter {
       for (const key of keys) {
         await this.tagIndex.remove(key);
         this.ttlResolver.deleteProfile(key);
-        this.circuitBreakerManager.delete(key);
+        this.circuitBreakerManager.delete(`key:${key}`);
       }
     }
   }
@@ -3669,15 +3791,15 @@ var CacheStack = class extends EventEmitter {
   isGracefulDegradationEnabled() {
     return Boolean(this.options.gracefulDegradation);
   }
-  recordCircuitFailure(key, options, error) {
+  recordCircuitFailure(key, breakerKey, options, error) {
     if (!options) {
       return;
     }
-    this.circuitBreakerManager.recordFailure(key, options);
-    if (this.circuitBreakerManager.isOpen(key)) {
+    this.circuitBreakerManager.recordFailure(breakerKey, options);
+    if (this.circuitBreakerManager.isOpen(breakerKey)) {
       this.metricsCollector.increment("circuitBreakerTrips");
     }
-    this.emitError("fetch", { key, error: this.formatError(error) });
+    this.emitError("fetch", { key, breakerKey, error: this.formatError(error) });
   }
   emitError(operation, context) {
     this.logger.error?.(operation, context);
@@ -4712,6 +4834,7 @@ var PayloadProtectionError = class extends Error {
 
 // src/layers/DiskLayer.ts
 var FILE_SCAN_CONCURRENCY = 32;
+var DEFAULT_MAX_WRITE_QUEUE_DEPTH = 1e4;
 var DiskLayer = class {
   name;
   defaultTtl;
@@ -4720,8 +4843,10 @@ var DiskLayer = class {
   serializer;
   maxFiles;
   maxEntryBytes;
+  maxWriteQueueDepth;
   protection;
   writeQueue = Promise.resolve();
+  writeQueueDepth = 0;
   /**
    * Creates a disk-backed cache layer.
    */
@@ -4732,6 +4857,7 @@ var DiskLayer = class {
     this.serializer = options.serializer ?? new JsonSerializer();
     this.maxFiles = this.normalizeMaxFiles(options.maxFiles);
     this.maxEntryBytes = this.normalizeMaxEntryBytes(options.maxEntryBytes);
+    this.maxWriteQueueDepth = this.normalizeMaxWriteQueueDepth(options.maxWriteQueueDepth);
     this.protection = new PayloadProtection({
       encryptionKey: options.encryptionKey,
       signingKey: options.signingKey
@@ -4947,6 +5073,16 @@ var DiskLayer = class {
     }
     return normalized;
   }
+  normalizeMaxWriteQueueDepth(maxWriteQueueDepth) {
+    if (maxWriteQueueDepth === false) {
+      return false;
+    }
+    const normalized = maxWriteQueueDepth ?? DEFAULT_MAX_WRITE_QUEUE_DEPTH;
+    if (!Number.isInteger(normalized) || normalized <= 0) {
+      throw new Error("DiskLayer.maxWriteQueueDepth must be a positive integer or false.");
+    }
+    return normalized;
+  }
   async readEntryFile(filePath) {
     let handle;
     try {
@@ -5059,7 +5195,13 @@ var DiskLayer = class {
     }
   }
   enqueueWrite(operation) {
-    const next = this.writeQueue.then(operation, operation);
+    if (this.maxWriteQueueDepth !== false && this.writeQueueDepth >= this.maxWriteQueueDepth) {
+      return Promise.reject(new Error(`DiskLayer write queue limit (${this.maxWriteQueueDepth}) exceeded.`));
+    }
+    this.writeQueueDepth += 1;
+    const next = this.writeQueue.then(operation, operation).finally(() => {
+      this.writeQueueDepth -= 1;
+    });
     this.writeQueue = next.catch(() => void 0);
     return next;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "layercache",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "description": "Production-ready multi-layer caching for Node.js. Stack memory + Redis + disk behind one API with stampede prevention, tag invalidation, stale serving, and full observability.",
   "keywords": [
     "cache",
@@ -97,8 +97,11 @@
     "ioredis": "^5.6.1",
     "ioredis-mock": "^8.13.0",
     "tsup": "^8.5.0",
-    "tsx": "^4.19.3",
+    "tsx": "^4.22.4",
     "typescript": "^5.8.3",
     "vitest": "^4.1.2"
+  },
+  "overrides": {
+    "esbuild": "0.28.1"
   }
 }