actly 1.2.0 → 1.3.0

package/dist/policies/circuitBreaker.cjs

@@ -5,27 +5,88 @@ 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) {
-    return store.get(NS + key) ?? { failures: 0, lastFailureTime: 0, isOpen: false, openedAt: 0, halfOpen: false };
+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();
-            // Read state synchronously and make decisions atomically
-            const state = getState(syncCtx.store, key);
+            const state = getState(syncCtx.store, key, strategy);
             if (state.isOpen) {
                 const elapsed = now - state.openedAt;
                 if (elapsed >= cooldownMs) {
-                    // Transition to half-open: allow only ONE probe call
                     state.isOpen = false;
                     state.halfOpen = true;
                     setState(syncCtx.store, key, state);
@@ -35,45 +96,78 @@ function circuitBreakerPolicy(opts) {
                 }
             }
             else if (state.halfOpen) {
-                // Another call is already probing — block this one
                 throw new errors_js_1.CircuitBreakerOpenError(key, 0);
             }
-            if (now - state.lastFailureTime > resetTimeoutMs && state.failures > 0) {
-                state.failures = 0;
-                setState(syncCtx.store, key, state);
+            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);
-                // Re-read state (it may have changed during await) and update atomically
-                const updated = getState(syncCtx.store, key);
-                updated.failures = 0;
-                updated.isOpen = false;
-                updated.halfOpen = false;
-                setState(syncCtx.store, key, updated);
+                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) {
-                // Signal aborts are not downstream failures — don't count them
-                if ((0, abort_js_1.isAbortError)(err) || (signal.aborted && err === signal.reason)) {
-                    const updated = getState(syncCtx.store, key);
-                    if (updated.halfOpen) {
-                        // Abort during half-open: probe didn't succeed or fail —
-                        // downstream health is still unknown. Go back to OPEN with
-                        // fresh cooldown so next call waits before probing again.
-                        updated.isOpen = true;
-                        updated.openedAt = Date.now();
-                        updated.halfOpen = false;
+                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);
                     }
-                    setState(syncCtx.store, key, updated);
                     throw err;
                 }
-                const updated = getState(syncCtx.store, key);
-                updated.failures++;
+                const updated = getState(syncCtx.store, key, strategy);
+                const wasHalfOpen = updated.halfOpen;
                 updated.lastFailureTime = Date.now();
                 updated.halfOpen = false;
-                if (updated.failures >= threshold) {
-                    updated.isOpen = true;
-                    updated.openedAt = Date.now();
+                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;

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

@@ -1 +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;AAwBnG,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,IAAI,EAAE,qBAAqB,GAAG,aAAa,CAAC,CAAC,CAAC,CA2ErF"}
+{"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"}

package/dist/policies/circuitBreaker.js

@@ -2,27 +2,88 @@ import { REQUIRES_SYNC_STORE } from '../core/executor.js';
 import { CircuitBreakerOpenError } from '../errors.js';
 import { isAbortError } from '../utils/abort.js';
 const NS = 'cb:';
-function getState(store, key) {
-    return store.get(NS + key) ?? { failures: 0, lastFailureTime: 0, isOpen: false, openedAt: 0, halfOpen: false };
+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;
+}
 export 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();
-            // Read state synchronously and make decisions atomically
-            const state = getState(syncCtx.store, key);
+            const state = getState(syncCtx.store, key, strategy);
             if (state.isOpen) {
                 const elapsed = now - state.openedAt;
                 if (elapsed >= cooldownMs) {
-                    // Transition to half-open: allow only ONE probe call
                     state.isOpen = false;
                     state.halfOpen = true;
                     setState(syncCtx.store, key, state);
@@ -32,45 +93,78 @@ export function circuitBreakerPolicy(opts) {
                 }
             }
             else if (state.halfOpen) {
-                // Another call is already probing — block this one
                 throw new CircuitBreakerOpenError(key, 0);
             }
-            if (now - state.lastFailureTime > resetTimeoutMs && state.failures > 0) {
-                state.failures = 0;
-                setState(syncCtx.store, key, state);
+            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);
-                // Re-read state (it may have changed during await) and update atomically
-                const updated = getState(syncCtx.store, key);
-                updated.failures = 0;
-                updated.isOpen = false;
-                updated.halfOpen = false;
-                setState(syncCtx.store, key, updated);
+                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) {
-                // Signal aborts are not downstream failures — don't count them
-                if (isAbortError(err) || (signal.aborted && err === signal.reason)) {
-                    const updated = getState(syncCtx.store, key);
-                    if (updated.halfOpen) {
-                        // Abort during half-open: probe didn't succeed or fail —
-                        // downstream health is still unknown. Go back to OPEN with
-                        // fresh cooldown so next call waits before probing again.
-                        updated.isOpen = true;
-                        updated.openedAt = Date.now();
-                        updated.halfOpen = false;
+                if (signal.aborted && (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);
                     }
-                    setState(syncCtx.store, key, updated);
                     throw err;
                 }
-                const updated = getState(syncCtx.store, key);
-                updated.failures++;
+                const updated = getState(syncCtx.store, key, strategy);
+                const wasHalfOpen = updated.halfOpen;
                 updated.lastFailureTime = Date.now();
                 updated.halfOpen = false;
-                if (updated.failures >= threshold) {
-                    updated.isOpen = true;
-                    updated.openedAt = Date.now();
+                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;
@@ -80,4 +174,3 @@ export function circuitBreakerPolicy(opts) {
     applier[REQUIRES_SYNC_STORE] = true;
     return applier;
 }
-//# sourceMappingURL=circuitBreaker.js.map

package/dist/policies/dedupe.cjs

@@ -3,91 +3,47 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.dedupePolicy = dedupePolicy;
 const executor_js_1 = require("../core/executor.js");
 const abort_js_1 = require("../utils/abort.js");
-// Namespace so dedupe keys never collide with cache keys in the shared store.
+const safeCall_js_1 = require("../utils/safeCall.js");
+const limits_js_1 = require("../utils/limits.js");
 const NS = 'dedupe:';
-/**
- * Module-level generation counter. Monotonic — guarantees uniqueness
- * across the lifetime of the process. Wraps at `Number.MAX_SAFE_INTEGER`
- * (which would take ~285 000 years at 1M increments/sec).
- */
 let generationCounter = 0;
 function nextGeneration() {
     generationCounter = (generationCounter + 1) % Number.MAX_SAFE_INTEGER;
     return generationCounter;
 }
-/**
- * Collapse concurrent calls that share the same key into one in-flight Promise.
- *
- * # Properties
- *
- *  - **Generation-safe cleanup**: stale originators never delete newer
- *    entries when `inflightTtl` triggers replacement.
- *  - **Joiner isolation**: originator's caller-signal abort does NOT
- *    propagate to joiners. Each joiner races the shared in-flight promise
- *    against their OWN signal only.
- *  - **Truthful joiner attempts**: joiners that abort before the originator
- *    settles report `attempts: 0` (they did no work), not the originator's
- *    in-progress count.
- *
- * # INVARIANT: requires SyncStateStore
- *
- * The read-then-write that makes deduplication work must happen in a single
- * synchronous frame. An async store would introduce an `await` between
- * `get()` and `set()`, letting two concurrent callers both see a miss and
- * both launch work. The `REQUIRES_SYNC_STORE` symbol on the returned
- * `PolicyApplier` lets `execute()` enforce this at runtime for JS callers
- * that bypass TypeScript.
- */
 function dedupePolicy(opts = { enabled: true }) {
-    const inflightTtl = opts.inflightTtl;
+    const inflightTtl = opts.inflightTtl ?? limits_js_1.LIMITS.DEFAULT_INFLIGHT_TTL;
     const applier = (fn, ctx) => {
-        // Cast is safe: execute() verifies isSyncStore(ctx.store) before calling
-        // any policy tagged with REQUIRES_SYNC_STORE.
         const syncCtx = ctx;
         return async (signal) => {
             const key = NS + syncCtx.key;
-            // ─── Fast path: an in-flight promise already exists. Join it. ──────
-            //
-            // The joiner races the in-flight promise against THEIR OWN signal.
-            // They do NOT inherit the originator's signal state — if the
-            // originator's caller cancels, joiners continue waiting (or get
-            // the eventual settled value).
             const existing = syncCtx.store.get(key);
             if (existing) {
+                const obs = syncCtx.observability;
+                if (obs) {
+                    obs.joinerCounter++;
+                    (0, safeCall_js_1.safeCall)(obs.hooks.onDedupeJoin, {
+                        type: 'dedupe-join', key: syncCtx.key, traceId: obs.traceId,
+                        timestamp: Date.now(), joinerPosition: obs.joinerCounter,
+                    });
+                }
                 try {
                     const value = await (0, abort_js_1.raceAbort)(existing.promise, signal);
-                    // Success — copy originator's final meta (attempts, source)
-                    // so the joiner's ActResult reflects the real effort.
                     syncCtx.meta.attempts = existing.meta.attempts;
                     syncCtx.meta.source = existing.meta.source;
                     return value;
                 }
                 catch (err) {
-                    // Joiner either aborted (their own signal) or got the
-                    // originator's settled error.
                     if (signal.aborted) {
-                        // Joiner's own signal aborted before originator settled.
-                        // They did no work — report `attempts: 0` (truthful).
                         syncCtx.meta.attempts = 0;
-                        // source stays 'fresh' (default) — joiner didn't read from cache
                     }
                     else {
-                        // Originator settled with failure — copy its final meta.
                         syncCtx.meta.attempts = existing.meta.attempts;
                         syncCtx.meta.source = existing.meta.source;
                     }
                     throw err;
                 }
             }
-            // ─── Originator path: start the work and publish the promise. ──────
-            //
-            // The stored promise is the RAW fn(signal) — NOT raceAbort-wrapped.
-            // This is critical: if we stored raceAbort(fn, signal), an
-            // originator signal abort would cause the stored promise to reject,
-            // which would propagate to all joiners. Instead:
-            //   - stored: raw fn(signal) — joiners await this
-            //   - originator's await: raceAbort(stored, signal) — originator
-            //     can bail out on their own signal without affecting joiners
             const generation = nextGeneration();
             const rawPromise = Promise.resolve(fn(signal));
             const entry = {
@@ -96,20 +52,17 @@ function dedupePolicy(opts = { enabled: true }) {
                 generation,
             };
             syncCtx.store.set(key, entry, inflightTtl);
-            // Cleanup on settle: only delete if generation matches. If a newer
-            // originator has replaced this entry (because inflightTtl expired),
-            // our cleanup is a no-op — the newer entry stays.
             const cleanup = () => {
-                const current = syncCtx.store.get(key);
-                if (current && current.generation === generation) {
-                    syncCtx.store.delete(key);
+                try {
+                    const current = syncCtx.store.get(key);
+                    if (current && current.generation === generation) {
+                        syncCtx.store.delete(key);
+                    }
+                }
+                catch {
                 }
             };
-            // Attach cleanup to the RAW promise (not the raceAbort-wrapped one)
-            // so cleanup runs whenever fn settles, regardless of originator abort.
-            rawPromise.then(cleanup, cleanup);
-            // Originator races the raw promise against their own signal —
-            // they can bail out without affecting joiners.
+            rawPromise.then(cleanup, cleanup).catch(() => { });
             return (0, abort_js_1.raceAbort)(rawPromise, signal);
         };
     };

package/dist/policies/dedupe.d.ts

@@ -1,26 +1,3 @@
 import type { PolicyApplier, DedupeOptions } from '../types/index.js';
-/**
- * Collapse concurrent calls that share the same key into one in-flight Promise.
- *
- * # Properties
- *
- *  - **Generation-safe cleanup**: stale originators never delete newer
- *    entries when `inflightTtl` triggers replacement.
- *  - **Joiner isolation**: originator's caller-signal abort does NOT
- *    propagate to joiners. Each joiner races the shared in-flight promise
- *    against their OWN signal only.
- *  - **Truthful joiner attempts**: joiners that abort before the originator
- *    settles report `attempts: 0` (they did no work), not the originator's
- *    in-progress count.
- *
- * # INVARIANT: requires SyncStateStore
- *
- * The read-then-write that makes deduplication work must happen in a single
- * synchronous frame. An async store would introduce an `await` between
- * `get()` and `set()`, letting two concurrent callers both see a miss and
- * both launch work. The `REQUIRES_SYNC_STORE` symbol on the returned
- * `PolicyApplier` lets `execute()` enforce this at runtime for JS callers
- * that bypass TypeScript.
- */
 export declare function dedupePolicy<T>(opts?: DedupeOptions): PolicyApplier<T>;
 //# sourceMappingURL=dedupe.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"dedupe.d.ts","sourceRoot":"","sources":["../../src/policies/dedupe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,aAAa,EAAE,MAAM,mBAAmB,CAAA;AA6D3F;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,GAAE,aAAiC,GAAG,aAAa,CAAC,CAAC,CAAC,CAqFzF"}
+{"version":3,"file":"dedupe.d.ts","sourceRoot":"","sources":["../../src/policies/dedupe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,aAAa,EAAE,MAAM,mBAAmB,CAAA;AA0D3F,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,GAAE,aAAiC,GAAG,aAAa,CAAC,CAAC,CAAC,CA6FzF"}