layercache 1.2.8 → 1.2.9

package/dist/index.js

@@ -440,7 +440,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}`;
@@ -671,6 +671,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;
     }
@@ -849,6 +850,7 @@ function planFreshReadPolicies({
 }
 
 // src/internal/CacheStackSnapshotManager.ts
+import { randomBytes } from "crypto";
 import { constants, promises as fs } from "fs";
 import path from "path";
 
@@ -948,6 +950,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 {
@@ -972,7 +1010,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);
         })
       );
@@ -982,7 +1029,7 @@ var CacheStackSnapshotManager = class {
     const targetPath = await validateSnapshotFilePath(filePath, "write", snapshotBaseDir);
     const tempPath = path.join(
       path.dirname(targetPath),
-      `.layercache-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`
+      `.layercache-${process.pid}-${Date.now()}-${randomBytes(8).toString("hex")}.tmp`
     );
     let handle;
     try {
@@ -1082,7 +1129,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)
+    });
   }
 };
 
@@ -1462,7 +1515,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?.();
+        }
       });
     }
   }
@@ -1504,6 +1563,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);
@@ -1733,38 +1795,6 @@ var TtlResolver = 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) {
@@ -1929,6 +1959,8 @@ var CacheStack = class extends 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,
@@ -1953,6 +1985,7 @@ var CacheStack = class extends EventEmitter {
   layerWriter;
   snapshots;
   backgroundRefreshes = /* @__PURE__ */ new Map();
+  backgroundRefreshAbort = /* @__PURE__ */ new Map();
   layerDegradedUntil = /* @__PURE__ */ new Map();
   maintenance = new CacheStackMaintenance();
   ttlResolver;
@@ -2197,7 +2230,7 @@ var CacheStack = class extends 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;
@@ -2214,6 +2247,9 @@ var CacheStack = class extends 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);
@@ -2469,7 +2505,25 @@ var CacheStack = class extends 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((resolve2) => {
+                timer = setTimeout(resolve2, 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()));
@@ -2736,15 +2790,19 @@ var CacheStack = class extends 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);
@@ -2847,7 +2905,7 @@ var CacheStack = class extends 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;
         }
@@ -2865,7 +2923,7 @@ var CacheStack = class extends 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();
@@ -3101,6 +3159,7 @@ var RedisInvalidationBus = class {
   logger;
   handlers = /* @__PURE__ */ new Set();
   sharedListener;
+  subscribePromise;
   constructor(options) {
     this.publisher = options.publisher;
     this.subscriber = options.subscriber ?? options.publisher.duplicate();
@@ -3108,15 +3167,27 @@ var RedisInvalidationBus = class {
     this.logger = options.logger;
   }
   async subscribe(handler) {
-    if (this.handlers.size === 0) {
-      const listener = (_channel, payload) => {
-        void this.dispatchToHandlers(payload);
-      };
-      this.sharedListener = listener;
-      this.subscriber.on("message", listener);
-      await this.subscriber.subscribe(this.channel);
+    const previousPromise = this.subscribePromise;
+    let resolveThis;
+    this.subscribePromise = new Promise((resolve2) => {
+      resolveThis = resolve2;
+    });
+    if (previousPromise) {
+      await previousPromise;
+    }
+    try {
+      if (this.handlers.size === 0) {
+        const listener = (_channel, payload) => {
+          void this.dispatchToHandlers(payload);
+        };
+        this.sharedListener = listener;
+        this.subscriber.on("message", listener);
+        await this.subscriber.subscribe(this.channel);
+      }
+      this.handlers.add(handler);
+    } finally {
+      resolveThis();
     }
-    this.handlers.add(handler);
     return async () => {
       this.handlers.delete(handler);
       if (this.handlers.size === 0 && this.sharedListener) {
@@ -3317,10 +3388,21 @@ function cacheGraphqlResolver(cache, prefix, resolver, options = {}) {
 }
 
 // src/integrations/opentelemetry.ts
+var MAX_SPANS = 1e4;
 function createOpenTelemetryPlugin(cache, tracer) {
   const spans = /* @__PURE__ */ new Map();
   const onStart = (event) => {
-    spans.set(event.id, tracer.startSpan(event.name, { attributes: event.attributes }));
+    try {
+      if (spans.size >= MAX_SPANS) {
+        const oldest = spans.keys().next().value;
+        if (oldest !== void 0) {
+          spans.get(oldest)?.end();
+          spans.delete(oldest);
+        }
+      }
+      spans.set(event.id, tracer.startSpan(event.name, { attributes: event.attributes }));
+    } catch {
+    }
   };
   const onEnd = (event) => {
     const span = spans.get(event.id);
@@ -3328,12 +3410,15 @@ function createOpenTelemetryPlugin(cache, tracer) {
       return;
     }
     spans.delete(event.id);
-    span.setAttribute?.("layercache.success", event.success);
-    if (event.result) {
-      span.setAttribute?.("layercache.result", event.result);
-    }
-    if (event.error !== void 0) {
-      span.recordException?.(event.error);
+    try {
+      span.setAttribute?.("layercache.success", event.success);
+      if (event.result) {
+        span.setAttribute?.("layercache.result", event.result);
+      }
+      if (event.error !== void 0) {
+        span.recordException?.(event.error);
+      }
+    } catch {
     }
     span.end();
   };
@@ -3711,7 +3796,7 @@ var RedisLayer = class {
 };
 
 // src/layers/DiskLayer.ts
-import { createHash } from "crypto";
+import { createHash, randomBytes as randomBytes2 } from "crypto";
 import { promises as fs2 } from "fs";
 import { join, resolve } from "path";
 var FILE_SCAN_CONCURRENCY = 32;
@@ -3764,7 +3849,7 @@ var DiskLayer = class {
       };
       const payload = this.serializer.serialize(entry);
       const targetPath = this.keyToPath(key);
-      const tempPath = `${targetPath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+      const tempPath = `${targetPath}.${process.pid}.${Date.now()}.${randomBytes2(8).toString("hex")}.tmp`;
       try {
         await fs2.writeFile(tempPath, payload);
         await fs2.rename(tempPath, targetPath);

package/package.json

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

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) {
@@ -2619,6 +2649,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 +2675,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;
@@ -2887,7 +2920,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 +2937,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 +3195,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()));
@@ -3426,15 +3480,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 +3595,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 +3613,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;