@adaptic/utils 0.0.1003 → 0.0.1005

package/dist/index.mjs

@@ -63155,6 +63155,7 @@ class StampedeProtectedCache {
         coalescedRequests: 0,
         backgroundRefreshes: 0,
         refreshErrors: 0,
+        loadTimeouts: 0,
     };
     constructor(options) {
         this.options = {
@@ -63428,6 +63429,7 @@ class StampedeProtectedCache {
             coalescedRequests: this.stats.coalescedRequests,
             backgroundRefreshes: this.stats.backgroundRefreshes,
             refreshErrors: this.stats.refreshErrors,
+            loadTimeouts: this.stats.loadTimeouts,
         };
     }
     /**
@@ -63478,8 +63480,9 @@ class StampedeProtectedCache {
             this.options.logger.debug("Request coalesced", { key });
             return existingPromise;
         }
-        // Create new promise and store it
-        const promise = this.loadAndCache(key, loader, ttl);
+        // Create new promise and store it — bounded by loadTimeoutMs so a
+        // never-settling loader cannot pin the key (see loadWithTimeout).
+        const promise = this.loadWithTimeout(key, loader, ttl);
         this.pendingRefreshes.set(key, promise);
         try {
             const result = await promise;
@@ -63490,6 +63493,51 @@ class StampedeProtectedCache {
             this.pendingRefreshes.delete(key);
         }
     }
+    /**
+     * Race {@link loadAndCache} against the configured load timeout.
+     *
+     * On timeout: rejects with a typed timeout error, evicts the pending
+     * single-flight entry so the NEXT caller retries with a fresh loader
+     * (instead of coalescing onto the hung one), and attaches a settlement
+     * observer to the abandoned loader so its eventual resolution/rejection
+     * is logged rather than surfacing as an unhandled rejection.
+     */
+    async loadWithTimeout(key, loader, ttl) {
+        const timeoutMs = this.options.loadTimeoutMs ?? 30000;
+        const loadPromise = this.loadAndCache(key, loader, ttl);
+        let timeoutHandle;
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutHandle = setTimeout(() => {
+                this.stats.loadTimeouts++;
+                // Evict the pin so the next caller retries fresh.
+                this.pendingRefreshes.delete(key);
+                this.options.logger.warn("Cache loader timed out — pin evicted", {
+                    key,
+                    timeoutMs,
+                });
+                // Observe the abandoned loader; never let it become unhandled.
+                loadPromise
+                    .then(() => {
+                    this.options.logger.warn("Abandoned cache loader eventually resolved", { key });
+                })
+                    .catch((error) => {
+                    this.options.logger.warn("Abandoned cache loader eventually rejected", {
+                        key,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                });
+                reject(new Error(`StampedeProtectedCache loader timed out after ${timeoutMs}ms for key "${key}"`));
+            }, timeoutMs);
+        });
+        try {
+            return await Promise.race([loadPromise, timeoutPromise]);
+        }
+        finally {
+            if (timeoutHandle !== undefined) {
+                clearTimeout(timeoutHandle);
+            }
+        }
+    }
     /**
      * Load data and cache it
      */
@@ -63639,6 +63687,7 @@ const DEFAULT_CACHE_OPTIONS = {
     minJitter: 0.9, // 90%
     maxJitter: 1.1, // 110%
     enableBackgroundRefresh: true,
+    loadTimeoutMs: 30000, // 30s hard loader ceiling (anti-pinning)
 };
 
 /**