actly 1.1.5 → 1.3.0

package/dist/policies/cache.cjs

@@ -2,105 +2,122 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cachePolicy = cachePolicy;
 const base_js_1 = require("../stores/base.js");
+const safeCall_js_1 = require("../utils/safeCall.js");
+const abort_js_1 = require("../utils/abort.js");
+const limits_js_1 = require("../utils/limits.js");
 const NS = 'cache:';
-const INFLIGHT_NS = '__inflight:cache:';
-/**
- * Short-circuit the entire downstream chain on a cache hit.
- * On a miss, run `fn` and store the result with TTL.
- *
- * # Single-flight (fixes cache stampede)
- *
- * On a sync store, the policy also stores the in-flight Promise under a
- * separate `__inflight:cache:<key>` slot. Concurrent callers that miss the
- * cache but find an in-flight Promise join it instead of launching duplicate
- * work. This is the same mechanism `dedupePolicy` uses, applied internally
- * to cache misses so users don't need to combine `cache` + `dedupe` to
- * avoid stampedes.
- *
- * On an async store, single-flight is not possible (the same sync-store
- * constraint as dedupe applies). Stampedes are a known limitation — document
- * and pair with dedupe at a higher layer if you need single-flight semantics.
- *
- * # Fail-open writes
- *
- * If `store.set()` throws (e.g. Redis transient error), we swallow the error
- * and return the value anyway. The caller gets their result; the next call
- * will simply re-run `fn` and try to cache again. Caching is an optimisation,
- * not a correctness requirement.
- *
- * # Cache hit semantics
- *
- * On a cache hit, `meta.source` is set to `'cache'` and `meta.attempts` is
- * set to `0` — no work was performed. (v1.1.0 reported `attempts: 1` on
- * cache hits, which was inconsistent with the documented meaning of
- * `attempts`. v1.1.5 fixes this.)
- *
- * Failures are NEVER cached. Only successful values are stored.
- */
+const INFLIGHT_NS = 'inflight:cache:';
+let generationCounter = 0;
+function nextGeneration() {
+    generationCounter = (generationCounter + 1) % Number.MAX_SAFE_INTEGER;
+    return generationCounter;
+}
 function cachePolicy(opts) {
     return (fn, ctx) => async (signal) => {
+        if (signal.aborted)
+            return Promise.reject(signal.reason);
         const key = NS + ctx.key;
         const inflightKey = INFLIGHT_NS + ctx.key;
-        // ─── Sync store: fast path with single-flight ────────────────────────
         if ((0, base_js_1.isSyncStore)(ctx.store)) {
-            // 1. Cache hit?
-            const hit = ctx.store.get(key);
+            const store = ctx.store;
+            const obs = ctx.observability;
+            const hit = store.get(key);
             if (hit) {
                 ctx.meta.source = 'cache';
                 ctx.meta.attempts = 0;
+                if (obs) {
+                    const ageMs = Date.now() - hit.insertedAt;
+                    (0, safeCall_js_1.safeCall)(obs.hooks.onCacheHit, {
+                        type: 'cache-hit', key: ctx.key, traceId: obs.traceId,
+                        timestamp: Date.now(), ageMs: Math.max(0, ageMs),
+                    });
+                }
                 return hit.value;
             }
-            // 2. In-flight single-flight hit? Join it.
-            const inflight = ctx.store.get(inflightKey);
-            if (inflight)
-                return inflight;
-            // 3. Originator: launch fn, cache on success (fail-open).
-            const promise = Promise.resolve(fn(signal)).then((value) => {
+            if (obs) {
+                (0, safeCall_js_1.safeCall)(obs.hooks.onCacheMiss, {
+                    type: 'cache-miss', key: ctx.key, traceId: obs.traceId,
+                    timestamp: Date.now(),
+                });
+            }
+            const inflight = store.get(inflightKey);
+            if (inflight) {
+                try {
+                    const value = await (0, abort_js_1.raceAbort)(inflight.promise, signal);
+                    ctx.meta.attempts = inflight.meta.attempts;
+                    ctx.meta.source = inflight.meta.source;
+                    return value;
+                }
+                catch (err) {
+                    if (signal.aborted) {
+                        ctx.meta.attempts = 0;
+                    }
+                    else {
+                        ctx.meta.attempts = inflight.meta.attempts;
+                        ctx.meta.source = inflight.meta.source;
+                    }
+                    throw err;
+                }
+            }
+            const generation = nextGeneration();
+            const rawPromise = Promise.resolve(fn(signal)).then((value) => {
                 try {
-                    ctx.store.set(key, { value }, opts.ttl);
+                    store.set(key, { value, insertedAt: Date.now() }, opts.ttl);
                 }
                 catch {
-                    // Fail-open: cache write failure should not surface to caller.
-                    // The value is still valid; next call will just re-run fn.
                 }
                 return value;
             }, (err) => { throw err; });
-            // Try to publish the in-flight promise so concurrent callers can
-            // join (single-flight). If store.set throws, single-flight is
-            // disabled for this call — concurrent callers will all run fn.
-            // That's still correct, just less efficient.
             try {
-                ctx.store.set(inflightKey, promise);
-                // Cleanup the in-flight slot on settle. The `.catch(() => {})`
-                // suppresses the unhandled-rejection warning that would otherwise
-                // fire on the `.finally()` chain — the original `promise` (with
-                // its rejection) is returned to the caller, which has its own
-                // try/catch via act().
-                promise.finally(() => {
-                    try {
-                        ctx.store.delete(inflightKey);
-                    }
-                    catch { /* ignore */ }
-                }).catch(() => { });
+                store.set(inflightKey, { promise: rawPromise, generation, meta: ctx.meta }, limits_js_1.LIMITS.DEFAULT_INFLIGHT_TTL);
             }
             catch {
-                // Single-flight unavailable; proceed without publishing.
             }
-            return promise;
+            const cleanup = () => {
+                try {
+                    const current = store.get(inflightKey);
+                    if (current && current.generation === generation) {
+                        try {
+                            store.delete(inflightKey);
+                        }
+                        catch { }
+                    }
+                }
+                catch {
+                }
+            };
+            rawPromise.then(cleanup, cleanup).catch(() => { });
+            return (0, abort_js_1.raceAbort)(rawPromise, signal);
         }
-        // ─── Async store: no single-flight (race window unavoidable) ─────────
+        const obs = ctx.observability;
         const hit = await ctx.store.get(key);
+        if (signal.aborted)
+            return Promise.reject(signal.reason);
         if (hit) {
             ctx.meta.source = 'cache';
             ctx.meta.attempts = 0;
+            if (obs) {
+                const ageMs = Date.now() - hit.insertedAt;
+                (0, safeCall_js_1.safeCall)(obs.hooks.onCacheHit, {
+                    type: 'cache-hit', key: ctx.key, traceId: obs.traceId,
+                    timestamp: Date.now(), ageMs: Math.max(0, ageMs),
+                });
+            }
             return hit.value;
         }
+        if (obs) {
+            (0, safeCall_js_1.safeCall)(obs.hooks.onCacheMiss, {
+                type: 'cache-miss', key: ctx.key, traceId: obs.traceId,
+                timestamp: Date.now(),
+            });
+        }
         const value = await fn(signal);
+        if (signal.aborted)
+            return Promise.reject(signal.reason);
         try {
-            await ctx.store.set(key, { value }, opts.ttl);
+            await ctx.store.set(key, { value, insertedAt: Date.now() }, opts.ttl);
         }
         catch {
-            // Fail-open: see sync path comment.
         }
         return value;
     };

package/dist/policies/cache.d.ts

@@ -1,36 +1,3 @@
 import type { CacheOptions, PolicyApplier } from '../types/index.js';
-/**
- * Short-circuit the entire downstream chain on a cache hit.
- * On a miss, run `fn` and store the result with TTL.
- *
- * # Single-flight (fixes cache stampede)
- *
- * On a sync store, the policy also stores the in-flight Promise under a
- * separate `__inflight:cache:<key>` slot. Concurrent callers that miss the
- * cache but find an in-flight Promise join it instead of launching duplicate
- * work. This is the same mechanism `dedupePolicy` uses, applied internally
- * to cache misses so users don't need to combine `cache` + `dedupe` to
- * avoid stampedes.
- *
- * On an async store, single-flight is not possible (the same sync-store
- * constraint as dedupe applies). Stampedes are a known limitation — document
- * and pair with dedupe at a higher layer if you need single-flight semantics.
- *
- * # Fail-open writes
- *
- * If `store.set()` throws (e.g. Redis transient error), we swallow the error
- * and return the value anyway. The caller gets their result; the next call
- * will simply re-run `fn` and try to cache again. Caching is an optimisation,
- * not a correctness requirement.
- *
- * # Cache hit semantics
- *
- * On a cache hit, `meta.source` is set to `'cache'` and `meta.attempts` is
- * set to `0` — no work was performed. (v1.1.0 reported `attempts: 1` on
- * cache hits, which was inconsistent with the documented meaning of
- * `attempts`. v1.1.5 fixes this.)
- *
- * Failures are NEVER cached. Only successful values are stored.
- */
 export declare function cachePolicy<T>(opts: CacheOptions): PolicyApplier<T>;
 //# sourceMappingURL=cache.d.ts.map

package/dist/policies/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/policies/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,YAAY,EAAE,aAAa,EAAiB,MAAM,mBAAmB,CAAA;AAY1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,CAAC,CAAC,CAuEnE"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/policies/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,YAAY,EAAE,aAAa,EAAiB,MAAM,mBAAmB,CAAA;AAiD1F,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,CAAC,CAAC,CAqInE"}

package/dist/policies/cache.js

@@ -1,105 +1,121 @@
 import { isSyncStore } from '../stores/base.js';
+import { safeCall } from '../utils/safeCall.js';
+import { raceAbort } from '../utils/abort.js';
+import { LIMITS } from '../utils/limits.js';
 const NS = 'cache:';
-const INFLIGHT_NS = '__inflight:cache:';
-/**
- * Short-circuit the entire downstream chain on a cache hit.
- * On a miss, run `fn` and store the result with TTL.
- *
- * # Single-flight (fixes cache stampede)
- *
- * On a sync store, the policy also stores the in-flight Promise under a
- * separate `__inflight:cache:<key>` slot. Concurrent callers that miss the
- * cache but find an in-flight Promise join it instead of launching duplicate
- * work. This is the same mechanism `dedupePolicy` uses, applied internally
- * to cache misses so users don't need to combine `cache` + `dedupe` to
- * avoid stampedes.
- *
- * On an async store, single-flight is not possible (the same sync-store
- * constraint as dedupe applies). Stampedes are a known limitation — document
- * and pair with dedupe at a higher layer if you need single-flight semantics.
- *
- * # Fail-open writes
- *
- * If `store.set()` throws (e.g. Redis transient error), we swallow the error
- * and return the value anyway. The caller gets their result; the next call
- * will simply re-run `fn` and try to cache again. Caching is an optimisation,
- * not a correctness requirement.
- *
- * # Cache hit semantics
- *
- * On a cache hit, `meta.source` is set to `'cache'` and `meta.attempts` is
- * set to `0` — no work was performed. (v1.1.0 reported `attempts: 1` on
- * cache hits, which was inconsistent with the documented meaning of
- * `attempts`. v1.1.5 fixes this.)
- *
- * Failures are NEVER cached. Only successful values are stored.
- */
+const INFLIGHT_NS = 'inflight:cache:';
+let generationCounter = 0;
+function nextGeneration() {
+    generationCounter = (generationCounter + 1) % Number.MAX_SAFE_INTEGER;
+    return generationCounter;
+}
 export function cachePolicy(opts) {
     return (fn, ctx) => async (signal) => {
+        if (signal.aborted)
+            return Promise.reject(signal.reason);
         const key = NS + ctx.key;
         const inflightKey = INFLIGHT_NS + ctx.key;
-        // ─── Sync store: fast path with single-flight ────────────────────────
         if (isSyncStore(ctx.store)) {
-            // 1. Cache hit?
-            const hit = ctx.store.get(key);
+            const store = ctx.store;
+            const obs = ctx.observability;
+            const hit = store.get(key);
             if (hit) {
                 ctx.meta.source = 'cache';
                 ctx.meta.attempts = 0;
+                if (obs) {
+                    const ageMs = Date.now() - hit.insertedAt;
+                    safeCall(obs.hooks.onCacheHit, {
+                        type: 'cache-hit', key: ctx.key, traceId: obs.traceId,
+                        timestamp: Date.now(), ageMs: Math.max(0, ageMs),
+                    });
+                }
                 return hit.value;
             }
-            // 2. In-flight single-flight hit? Join it.
-            const inflight = ctx.store.get(inflightKey);
-            if (inflight)
-                return inflight;
-            // 3. Originator: launch fn, cache on success (fail-open).
-            const promise = Promise.resolve(fn(signal)).then((value) => {
+            if (obs) {
+                safeCall(obs.hooks.onCacheMiss, {
+                    type: 'cache-miss', key: ctx.key, traceId: obs.traceId,
+                    timestamp: Date.now(),
+                });
+            }
+            const inflight = store.get(inflightKey);
+            if (inflight) {
+                try {
+                    const value = await raceAbort(inflight.promise, signal);
+                    ctx.meta.attempts = inflight.meta.attempts;
+                    ctx.meta.source = inflight.meta.source;
+                    return value;
+                }
+                catch (err) {
+                    if (signal.aborted) {
+                        ctx.meta.attempts = 0;
+                    }
+                    else {
+                        ctx.meta.attempts = inflight.meta.attempts;
+                        ctx.meta.source = inflight.meta.source;
+                    }
+                    throw err;
+                }
+            }
+            const generation = nextGeneration();
+            const rawPromise = Promise.resolve(fn(signal)).then((value) => {
                 try {
-                    ctx.store.set(key, { value }, opts.ttl);
+                    store.set(key, { value, insertedAt: Date.now() }, opts.ttl);
                 }
                 catch {
-                    // Fail-open: cache write failure should not surface to caller.
-                    // The value is still valid; next call will just re-run fn.
                 }
                 return value;
             }, (err) => { throw err; });
-            // Try to publish the in-flight promise so concurrent callers can
-            // join (single-flight). If store.set throws, single-flight is
-            // disabled for this call — concurrent callers will all run fn.
-            // That's still correct, just less efficient.
             try {
-                ctx.store.set(inflightKey, promise);
-                // Cleanup the in-flight slot on settle. The `.catch(() => {})`
-                // suppresses the unhandled-rejection warning that would otherwise
-                // fire on the `.finally()` chain — the original `promise` (with
-                // its rejection) is returned to the caller, which has its own
-                // try/catch via act().
-                promise.finally(() => {
-                    try {
-                        ctx.store.delete(inflightKey);
-                    }
-                    catch { /* ignore */ }
-                }).catch(() => { });
+                store.set(inflightKey, { promise: rawPromise, generation, meta: ctx.meta }, LIMITS.DEFAULT_INFLIGHT_TTL);
             }
             catch {
-                // Single-flight unavailable; proceed without publishing.
             }
-            return promise;
+            const cleanup = () => {
+                try {
+                    const current = store.get(inflightKey);
+                    if (current && current.generation === generation) {
+                        try {
+                            store.delete(inflightKey);
+                        }
+                        catch { }
+                    }
+                }
+                catch {
+                }
+            };
+            rawPromise.then(cleanup, cleanup).catch(() => { });
+            return raceAbort(rawPromise, signal);
         }
-        // ─── Async store: no single-flight (race window unavoidable) ─────────
+        const obs = ctx.observability;
         const hit = await ctx.store.get(key);
+        if (signal.aborted)
+            return Promise.reject(signal.reason);
         if (hit) {
             ctx.meta.source = 'cache';
             ctx.meta.attempts = 0;
+            if (obs) {
+                const ageMs = Date.now() - hit.insertedAt;
+                safeCall(obs.hooks.onCacheHit, {
+                    type: 'cache-hit', key: ctx.key, traceId: obs.traceId,
+                    timestamp: Date.now(), ageMs: Math.max(0, ageMs),
+                });
+            }
             return hit.value;
         }
+        if (obs) {
+            safeCall(obs.hooks.onCacheMiss, {
+                type: 'cache-miss', key: ctx.key, traceId: obs.traceId,
+                timestamp: Date.now(),
+            });
+        }
         const value = await fn(signal);
+        if (signal.aborted)
+            return Promise.reject(signal.reason);
         try {
-            await ctx.store.set(key, { value }, opts.ttl);
+            await ctx.store.set(key, { value, insertedAt: Date.now() }, opts.ttl);
         }
         catch {
-            // Fail-open: see sync path comment.
         }
         return value;
     };
 }
-//# sourceMappingURL=cache.js.map

package/dist/policies/circuitBreaker.cjs

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.circuitBreakerPolicy = circuitBreakerPolicy;
+const executor_js_1 = require("../core/executor.js");
+const errors_js_1 = require("../errors.js");
+const abort_js_1 = require("../utils/abort.js");
+const NS = 'cb:';
+function getState(store, key, strategy) {
+    const existing = store.get(NS + key);
+    if (existing)
+        return existing;
+    if (strategy === 'count') {
+        return {
+            strategy: 'count',
+            outcomes: [],
+            index: 0,
+            failures: 0,
+            filled: 0,
+            isOpen: false,
+            openedAt: 0,
+            halfOpen: false,
+            lastFailureTime: 0,
+        };
+    }
+    return {
+        strategy: 'consecutive',
+        failures: 0,
+        lastFailureTime: 0,
+        isOpen: false,
+        openedAt: 0,
+        halfOpen: false,
+    };
+}
+function setState(store, key, state) {
+    store.set(NS + key, state);
+}
+function recordCountOutcome(state, success, windowSize) {
+    if (state.outcomes.length < windowSize) {
+        state.outcomes.push(success);
+        state.filled = state.outcomes.length;
+        if (!success)
+            state.failures++;
+        state.index = (state.index + 1) % windowSize;
+        return;
+    }
+    if (state.outcomes[state.index] === false)
+        state.failures--;
+    state.outcomes[state.index] = success;
+    if (!success)
+        state.failures++;
+    state.index = (state.index + 1) % windowSize;
+    state.filled = windowSize;
+}
+function countFailureRate(state) {
+    if (state.filled === 0)
+        return 0;
+    return state.failures / state.filled;
+}
+function resetCountState(state) {
+    state.outcomes = [];
+    state.index = 0;
+    state.failures = 0;
+    state.filled = 0;
+    state.isOpen = false;
+    state.openedAt = 0;
+    state.halfOpen = false;
+    state.lastFailureTime = 0;
+}
+function circuitBreakerPolicy(opts) {
+    const threshold = Math.max(1, Math.floor(opts.threshold));
+    const cooldownMs = opts.cooldownMs;
+    const resetTimeoutMs = opts.resetTimeoutMs ?? Number.POSITIVE_INFINITY;
+    const strategy = opts.strategy ?? 'consecutive';
+    const countSize = strategy === 'count' ? Math.max(1, Math.floor(opts.countSize ?? 100)) : 0;
+    const countThreshold = strategy === 'count'
+        ? Math.min(1, Math.max(0, opts.countThreshold ?? 0.5))
+        : 0;
+    const countMinimumCalls = strategy === 'count'
+        ? Math.max(1, Math.floor(opts.countMinimumCalls ?? countSize))
+        : 0;
+    const applier = (fn, ctx) => {
+        const syncCtx = ctx;
+        return async (signal) => {
+            const key = syncCtx.key;
+            const now = Date.now();
+            const state = getState(syncCtx.store, key, strategy);
+            if (state.isOpen) {
+                const elapsed = now - state.openedAt;
+                if (elapsed >= cooldownMs) {
+                    state.isOpen = false;
+                    state.halfOpen = true;
+                    setState(syncCtx.store, key, state);
+                }
+                else {
+                    throw new errors_js_1.CircuitBreakerOpenError(key, cooldownMs - elapsed);
+                }
+            }
+            else if (state.halfOpen) {
+                throw new errors_js_1.CircuitBreakerOpenError(key, 0);
+            }
+            if (now - state.lastFailureTime > resetTimeoutMs && state.lastFailureTime > 0) {
+                if (!state.halfOpen) {
+                    if (state.strategy === 'count') {
+                        resetCountState(state);
+                    }
+                    else {
+                        state.failures = 0;
+                        state.isOpen = false;
+                        state.openedAt = 0;
+                        state.halfOpen = false;
+                    }
+                    setState(syncCtx.store, key, state);
+                }
+            }
+            try {
+                const result = await fn(signal);
+                const updated = getState(syncCtx.store, key, strategy);
+                const wasHalfOpen = updated.halfOpen;
+                if (wasHalfOpen && updated.strategy === 'count') {
+                    resetCountState(updated);
+                }
+                else if (updated.strategy === 'count') {
+                    recordCountOutcome(updated, true, countSize);
+                }
+                else {
+                    updated.failures = 0;
+                }
+                if (wasHalfOpen) {
+                    updated.isOpen = false;
+                    updated.halfOpen = false;
+                }
+                const isIdle = updated.failures === 0 && !updated.isOpen && !updated.halfOpen;
+                if (isIdle) {
+                    syncCtx.store.delete(NS + key);
+                }
+                else {
+                    setState(syncCtx.store, key, updated);
+                }
+                return result;
+            }
+            catch (err) {
+                if (signal.aborted && ((0, abort_js_1.isAbortError)(err) || err === signal.reason)) {
+                    const updated = getState(syncCtx.store, key, strategy);
+                    if (updated.failures === 0 && !updated.isOpen && !updated.halfOpen) {
+                        syncCtx.store.delete(NS + key);
+                    }
+                    else {
+                        setState(syncCtx.store, key, updated);
+                    }
+                    throw err;
+                }
+                const updated = getState(syncCtx.store, key, strategy);
+                const wasHalfOpen = updated.halfOpen;
+                updated.lastFailureTime = Date.now();
+                updated.halfOpen = false;
+                if (updated.strategy === 'count') {
+                    recordCountOutcome(updated, false, countSize);
+                    const rate = countFailureRate(updated);
+                    const enoughCalls = updated.filled >= countMinimumCalls;
+                    if (wasHalfOpen || (enoughCalls && rate > countThreshold)) {
+                        updated.isOpen = true;
+                        updated.openedAt = Date.now();
+                    }
+                }
+                else {
+                    updated.failures++;
+                    if (updated.failures >= threshold || wasHalfOpen) {
+                        updated.isOpen = true;
+                        updated.openedAt = Date.now();
+                    }
+                }
+                setState(syncCtx.store, key, updated);
+                throw err;
+            }
+        };
+    };
+    applier[executor_js_1.REQUIRES_SYNC_STORE] = true;
+    return applier;
+}

package/dist/policies/circuitBreaker.d.ts

@@ -0,0 +1,3 @@
+import type { PolicyApplier, CircuitBreakerOptions } from '../types/index.js';
+export declare function circuitBreakerPolicy<T>(opts: CircuitBreakerOptions): PolicyApplier<T>;
+//# sourceMappingURL=circuitBreaker.d.ts.map

package/dist/policies/circuitBreaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuitBreaker.d.ts","sourceRoot":"","sources":["../../src/policies/circuitBreaker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AAoGnG,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,IAAI,EAAE,qBAAqB,GAAG,aAAa,CAAC,CAAC,CAAC,CAiIrF"}