layercache 1.2.8 → 1.3.0

package/dist/index.cjs

@@ -528,7 +528,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}`;
@@ -917,6 +917,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;
     }
@@ -1095,6 +1096,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);
 
@@ -1194,6 +1196,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 {
@@ -1218,7 +1256,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);
         })
       );
@@ -1228,7 +1275,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 {
@@ -1328,7 +1375,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)
+    });
   }
 };
 
@@ -1708,7 +1761,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?.();
+        }
       });
     }
   }
@@ -1750,6 +1809,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);
@@ -2228,38 +2290,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) {
@@ -2276,29 +2306,35 @@ var JsonSerializer = class {
 };
 
 // src/stampede/StampedeGuard.ts
-var import_async_mutex2 = require("async-mutex");
 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 import_async_mutex2.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;
   }
 };
 
@@ -2424,6 +2460,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,
@@ -2448,6 +2486,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;
@@ -2510,7 +2549,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.
@@ -2692,7 +2731,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;
@@ -2709,6 +2748,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);
@@ -2964,7 +3006,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((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()));
@@ -2980,12 +3040,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);
     };
@@ -2993,12 +3056,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();
@@ -3231,15 +3304,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);
@@ -3342,7 +3419,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;
         }
@@ -3360,7 +3437,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();
@@ -3596,6 +3673,7 @@ var RedisInvalidationBus = class {
   logger;
   handlers = /* @__PURE__ */ new Set();
   sharedListener;
+  subscribePromise;
   constructor(options) {
     this.publisher = options.publisher;
     this.subscriber = options.subscriber ?? options.publisher.duplicate();
@@ -3603,15 +3681,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) {
@@ -4037,10 +4127,21 @@ function normalizeUrl2(url) {
 }
 
 // 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);
@@ -4048,12 +4149,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();
   };
@@ -4308,6 +4412,7 @@ var RedisLayer = class {
   compression;
   compressionThreshold;
   decompressionMaxBytes;
+  commandTimeoutMs;
   disconnectOnDispose;
   constructor(options) {
     this.client = options.client;
@@ -4320,6 +4425,7 @@ var RedisLayer = class {
     this.compression = options.compression;
     this.compressionThreshold = options.compressionThreshold ?? 1024;
     this.decompressionMaxBytes = options.decompressionMaxBytes ?? 64 * 1024 * 1024;
+    this.commandTimeoutMs = this.normalizeCommandTimeoutMs(options.commandTimeoutMs);
     this.disconnectOnDispose = options.disconnectOnDispose ?? false;
   }
   async get(key) {
@@ -4327,7 +4433,7 @@ var RedisLayer = class {
     return unwrapStoredValue(payload);
   }
   async getEntry(key) {
-    const payload = await this.client.getBuffer(this.withPrefix(key));
+    const payload = await this.runCommand(`get("${key}")`, () => this.client.getBuffer(this.withPrefix(key)));
     if (payload === null) {
       return null;
     }
@@ -4341,7 +4447,7 @@ var RedisLayer = class {
     for (const key of keys) {
       pipeline.getBuffer(this.withPrefix(key));
     }
-    const results = await pipeline.exec();
+    const results = await this.runCommand(`mget(${keys.length})`, () => pipeline.exec());
     if (results === null) {
       return keys.map(() => null);
     }
@@ -4370,33 +4476,36 @@ var RedisLayer = class {
         pipeline.set(normalizedKey, payload);
       }
     }
-    await pipeline.exec();
+    await this.runCommand(`mset(${entries.length})`, () => pipeline.exec());
   }
   async set(key, value, ttl = this.defaultTtl) {
     const serialized = this.primarySerializer().serialize(value);
     const payload = await this.encodePayload(serialized);
     const normalizedKey = this.withPrefix(key);
     if (ttl && ttl > 0) {
-      await this.client.set(normalizedKey, payload, "EX", ttl);
+      await this.runCommand(`set("${key}")`, () => this.client.set(normalizedKey, payload, "EX", ttl));
       return;
     }
-    await this.client.set(normalizedKey, payload);
+    await this.runCommand(`set("${key}")`, () => this.client.set(normalizedKey, payload));
   }
   async delete(key) {
-    await this.client.del(this.withPrefix(key));
+    await this.runCommand(`delete("${key}")`, () => this.client.del(this.withPrefix(key)));
   }
   async deleteMany(keys) {
     if (keys.length === 0) {
       return;
     }
-    await this.client.del(...keys.map((key) => this.withPrefix(key)));
+    await this.runCommand(
+      `deleteMany(${keys.length})`,
+      () => this.client.del(...keys.map((key) => this.withPrefix(key)))
+    );
   }
   async has(key) {
-    const exists = await this.client.exists(this.withPrefix(key));
+    const exists = await this.runCommand(`has("${key}")`, () => this.client.exists(this.withPrefix(key)));
     return exists > 0;
   }
   async ttl(key) {
-    const remaining = await this.client.ttl(this.withPrefix(key));
+    const remaining = await this.runCommand(`ttl("${key}")`, () => this.client.ttl(this.withPrefix(key)));
     if (remaining < 0) {
       return null;
     }
@@ -4404,13 +4513,16 @@ var RedisLayer = class {
   }
   async size() {
     if (!this.prefix) {
-      return this.client.dbsize();
+      return this.runCommand("dbsize()", () => this.client.dbsize());
     }
     const pattern = `${this.prefix}*`;
     let cursor = "0";
     let count = 0;
     do {
-      const [nextCursor, keys] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount);
+      const [nextCursor, keys] = await this.runCommand(
+        `scan("${pattern}")`,
+        () => this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount)
+      );
       cursor = nextCursor;
       count += keys.length;
     } while (cursor !== "0");
@@ -4418,7 +4530,7 @@ var RedisLayer = class {
   }
   async ping() {
     try {
-      return await this.client.ping() === "PONG";
+      return await this.runCommand("ping()", () => this.client.ping()) === "PONG";
     } catch {
       return false;
     }
@@ -4441,14 +4553,17 @@ var RedisLayer = class {
     const pattern = `${this.prefix}*`;
     let cursor = "0";
     do {
-      const [nextCursor, keys] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount);
+      const [nextCursor, keys] = await this.runCommand(
+        `scan("${pattern}")`,
+        () => this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount)
+      );
       cursor = nextCursor;
       if (keys.length === 0) {
         continue;
       }
       for (let i = 0; i < keys.length; i += BATCH_DELETE_SIZE) {
         const batch = keys.slice(i, i + BATCH_DELETE_SIZE);
-        await this.client.del(...batch);
+        await this.runCommand(`clear-del(${batch.length})`, () => this.client.del(...batch));
       }
     } while (cursor !== "0");
   }
@@ -4464,7 +4579,10 @@ var RedisLayer = class {
     const pattern = `${this.prefix}*`;
     let cursor = "0";
     do {
-      const [nextCursor, keys] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount);
+      const [nextCursor, keys] = await this.runCommand(
+        `scan("${pattern}")`,
+        () => this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount)
+      );
       cursor = nextCursor;
       for (const key of keys) {
         await visitor(this.prefix ? key.slice(this.prefix.length) : key);
@@ -4475,7 +4593,10 @@ var RedisLayer = class {
     const matches = [];
     let cursor = "0";
     do {
-      const [nextCursor, keys] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount);
+      const [nextCursor, keys] = await this.runCommand(
+        `scan("${pattern}")`,
+        () => this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount)
+      );
       cursor = nextCursor;
       matches.push(...keys);
     } while (cursor !== "0");
@@ -4507,7 +4628,7 @@ var RedisLayer = class {
   }
   async deleteCorruptedKey(key) {
     try {
-      await this.client.del(this.withPrefix(key));
+      await this.runCommand(`deleteCorrupted("${key}")`, () => this.client.del(this.withPrefix(key)));
     } catch (deleteError) {
       console.warn(`[layercache] RedisLayer: failed to delete corrupted key "${key}"`, deleteError);
     }
@@ -4515,12 +4636,15 @@ var RedisLayer = class {
   async rewriteWithPrimarySerializer(key, value) {
     const serialized = this.primarySerializer().serialize(value);
     const payload = await this.encodePayload(serialized);
-    const ttl = await this.client.ttl(this.withPrefix(key));
+    const ttl = await this.runCommand(`rewrite-ttl("${key}")`, () => this.client.ttl(this.withPrefix(key)));
     if (ttl > 0) {
-      await this.client.set(this.withPrefix(key), payload, "EX", ttl);
+      await this.runCommand(
+        `rewrite-set("${key}")`,
+        () => this.client.set(this.withPrefix(key), payload, "EX", ttl)
+      );
       return;
     }
-    await this.client.set(this.withPrefix(key), payload);
+    await this.runCommand(`rewrite-set("${key}")`, () => this.client.set(this.withPrefix(key), payload));
   }
   primarySerializer() {
     const serializer = this.serializers[0];
@@ -4616,10 +4740,39 @@ var RedisLayer = class {
       source.pipe(decompressor);
     });
   }
+  normalizeCommandTimeoutMs(value) {
+    if (value === void 0) {
+      return void 0;
+    }
+    if (!Number.isFinite(value) || value <= 0) {
+      throw new Error("RedisLayer.commandTimeoutMs must be a positive number.");
+    }
+    return value;
+  }
+  async runCommand(operation, command) {
+    const promise = command();
+    if (!this.commandTimeoutMs) {
+      return promise;
+    }
+    let timer;
+    return Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          reject(new Error(`RedisLayer command ${operation} timed out after ${this.commandTimeoutMs}ms.`));
+        }, this.commandTimeoutMs);
+        timer.unref?.();
+      })
+    ]).finally(() => {
+      if (timer) {
+        clearTimeout(timer);
+      }
+    });
+  }
 };
 
 // src/layers/DiskLayer.ts
-var import_node_crypto = require("crypto");
+var import_node_crypto2 = require("crypto");
 var import_node_fs2 = require("fs");
 var import_node_path2 = require("path");
 var FILE_SCAN_CONCURRENCY = 32;
@@ -4672,7 +4825,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()}.${(0, import_node_crypto2.randomBytes)(8).toString("hex")}.tmp`;
       try {
         await import_node_fs2.promises.writeFile(tempPath, payload);
         await import_node_fs2.promises.rename(tempPath, targetPath);
@@ -4772,7 +4925,7 @@ var DiskLayer = class {
   async dispose() {
   }
   keyToPath(key) {
-    const hash = (0, import_node_crypto.createHash)("sha256").update(key).digest("hex");
+    const hash = (0, import_node_crypto2.createHash)("sha256").update(key).digest("hex");
     return (0, import_node_path2.join)(this.directory, `${hash}.lc`);
   }
   resolveDirectory(directory) {
@@ -5050,7 +5203,7 @@ var MsgpackSerializer = class {
 };
 
 // src/singleflight/RedisSingleFlightCoordinator.ts
-var import_node_crypto2 = require("crypto");
+var import_node_crypto3 = require("crypto");
 var RELEASE_SCRIPT = `
 if redis.call("get", KEYS[1]) == ARGV[1] then
   return redis.call("del", KEYS[1])
@@ -5066,14 +5219,19 @@ return 0
 var RedisSingleFlightCoordinator = class {
   client;
   prefix;
+  commandTimeoutMs;
   constructor(options) {
     this.client = options.client;
     this.prefix = options.prefix ?? "layercache:singleflight";
+    this.commandTimeoutMs = this.normalizeCommandTimeoutMs(options.commandTimeoutMs);
   }
   async execute(key, options, worker, waiter) {
     const lockKey = `${this.prefix}:${encodeURIComponent(key)}`;
-    const token = (0, import_node_crypto2.randomUUID)();
-    const acquired = await this.client.set(lockKey, token, "PX", options.leaseMs, "NX");
+    const token = (0, import_node_crypto3.randomUUID)();
+    const acquired = await this.runCommand(
+      `acquire("${key}")`,
+      () => this.client.set(lockKey, token, "PX", options.leaseMs, "NX")
+    );
     if (acquired === "OK") {
       const renewTimer = this.startLeaseRenewal(lockKey, token, options);
       try {
@@ -5082,7 +5240,7 @@ var RedisSingleFlightCoordinator = class {
         if (renewTimer) {
           clearInterval(renewTimer);
         }
-        await this.client.eval(RELEASE_SCRIPT, 1, lockKey, token);
+        await this.runCommand(`release("${key}")`, () => this.client.eval(RELEASE_SCRIPT, 1, lockKey, token));
       }
     }
     return waiter();
@@ -5093,11 +5251,45 @@ var RedisSingleFlightCoordinator = class {
       return void 0;
     }
     const timer = setInterval(() => {
-      void this.client.eval(RENEW_SCRIPT, 1, lockKey, token, String(options.leaseMs)).catch(() => void 0);
+      void this.runCommand(
+        `renew("${lockKey}")`,
+        () => this.client.eval(RENEW_SCRIPT, 1, lockKey, token, String(options.leaseMs))
+      ).catch(() => void 0);
     }, renewIntervalMs);
     timer.unref?.();
     return timer;
   }
+  normalizeCommandTimeoutMs(value) {
+    if (value === void 0) {
+      return void 0;
+    }
+    if (!Number.isFinite(value) || value <= 0) {
+      throw new Error("RedisSingleFlightCoordinator.commandTimeoutMs must be a positive number.");
+    }
+    return value;
+  }
+  async runCommand(operation, command) {
+    const promise = command();
+    if (!this.commandTimeoutMs) {
+      return promise;
+    }
+    let timer;
+    return Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          reject(
+            new Error(`RedisSingleFlightCoordinator command ${operation} timed out after ${this.commandTimeoutMs}ms.`)
+          );
+        }, this.commandTimeoutMs);
+        timer.unref?.();
+      })
+    ]).finally(() => {
+      if (timer) {
+        clearTimeout(timer);
+      }
+    });
+  }
 };
 
 // src/metrics/PrometheusExporter.ts