layercache 1.2.8 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "layercache",
-  "version": "1.2.8",
+  "version": "1.3.0",
   "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

@@ -724,7 +724,7 @@ function normalizeForSerialization(value) {
 }
 function serializeKeyPart(value) {
   if (typeof value === "string") {
-    return `s:${value}`;
+    return `s:${value.replace(/%/g, "%25").replace(/:/g, "%3A")}`;
   }
   if (typeof value === "number") {
     return `n:${value}`;
@@ -1113,6 +1113,7 @@ var CacheStackLayerWriter = class {
     }
     const results = await Promise.allSettled(operations.map((operation) => operation()));
     const failures = results.filter((result) => result.status === "rejected");
+    const degraded = results.filter((result) => result.status === "fulfilled");
     if (failures.length === 0) {
       return;
     }
@@ -1291,6 +1292,7 @@ function planFreshReadPolicies({
 }
 
 // ../../src/internal/CacheStackSnapshotManager.ts
+var import_node_crypto = require("crypto");
 var import_node_fs = require("fs");
 var import_node_path = __toESM(require("path"), 1);
 
@@ -1390,6 +1392,42 @@ async function readUtf8HandleWithLimit(handle, byteLimit) {
   return Buffer.concat(chunks).toString("utf8");
 }
 
+// ../../src/internal/StructuredDataSanitizer.ts
+var DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+function sanitizeStructuredData(value, options) {
+  return sanitizeValue(value, 0, { count: 0 }, options);
+}
+function sanitizeValue(value, depth, state, options) {
+  state.count += 1;
+  if (state.count > options.maxNodes) {
+    throw new Error(`${options.label} exceeds max node count of ${options.maxNodes}.`);
+  }
+  if (depth > options.maxDepth) {
+    throw new Error(`${options.label} exceeds max depth of ${options.maxDepth}.`);
+  }
+  if (Array.isArray(value)) {
+    const sanitized2 = [];
+    for (const entry of value) {
+      sanitized2.push(sanitizeValue(entry, depth + 1, state, options));
+    }
+    return sanitized2;
+  }
+  if (!isPlainObject(value)) {
+    return value;
+  }
+  const sanitized = options.createObject?.() ?? {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (DANGEROUS_KEYS.has(key)) {
+      continue;
+    }
+    sanitized[key] = sanitizeValue(entry, depth + 1, state, options);
+  }
+  return sanitized;
+}
+function isPlainObject(value) {
+  return Object.prototype.toString.call(value) === "[object Object]";
+}
+
 // ../../src/internal/CacheStackSnapshotManager.ts
 var DEFAULT_SNAPSHOT_IMPORT_BATCH_SIZE = 50;
 var CacheStackSnapshotManager = class {
@@ -1414,7 +1452,16 @@ var CacheStackSnapshotManager = class {
       const batch = normalizedEntries.slice(index, index + DEFAULT_SNAPSHOT_IMPORT_BATCH_SIZE);
       await Promise.all(
         batch.map(async (entry) => {
-          await Promise.all(this.options.layers.map((layer) => layer.set(entry.key, entry.value, entry.ttl)));
+          await Promise.all(
+            this.options.layers.map(async (layer) => {
+              if (this.options.shouldSkipLayer(layer)) return;
+              try {
+                await layer.set(entry.key, entry.value, entry.ttl);
+              } catch (error) {
+                await this.options.handleLayerFailure(layer, "write", error);
+              }
+            })
+          );
           await this.options.tagIndex.touch(entry.key);
         })
       );
@@ -1424,7 +1471,7 @@ var CacheStackSnapshotManager = class {
     const targetPath = await validateSnapshotFilePath(filePath, "write", snapshotBaseDir);
     const tempPath = import_node_path.default.join(
       import_node_path.default.dirname(targetPath),
-      `.layercache-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`
+      `.layercache-${process.pid}-${Date.now()}-${(0, import_node_crypto.randomBytes)(8).toString("hex")}.tmp`
     );
     let handle;
     try {
@@ -1524,7 +1571,13 @@ var CacheStackSnapshotManager = class {
     });
   }
   sanitizeSnapshotValue(value) {
-    return this.options.snapshotSerializer.deserialize(this.options.snapshotSerializer.serialize(value));
+    const roundTripped = this.options.snapshotSerializer.deserialize(this.options.snapshotSerializer.serialize(value));
+    return sanitizeStructuredData(roundTripped, {
+      label: "Snapshot value",
+      maxDepth: 64,
+      maxNodes: 1e4,
+      createObject: () => /* @__PURE__ */ Object.create(null)
+    });
   }
 };
 
@@ -1904,7 +1957,13 @@ var FetchRateLimiter = class {
           this.pendingBuckets.add(next.bucketKey);
         }
         this.cleanupBucket(next.bucketKey, bucket, next.options.intervalMs);
-        this.drain();
+        if (!this.drainTimer) {
+          this.drainTimer = setTimeout(() => {
+            this.drainTimer = void 0;
+            this.drain();
+          }, 0);
+          this.drainTimer.unref?.();
+        }
       });
     }
   }
@@ -1946,6 +2005,9 @@ var FetchRateLimiter = class {
     }
     if (this.buckets.size >= MAX_BUCKETS) {
       this.evictIdleBuckets();
+      if (this.buckets.size >= MAX_BUCKETS) {
+        throw new Error(`FetchRateLimiter bucket limit (${MAX_BUCKETS}) exceeded.`);
+      }
     }
     const bucket = { active: 0, startedAt: [] };
     this.buckets.set(bucketKey, bucket);
@@ -2424,38 +2486,6 @@ var TagIndex = class {
   }
 };
 
-// ../../src/internal/StructuredDataSanitizer.ts
-var DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
-function sanitizeStructuredData(value, options) {
-  return sanitizeValue(value, 0, { count: 0 }, options);
-}
-function sanitizeValue(value, depth, state, options) {
-  state.count += 1;
-  if (state.count > options.maxNodes) {
-    throw new Error(`${options.label} exceeds max node count of ${options.maxNodes}.`);
-  }
-  if (depth > options.maxDepth) {
-    throw new Error(`${options.label} exceeds max depth of ${options.maxDepth}.`);
-  }
-  if (Array.isArray(value)) {
-    return value.map((entry) => sanitizeValue(entry, depth + 1, state, options));
-  }
-  if (!isPlainObject(value)) {
-    return value;
-  }
-  const sanitized = options.createObject?.() ?? {};
-  for (const [key, entry] of Object.entries(value)) {
-    if (DANGEROUS_KEYS.has(key)) {
-      continue;
-    }
-    sanitized[key] = sanitizeValue(entry, depth + 1, state, options);
-  }
-  return sanitized;
-}
-function isPlainObject(value) {
-  return Object.prototype.toString.call(value) === "[object Object]";
-}
-
 // ../../src/serialization/JsonSerializer.ts
 var JsonSerializer = class {
   serialize(value) {
@@ -2473,27 +2503,34 @@ var JsonSerializer = class {
 
 // ../../src/stampede/StampedeGuard.ts
 var StampedeGuard = class {
-  mutexes = /* @__PURE__ */ new Map();
+  inFlight = /* @__PURE__ */ new Map();
   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);
+      }
+    }
+    const entry = {
+      promise: Promise.resolve().then(task),
+      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);
+  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;
   }
 };
 
@@ -2619,6 +2656,8 @@ var CacheStack = class extends import_node_events.EventEmitter {
       tagIndex: this.tagIndex,
       snapshotSerializer: this.snapshotSerializer,
       readLayerEntry: this.readLayerEntry.bind(this),
+      shouldSkipLayer: (layer) => this.shouldSkipLayer(layer),
+      handleLayerFailure: async (layer, operation, error) => this.handleLayerFailure(layer, operation, error),
       qualifyKey: this.qualifyKey.bind(this),
       stripQualifiedKey: this.stripQualifiedKey.bind(this),
       validateCacheKey,
@@ -2643,6 +2682,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
   layerWriter;
   snapshots;
   backgroundRefreshes = /* @__PURE__ */ new Map();
+  backgroundRefreshAbort = /* @__PURE__ */ new Map();
   layerDegradedUntil = /* @__PURE__ */ new Map();
   maintenance = new CacheStackMaintenance();
   ttlResolver;
@@ -2705,7 +2745,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.
@@ -2887,7 +2927,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
       }
       for (let layerIndex = 0; layerIndex < this.layers.length; layerIndex += 1) {
         const layer = this.layers[layerIndex];
-        if (!layer) continue;
+        if (!layer || this.shouldSkipLayer(layer)) continue;
         const keys = [...pending];
         if (keys.length === 0) {
           break;
@@ -2904,6 +2944,9 @@ var CacheStack = class extends import_node_events.EventEmitter {
             await layer.delete(key);
             continue;
           }
+          if (resolved.state === "stale-while-revalidate" || resolved.state === "stale-if-error") {
+            this.metricsCollector.increment("staleHits", indexesByKey.get(key)?.length ?? 1);
+          }
           await this.tagIndex.touch(key);
           await this.backfill(key, stored, layerIndex - 1);
           resultsByKey.set(key, resolved.value);
@@ -3159,7 +3202,25 @@ var CacheStack = class extends import_node_events.EventEmitter {
         await this.unsubscribeInvalidation?.();
         await this.flushWriteBehindQueue();
         await this.maintenance.waitForGenerationCleanup();
-        await Promise.allSettled([...this.backgroundRefreshes.values()]);
+        for (const key of this.backgroundRefreshAbort.keys()) {
+          this.backgroundRefreshAbort.set(key, true);
+        }
+        await Promise.allSettled(
+          [...this.backgroundRefreshes.values()].map((promise) => {
+            let timer;
+            return Promise.race([
+              promise,
+              new Promise((resolve) => {
+                timer = setTimeout(resolve, 5e3);
+                timer.unref?.();
+              })
+            ]).finally(() => {
+              if (timer) clearTimeout(timer);
+            });
+          })
+        );
+        this.backgroundRefreshes.clear();
+        this.backgroundRefreshAbort.clear();
         this.maintenance.disposeWriteBehindTimer();
         this.fetchRateLimiter.dispose();
         await Promise.allSettled(this.layers.map((layer) => layer.dispose?.() ?? Promise.resolve()));
@@ -3175,12 +3236,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);
     };
@@ -3188,12 +3252,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();
@@ -3426,15 +3500,19 @@ var CacheStack = class extends import_node_events.EventEmitter {
     }
     const clearEpoch = this.maintenance.currentClearEpoch();
     const keyEpoch = this.maintenance.currentKeyEpoch(key);
+    this.backgroundRefreshAbort.set(key, false);
     const refresh = (async () => {
       this.metricsCollector.increment("refreshes");
       try {
+        if (this.backgroundRefreshAbort.get(key)) return;
         await this.runBackgroundRefresh(key, fetcher, options, clearEpoch, keyEpoch);
       } catch (error) {
+        if (this.backgroundRefreshAbort.get(key)) return;
         this.metricsCollector.increment("refreshErrors");
         this.logger.debug?.("refresh-error", { key, error: this.formatError(error) });
       } finally {
         this.backgroundRefreshes.delete(key);
+        this.backgroundRefreshAbort.delete(key);
       }
     })();
     this.backgroundRefreshes.set(key, refresh);
@@ -3537,7 +3615,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
           timer.unref?.();
         })
       ]);
-      if (result && typeof result === "object" && "kind" in result) {
+      if (result !== null && result !== void 0 && typeof result === "object" && "kind" in result) {
         if (result.kind === "error") {
           throw result.error;
         }
@@ -3555,7 +3633,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
   }
   async observeOperation(name, attributes, execute) {
     const id = this.nextOperationId;
-    this.nextOperationId += 1;
+    this.nextOperationId = (this.nextOperationId + 1) % Number.MAX_SAFE_INTEGER;
     this.emit("operation-start", { id, name, attributes });
     try {
       const result = await execute();

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

@@ -443,6 +443,7 @@ declare class CacheStack extends EventEmitter {
     private readonly layerWriter;
     private readonly snapshots;
     private readonly backgroundRefreshes;
+    private readonly backgroundRefreshAbort;
     private readonly layerDegradedUntil;
     private readonly maintenance;
     private readonly ttlResolver;

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

@@ -443,6 +443,7 @@ declare class CacheStack extends EventEmitter {
     private readonly layerWriter;
     private readonly snapshots;
     private readonly backgroundRefreshes;
+    private readonly backgroundRefreshAbort;
     private readonly layerDegradedUntil;
     private readonly maintenance;
     private readonly ttlResolver;