layercache 1.2.9 → 1.3.0

package/dist/index.cjs

@@ -2306,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;
   }
 };
 
@@ -2543,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.
@@ -3034,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);
     };
@@ -3047,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();
@@ -4393,6 +4412,7 @@ var RedisLayer = class {
   compression;
   compressionThreshold;
   decompressionMaxBytes;
+  commandTimeoutMs;
   disconnectOnDispose;
   constructor(options) {
     this.client = options.client;
@@ -4405,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) {
@@ -4412,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;
     }
@@ -4426,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);
     }
@@ -4455,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;
     }
@@ -4489,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");
@@ -4503,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;
     }
@@ -4526,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");
   }
@@ -4549,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);
@@ -4560,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");
@@ -4592,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);
     }
@@ -4600,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];
@@ -4701,6 +4740,35 @@ 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
@@ -5151,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_crypto3.randomUUID)();
-    const acquired = await this.client.set(lockKey, token, "PX", options.leaseMs, "NX");
+    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 {
@@ -5167,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();
@@ -5178,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

package/dist/index.d.cts

@@ -203,6 +203,11 @@ interface RedisLayerOptions {
      * Prevents decompression bomb attacks. Defaults to 64 MiB.
      */
     decompressionMaxBytes?: number;
+    /**
+     * Per-command timeout in milliseconds for Redis round-trips.
+     * Slow commands reject so CacheStack can treat the layer as degraded.
+     */
+    commandTimeoutMs?: number;
     disconnectOnDispose?: boolean;
 }
 declare class RedisLayer implements CacheLayer {
@@ -217,6 +222,7 @@ declare class RedisLayer implements CacheLayer {
     private readonly compression?;
     private readonly compressionThreshold;
     private readonly decompressionMaxBytes;
+    private readonly commandTimeoutMs;
     private readonly disconnectOnDispose;
     constructor(options: RedisLayerOptions);
     get<T>(key: string): Promise<T | null>;
@@ -256,6 +262,8 @@ declare class RedisLayer implements CacheLayer {
      */
     private decodePayload;
     private decompressWithLimit;
+    private normalizeCommandTimeoutMs;
+    private runCommand;
 }
 
 interface DiskLayerOptions {
@@ -408,19 +416,23 @@ declare class MsgpackSerializer implements CacheSerializer {
 interface RedisSingleFlightCoordinatorOptions {
     client: Redis;
     prefix?: string;
+    commandTimeoutMs?: number;
 }
 declare class RedisSingleFlightCoordinator implements CacheSingleFlightCoordinator {
     private readonly client;
     private readonly prefix;
+    private readonly commandTimeoutMs;
     constructor(options: RedisSingleFlightCoordinatorOptions);
     execute<T>(key: string, options: CacheSingleFlightExecutionOptions, worker: () => Promise<T>, waiter: () => Promise<T>): Promise<T>;
     private startLeaseRenewal;
+    private normalizeCommandTimeoutMs;
+    private runCommand;
 }
 
 declare class StampedeGuard {
-    private readonly mutexes;
+    private readonly inFlight;
     execute<T>(key: string, task: () => Promise<T>): Promise<T>;
-    private getMutexEntry;
+    private releaseEntry;
 }
 
 /**

package/dist/index.d.ts

@@ -203,6 +203,11 @@ interface RedisLayerOptions {
      * Prevents decompression bomb attacks. Defaults to 64 MiB.
      */
     decompressionMaxBytes?: number;
+    /**
+     * Per-command timeout in milliseconds for Redis round-trips.
+     * Slow commands reject so CacheStack can treat the layer as degraded.
+     */
+    commandTimeoutMs?: number;
     disconnectOnDispose?: boolean;
 }
 declare class RedisLayer implements CacheLayer {
@@ -217,6 +222,7 @@ declare class RedisLayer implements CacheLayer {
     private readonly compression?;
     private readonly compressionThreshold;
     private readonly decompressionMaxBytes;
+    private readonly commandTimeoutMs;
     private readonly disconnectOnDispose;
     constructor(options: RedisLayerOptions);
     get<T>(key: string): Promise<T | null>;
@@ -256,6 +262,8 @@ declare class RedisLayer implements CacheLayer {
      */
     private decodePayload;
     private decompressWithLimit;
+    private normalizeCommandTimeoutMs;
+    private runCommand;
 }
 
 interface DiskLayerOptions {
@@ -408,19 +416,23 @@ declare class MsgpackSerializer implements CacheSerializer {
 interface RedisSingleFlightCoordinatorOptions {
     client: Redis;
     prefix?: string;
+    commandTimeoutMs?: number;
 }
 declare class RedisSingleFlightCoordinator implements CacheSingleFlightCoordinator {
     private readonly client;
     private readonly prefix;
+    private readonly commandTimeoutMs;
     constructor(options: RedisSingleFlightCoordinatorOptions);
     execute<T>(key: string, options: CacheSingleFlightExecutionOptions, worker: () => Promise<T>, waiter: () => Promise<T>): Promise<T>;
     private startLeaseRenewal;
+    private normalizeCommandTimeoutMs;
+    private runCommand;
 }
 
 declare class StampedeGuard {
-    private readonly mutexes;
+    private readonly inFlight;
     execute<T>(key: string, task: () => Promise<T>): Promise<T>;
-    private getMutexEntry;
+    private releaseEntry;
 }
 
 /**