layercache 1.2.9 → 1.3.0

package/dist/index.js

@@ -1811,29 +1811,35 @@ var JsonSerializer = class {
 };
 
 // src/stampede/StampedeGuard.ts
-import { Mutex as Mutex2 } from "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 Mutex2(), 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;
   }
 };
 
@@ -2048,7 +2054,7 @@ var CacheStack = class extends EventEmitter {
     if (!fetcher) {
       return null;
     }
-    return this.fetchWithGuards(normalizedKey, fetcher, options);
+    return this.fetchWithGuards(normalizedKey, fetcher, options, void 0, void 0, true);
   }
   /**
    * Alias for `get(key, fetcher, options)` — explicit get-or-set pattern.
@@ -2539,12 +2545,15 @@ var CacheStack = class extends EventEmitter {
       await this.handleInvalidationMessage(message);
     });
   }
-  async fetchWithGuards(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
+  async fetchWithGuards(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, initialMissConfirmed = false) {
     const fetchTask = async () => {
-      const secondHit = await this.readFromLayers(key, options, "fresh-only");
-      if (secondHit.found) {
-        this.metricsCollector.increment("hits");
-        return secondHit.value;
+      const shouldRecheckFreshLayers = !(initialMissConfirmed && this.options.singleFlightCoordinator);
+      if (shouldRecheckFreshLayers) {
+        const secondHit = await this.readFromLayers(key, options, "fresh-only");
+        if (secondHit.found) {
+          this.metricsCollector.increment("hits");
+          return secondHit.value;
+        }
       }
       return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch);
     };
@@ -2552,12 +2561,22 @@ var CacheStack = class extends EventEmitter {
       if (!this.options.singleFlightCoordinator) {
         return fetchTask();
       }
-      return this.options.singleFlightCoordinator.execute(
-        key,
-        this.resolveSingleFlightOptions(),
-        fetchTask,
-        () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch)
-      );
+      try {
+        return await this.options.singleFlightCoordinator.execute(
+          key,
+          this.resolveSingleFlightOptions(),
+          fetchTask,
+          () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch)
+        );
+      } catch (error) {
+        if (!this.isGracefulDegradationEnabled()) {
+          throw error;
+        }
+        this.metricsCollector.increment("degradedOperations");
+        this.logger.warn?.("single-flight-coordinator-degraded", { key, error: this.formatError(error) });
+        this.emitError("single-flight", { key, degraded: true, error: this.formatError(error) });
+        return fetchTask();
+      }
     };
     if (this.options.stampedePrevention === false) {
       return singleFlightTask();
@@ -3485,6 +3504,7 @@ var RedisLayer = class {
   compression;
   compressionThreshold;
   decompressionMaxBytes;
+  commandTimeoutMs;
   disconnectOnDispose;
   constructor(options) {
     this.client = options.client;
@@ -3497,6 +3517,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) {
@@ -3504,7 +3525,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;
     }
@@ -3518,7 +3539,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);
     }
@@ -3547,33 +3568,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;
     }
@@ -3581,13 +3605,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");
@@ -3595,7 +3622,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;
     }
@@ -3618,14 +3645,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");
   }
@@ -3641,7 +3671,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);
@@ -3652,7 +3685,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");
@@ -3684,7 +3720,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);
     }
@@ -3692,12 +3728,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];
@@ -3793,6 +3832,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
@@ -4243,14 +4311,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 = 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 {
@@ -4259,7 +4332,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();
@@ -4270,11 +4343,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/package.json

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

@@ -2503,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;
   }
 };
 
@@ -2738,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.
@@ -3229,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);
     };
@@ -3242,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();

package/packages/nestjs/dist/index.js

@@ -2467,27 +2467,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;
   }
 };
 
@@ -2702,7 +2709,7 @@ var CacheStack = class extends EventEmitter {
     if (!fetcher) {
       return null;
     }
-    return this.fetchWithGuards(normalizedKey, fetcher, options);
+    return this.fetchWithGuards(normalizedKey, fetcher, options, void 0, void 0, true);
   }
   /**
    * Alias for `get(key, fetcher, options)` — explicit get-or-set pattern.
@@ -3193,12 +3200,15 @@ var CacheStack = class extends EventEmitter {
       await this.handleInvalidationMessage(message);
     });
   }
-  async fetchWithGuards(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
+  async fetchWithGuards(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, initialMissConfirmed = false) {
     const fetchTask = async () => {
-      const secondHit = await this.readFromLayers(key, options, "fresh-only");
-      if (secondHit.found) {
-        this.metricsCollector.increment("hits");
-        return secondHit.value;
+      const shouldRecheckFreshLayers = !(initialMissConfirmed && this.options.singleFlightCoordinator);
+      if (shouldRecheckFreshLayers) {
+        const secondHit = await this.readFromLayers(key, options, "fresh-only");
+        if (secondHit.found) {
+          this.metricsCollector.increment("hits");
+          return secondHit.value;
+        }
       }
       return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch);
     };
@@ -3206,12 +3216,22 @@ var CacheStack = class extends EventEmitter {
       if (!this.options.singleFlightCoordinator) {
         return fetchTask();
       }
-      return this.options.singleFlightCoordinator.execute(
-        key,
-        this.resolveSingleFlightOptions(),
-        fetchTask,
-        () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch)
-      );
+      try {
+        return await this.options.singleFlightCoordinator.execute(
+          key,
+          this.resolveSingleFlightOptions(),
+          fetchTask,
+          () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch)
+        );
+      } catch (error) {
+        if (!this.isGracefulDegradationEnabled()) {
+          throw error;
+        }
+        this.metricsCollector.increment("degradedOperations");
+        this.logger.warn?.("single-flight-coordinator-degraded", { key, error: this.formatError(error) });
+        this.emitError("single-flight", { key, degraded: true, error: this.formatError(error) });
+        return fetchTask();
+      }
     };
     if (this.options.stampedePrevention === false) {
       return singleFlightTask();