layercache 1.2.9 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "layercache",
-  "version": "1.2.9",
+  "version": "1.3.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",
@@ -74,7 +74,15 @@
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "bench:latency": "tsx benchmarks/latency.ts",
-    "bench:stampede": "tsx benchmarks/stampede.ts"
+    "bench:stampede": "tsx benchmarks/stampede.ts",
+    "bench:direct": "tsx benchmarks/direct.ts",
+    "bench:http": "tsx benchmarks/http.ts",
+    "bench:edge": "tsx benchmarks/edge.ts",
+    "bench:slow-redis": "tsx benchmarks/slow-redis.ts",
+    "bench:memory-pressure": "tsx benchmarks/memory-pressure.ts",
+    "bench:queue-amplification": "tsx benchmarks/queue-amplification.ts",
+    "bench:multi-process-fanout": "tsx benchmarks/multi-process-fanout.ts",
+    "bench:all": "npm run bench:direct && npm run bench:edge && npm run bench:slow-redis && npm run bench:queue-amplification && npm run bench:http && npm run bench:multi-process-fanout"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.0.0",
@@ -90,8 +98,10 @@
     "@biomejs/biome": "^1.9.4",
     "@nestjs/common": "^11.1.0",
     "@nestjs/core": "^11.1.0",
+    "@types/autocannon": "^7.12.7",
     "@types/node": "^22.15.2",
     "@vitest/coverage-v8": "^4.1.2",
+    "autocannon": "^8.0.0",
     "ioredis": "^5.6.1",
     "ioredis-mock": "^8.13.0",
     "reflect-metadata": "^0.2.2",

package/packages/nestjs/dist/index.cjs

@@ -741,15 +741,14 @@ function createInstanceId() {
   if (globalThis.crypto?.randomUUID) {
     return globalThis.crypto.randomUUID();
   }
-  const bytes = new Uint8Array(16);
   if (globalThis.crypto?.getRandomValues) {
+    const bytes = new Uint8Array(16);
     globalThis.crypto.getRandomValues(bytes);
-  } else {
-    for (let i = 0; i < bytes.length; i += 1) {
-      bytes[i] = Math.floor(Math.random() * 256);
-    }
+    return `layercache-${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
   }
-  return `layercache-${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+  throw new Error(
+    "layercache requires a cryptographic random source. Neither crypto.randomUUID nor crypto.getRandomValues is available in this runtime."
+  );
 }
 
 // ../../src/internal/CacheStackGeneration.ts
@@ -1728,7 +1727,8 @@ var CircuitBreakerManager = class {
     }
     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).`);
+    const displayKey = key.length > 64 ? `${key.slice(0, 64)}...` : key;
+    throw new Error(`Circuit breaker is open for key "${displayKey}" (resets in ${remainingSecs}s).`);
   }
   recordFailure(key, options) {
     if (!options) {
@@ -2493,7 +2493,14 @@ var JsonSerializer = class {
   }
   deserialize(payload) {
     const normalized = Buffer.isBuffer(payload) ? payload.toString("utf8") : payload;
-    return sanitizeStructuredData(JSON.parse(normalized), {
+    let parsed;
+    try {
+      parsed = JSON.parse(normalized);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`JsonSerializer: failed to parse JSON payload: ${message}`);
+    }
+    return sanitizeStructuredData(parsed, {
       label: "JSON payload",
       maxDepth: 200,
       maxNodes: 1e4
@@ -2503,27 +2510,68 @@ var JsonSerializer = class {
 
 // ../../src/stampede/StampedeGuard.ts
 var StampedeGuard = class {
-  mutexes = /* @__PURE__ */ new Map();
+  inFlight = /* @__PURE__ */ new Map();
+  maxInFlight;
+  entryTimeoutMs;
+  constructor(options = {}) {
+    this.maxInFlight = options.maxInFlight ?? 1e4;
+    this.entryTimeoutMs = options.entryTimeoutMs;
+  }
   async execute(key, task) {
-    const entry = this.getMutexEntry(key);
+    const existing = this.inFlight.get(key);
+    if (existing) {
+      existing.references += 1;
+      try {
+        return await existing.promise;
+      } finally {
+        this.releaseEntry(key, existing);
+      }
+    }
+    if (this.inFlight.size >= this.maxInFlight) {
+      throw new Error(
+        `StampedeGuard: in-flight limit of ${this.maxInFlight} exceeded. Rejecting new key to prevent memory exhaustion.`
+      );
+    }
+    const taskPromise = Promise.resolve().then(task);
+    const guardedPromise = this.entryTimeoutMs ? this.withTimeout(key, taskPromise, this.entryTimeoutMs) : taskPromise;
+    const entry = {
+      promise: guardedPromise,
+      references: 1
+    };
+    this.inFlight.set(key, entry);
     try {
-      return await entry.mutex.runExclusive(task);
+      return await entry.promise;
     } finally {
-      entry.references -= 1;
-      const current = this.mutexes.get(key);
-      if (current === entry && entry.references === 0 && !entry.mutex.isLocked()) {
-        this.mutexes.delete(key);
-      }
+      this.releaseEntry(key, entry);
     }
   }
-  getMutexEntry(key) {
-    let entry = this.mutexes.get(key);
-    if (!entry) {
-      entry = { mutex: new Mutex(), references: 0 };
-      this.mutexes.set(key, entry);
+  withTimeout(key, promise, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(
+          new Error(
+            `StampedeGuard: task for key "${key.slice(0, 64)}${key.length > 64 ? "..." : ""}" timed out after ${timeoutMs}ms.`
+          )
+        );
+      }, timeoutMs);
+      promise.then(
+        (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        (error) => {
+          clearTimeout(timer);
+          reject(error);
+        }
+      );
+    });
+  }
+  releaseEntry(key, entry) {
+    entry.references -= 1;
+    const current = this.inFlight.get(key);
+    if (current === entry && entry.references === 0) {
+      this.inFlight.delete(key);
     }
-    entry.references += 1;
-    return entry;
   }
 };
 
@@ -2583,6 +2631,10 @@ var CacheStack = class extends import_node_events.EventEmitter {
     const maxProfileEntries = options.maxProfileEntries ?? DEFAULT_MAX_PROFILE_ENTRIES;
     this.ttlResolver = new TtlResolver({ maxProfileEntries });
     this.circuitBreakerManager = new CircuitBreakerManager({ maxEntries: maxProfileEntries });
+    this.stampedeGuard = new StampedeGuard({
+      maxInFlight: options.stampedeMaxInFlight,
+      entryTimeoutMs: options.stampedeEntryTimeoutMs
+    });
     this.currentGeneration = options.generation;
     if (options.publishSetInvalidation !== void 0) {
       console.warn(
@@ -2661,7 +2713,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
   }
   layers;
   options;
-  stampedeGuard = new StampedeGuard();
+  stampedeGuard;
   metricsCollector = new MetricsCollector();
   instanceId = createInstanceId();
   startup;
@@ -2738,7 +2790,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
     if (!fetcher) {
       return null;
     }
-    return this.fetchWithGuards(normalizedKey, fetcher, options);
+    return this.fetchWithGuards(normalizedKey, fetcher, options, void 0, void 0, true);
   }
   /**
    * Alias for `get(key, fetcher, options)` — explicit get-or-set pattern.
@@ -2899,7 +2951,8 @@ var CacheStack = class extends import_node_events.EventEmitter {
               return promise;
             }
             if (existing.fetch !== entry.fetch || existing.optionsSignature !== optionsSignature) {
-              throw new Error(`mget received conflicting entries for key "${entry.key}".`);
+              const displayKey = entry.key.length > 64 ? `${entry.key.slice(0, 64)}...` : entry.key;
+              throw new Error(`mget received conflicting entries for key "${displayKey}".`);
             }
             return existing.promise;
           })
@@ -3229,12 +3282,15 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.handleInvalidationMessage(message);
     });
   }
-  async fetchWithGuards(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
+  async fetchWithGuards(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, initialMissConfirmed = false) {
     const fetchTask = async () => {
-      const secondHit = await this.readFromLayers(key, options, "fresh-only");
-      if (secondHit.found) {
-        this.metricsCollector.increment("hits");
-        return secondHit.value;
+      const shouldRecheckFreshLayers = !(initialMissConfirmed && this.options.singleFlightCoordinator);
+      if (shouldRecheckFreshLayers) {
+        const secondHit = await this.readFromLayers(key, options, "fresh-only");
+        if (secondHit.found) {
+          this.metricsCollector.increment("hits");
+          return secondHit.value;
+        }
       }
       return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch);
     };
@@ -3242,12 +3298,22 @@ var CacheStack = class extends import_node_events.EventEmitter {
       if (!this.options.singleFlightCoordinator) {
         return fetchTask();
       }
-      return this.options.singleFlightCoordinator.execute(
-        key,
-        this.resolveSingleFlightOptions(),
-        fetchTask,
-        () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch)
-      );
+      try {
+        return await this.options.singleFlightCoordinator.execute(
+          key,
+          this.resolveSingleFlightOptions(),
+          fetchTask,
+          () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch)
+        );
+      } catch (error) {
+        if (!this.isGracefulDegradationEnabled()) {
+          throw error;
+        }
+        this.metricsCollector.increment("degradedOperations");
+        this.logger.warn?.("single-flight-coordinator-degraded", { key, error: this.formatError(error) });
+        this.emitError("single-flight", { key, degraded: true, error: this.formatError(error) });
+        return fetchTask();
+      }
     };
     if (this.options.stampedePrevention === false) {
       return singleFlightTask();

package/packages/nestjs/dist/index.d.cts

@@ -169,6 +169,8 @@ interface CacheStackOptions {
     logger?: CacheLogger | boolean;
     metrics?: boolean;
     stampedePrevention?: boolean;
+    stampedeMaxInFlight?: number;
+    stampedeEntryTimeoutMs?: number;
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
     generation?: number;

package/packages/nestjs/dist/index.d.ts

@@ -169,6 +169,8 @@ interface CacheStackOptions {
     logger?: CacheLogger | boolean;
     metrics?: boolean;
     stampedePrevention?: boolean;
+    stampedeMaxInFlight?: number;
+    stampedeEntryTimeoutMs?: number;
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
     generation?: number;

package/packages/nestjs/dist/index.js

@@ -705,15 +705,14 @@ function createInstanceId() {
   if (globalThis.crypto?.randomUUID) {
     return globalThis.crypto.randomUUID();
   }
-  const bytes = new Uint8Array(16);
   if (globalThis.crypto?.getRandomValues) {
+    const bytes = new Uint8Array(16);
     globalThis.crypto.getRandomValues(bytes);
-  } else {
-    for (let i = 0; i < bytes.length; i += 1) {
-      bytes[i] = Math.floor(Math.random() * 256);
-    }
+    return `layercache-${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
   }
-  return `layercache-${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+  throw new Error(
+    "layercache requires a cryptographic random source. Neither crypto.randomUUID nor crypto.getRandomValues is available in this runtime."
+  );
 }
 
 // ../../src/internal/CacheStackGeneration.ts
@@ -1692,7 +1691,8 @@ var CircuitBreakerManager = class {
     }
     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).`);
+    const displayKey = key.length > 64 ? `${key.slice(0, 64)}...` : key;
+    throw new Error(`Circuit breaker is open for key "${displayKey}" (resets in ${remainingSecs}s).`);
   }
   recordFailure(key, options) {
     if (!options) {
@@ -2457,7 +2457,14 @@ var JsonSerializer = class {
   }
   deserialize(payload) {
     const normalized = Buffer.isBuffer(payload) ? payload.toString("utf8") : payload;
-    return sanitizeStructuredData(JSON.parse(normalized), {
+    let parsed;
+    try {
+      parsed = JSON.parse(normalized);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`JsonSerializer: failed to parse JSON payload: ${message}`);
+    }
+    return sanitizeStructuredData(parsed, {
       label: "JSON payload",
       maxDepth: 200,
       maxNodes: 1e4
@@ -2467,27 +2474,68 @@ var JsonSerializer = class {
 
 // ../../src/stampede/StampedeGuard.ts
 var StampedeGuard = class {
-  mutexes = /* @__PURE__ */ new Map();
+  inFlight = /* @__PURE__ */ new Map();
+  maxInFlight;
+  entryTimeoutMs;
+  constructor(options = {}) {
+    this.maxInFlight = options.maxInFlight ?? 1e4;
+    this.entryTimeoutMs = options.entryTimeoutMs;
+  }
   async execute(key, task) {
-    const entry = this.getMutexEntry(key);
+    const existing = this.inFlight.get(key);
+    if (existing) {
+      existing.references += 1;
+      try {
+        return await existing.promise;
+      } finally {
+        this.releaseEntry(key, existing);
+      }
+    }
+    if (this.inFlight.size >= this.maxInFlight) {
+      throw new Error(
+        `StampedeGuard: in-flight limit of ${this.maxInFlight} exceeded. Rejecting new key to prevent memory exhaustion.`
+      );
+    }
+    const taskPromise = Promise.resolve().then(task);
+    const guardedPromise = this.entryTimeoutMs ? this.withTimeout(key, taskPromise, this.entryTimeoutMs) : taskPromise;
+    const entry = {
+      promise: guardedPromise,
+      references: 1
+    };
+    this.inFlight.set(key, entry);
     try {
-      return await entry.mutex.runExclusive(task);
+      return await entry.promise;
     } finally {
-      entry.references -= 1;
-      const current = this.mutexes.get(key);
-      if (current === entry && entry.references === 0 && !entry.mutex.isLocked()) {
-        this.mutexes.delete(key);
-      }
+      this.releaseEntry(key, entry);
     }
   }
-  getMutexEntry(key) {
-    let entry = this.mutexes.get(key);
-    if (!entry) {
-      entry = { mutex: new Mutex(), references: 0 };
-      this.mutexes.set(key, entry);
+  withTimeout(key, promise, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(
+          new Error(
+            `StampedeGuard: task for key "${key.slice(0, 64)}${key.length > 64 ? "..." : ""}" timed out after ${timeoutMs}ms.`
+          )
+        );
+      }, timeoutMs);
+      promise.then(
+        (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        (error) => {
+          clearTimeout(timer);
+          reject(error);
+        }
+      );
+    });
+  }
+  releaseEntry(key, entry) {
+    entry.references -= 1;
+    const current = this.inFlight.get(key);
+    if (current === entry && entry.references === 0) {
+      this.inFlight.delete(key);
     }
-    entry.references += 1;
-    return entry;
   }
 };
 
@@ -2547,6 +2595,10 @@ var CacheStack = class extends EventEmitter {
     const maxProfileEntries = options.maxProfileEntries ?? DEFAULT_MAX_PROFILE_ENTRIES;
     this.ttlResolver = new TtlResolver({ maxProfileEntries });
     this.circuitBreakerManager = new CircuitBreakerManager({ maxEntries: maxProfileEntries });
+    this.stampedeGuard = new StampedeGuard({
+      maxInFlight: options.stampedeMaxInFlight,
+      entryTimeoutMs: options.stampedeEntryTimeoutMs
+    });
     this.currentGeneration = options.generation;
     if (options.publishSetInvalidation !== void 0) {
       console.warn(
@@ -2625,7 +2677,7 @@ var CacheStack = class extends EventEmitter {
   }
   layers;
   options;
-  stampedeGuard = new StampedeGuard();
+  stampedeGuard;
   metricsCollector = new MetricsCollector();
   instanceId = createInstanceId();
   startup;
@@ -2702,7 +2754,7 @@ var CacheStack = class extends EventEmitter {
     if (!fetcher) {
       return null;
     }
-    return this.fetchWithGuards(normalizedKey, fetcher, options);
+    return this.fetchWithGuards(normalizedKey, fetcher, options, void 0, void 0, true);
   }
   /**
    * Alias for `get(key, fetcher, options)` — explicit get-or-set pattern.
@@ -2863,7 +2915,8 @@ var CacheStack = class extends EventEmitter {
               return promise;
             }
             if (existing.fetch !== entry.fetch || existing.optionsSignature !== optionsSignature) {
-              throw new Error(`mget received conflicting entries for key "${entry.key}".`);
+              const displayKey = entry.key.length > 64 ? `${entry.key.slice(0, 64)}...` : entry.key;
+              throw new Error(`mget received conflicting entries for key "${displayKey}".`);
             }
             return existing.promise;
           })
@@ -3193,12 +3246,15 @@ var CacheStack = class extends EventEmitter {
       await this.handleInvalidationMessage(message);
     });
   }
-  async fetchWithGuards(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
+  async fetchWithGuards(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, initialMissConfirmed = false) {
     const fetchTask = async () => {
-      const secondHit = await this.readFromLayers(key, options, "fresh-only");
-      if (secondHit.found) {
-        this.metricsCollector.increment("hits");
-        return secondHit.value;
+      const shouldRecheckFreshLayers = !(initialMissConfirmed && this.options.singleFlightCoordinator);
+      if (shouldRecheckFreshLayers) {
+        const secondHit = await this.readFromLayers(key, options, "fresh-only");
+        if (secondHit.found) {
+          this.metricsCollector.increment("hits");
+          return secondHit.value;
+        }
       }
       return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch);
     };
@@ -3206,12 +3262,22 @@ var CacheStack = class extends EventEmitter {
       if (!this.options.singleFlightCoordinator) {
         return fetchTask();
       }
-      return this.options.singleFlightCoordinator.execute(
-        key,
-        this.resolveSingleFlightOptions(),
-        fetchTask,
-        () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch)
-      );
+      try {
+        return await this.options.singleFlightCoordinator.execute(
+          key,
+          this.resolveSingleFlightOptions(),
+          fetchTask,
+          () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch)
+        );
+      } catch (error) {
+        if (!this.isGracefulDegradationEnabled()) {
+          throw error;
+        }
+        this.metricsCollector.increment("degradedOperations");
+        this.logger.warn?.("single-flight-coordinator-degraded", { key, error: this.formatError(error) });
+        this.emitError("single-flight", { key, degraded: true, error: this.formatError(error) });
+        return fetchTask();
+      }
     };
     if (this.options.stampedePrevention === false) {
       return singleFlightTask();