actly 1.1.5 → 1.3.0

package/dist/types/index.d.ts

@@ -1,233 +1,116 @@
-/**
- * The async function ACT wraps.
- *
- * Receives an {@link AbortSignal} that fires when:
- *  - the caller aborts via `options.signal`,
- *  - the per-attempt {@link TimeoutOptions} fires,
- *  - the operation-wide {@link ActOptions.totalTimeout} fires.
- *
- * Cooperative cancellation: pass `signal` through to `fetch`, `AbortController`,
- * database drivers, or any primitive that accepts one. If you ignore it, ACT
- * will still return promptly (the outer promise rejects), but the underlying
- * work will keep running in the background — leaking resources until it
- * settles on its own.
- *
- * Backwards compatible: `() => Promise<T>` is assignable to this type, so
- * existing call sites continue to compile and run. They simply forgo
- * cancellation.
- *
- * @example
- * // Cooperative
- * act('user:42', async (signal) => {
- *   return fetch(`/api/users/42`, { signal })
- * }, { timeout: { ms: 5_000 } })
- *
- * @example
- * // Legacy (still works, signal ignored)
- * act('user:42', () => fetchUser(42))
- */
 export type ActFn<T> = (signal: AbortSignal) => Promise<T> | T;
-/** Where a successful result came from. */
 export type ActSource = 'fresh' | 'cache';
 export interface ActSuccess<T> {
     ok: true;
     value: T;
     source: ActSource;
-    /**
-     * Number of attempts made before success.
-     *
-     * - Fresh success on first try: `1`
-     * - Fresh success after N retries: `N`
-     * - Cache hit: `0` (no work was performed)
-     * - Dedupe joiner: mirrors the originator's attempt count
-     */
     attempts: number;
+    traceId?: string;
+    durationMs?: number;
 }
 export interface ActFailure {
     ok: false;
     error: unknown;
-    /**
-     * Number of attempts made before final failure.
-     * For dedupe joiners: mirrors the originator's attempt count.
-     */
     attempts: number;
+    traceId?: string;
+    durationMs?: number;
 }
 export type ActResult<T> = ActSuccess<T> | ActFailure;
 export interface RetryOptions {
-    /**
-     * Total number of attempts including the first call.
-     * Must be an integer >= 1.
-     *
-     * `attempts: 1` is a no-op (equivalent to omitting `retry`); the policy
-     * is not added to the chain. This is intentional — adding a policy that
-     * never retries is pure overhead.
-     */
     attempts: number;
-    /**
-     * Base delay between attempts in milliseconds. Defaults to 0 (no delay).
-     * Must be a non-negative finite number.
-     */
     delayMs?: number;
-    /**
-     * How the base delay grows per attempt:
-     *  - `'none'`        -> always `delayMs`
-     *  - `'linear'`      -> `delayMs * attempt`
-     *  - `'exponential'` -> `delayMs * 2^(attempt-1)`
-     *
-     * The computed delay is then capped by {@link maxDelay} and jittered by
-     * {@link jitter} before being slept.
-     *
-     * Defaults to `'none'`.
-     */
     backoff?: 'none' | 'linear' | 'exponential';
-    /**
-     * Hard cap on the computed delay. Defaults to `Infinity`.
-     *
-     * Without a cap, `exponential` backoff with `delayMs: 1000` and
-     * `attempts: 10` would sleep 8.5 minutes between attempts 9 and 10
-     * (256 seconds). Set `maxDelay` to something sane (e.g. 30_000) to
-     * bound worst-case latency.
-     */
+    backoffFn?: (attempt: number, error: unknown, state: Record<string, unknown>) => number;
     maxDelay?: number;
-    /**
-     * Jitter strategy applied to the (post-`maxDelay`) delay.
-     *
-     *  - `'none'`         -> no jitter, return delay as-is
-     *  - `'full'`         -> `random() * delay`  (default; best for thundering-herd prevention)
-     *  - `'equal'`        -> `delay/2 + random() * delay/2`
-     *  - `'decorrelated'` -> `base + random() * (delay - base)`
-     *
-     * Defaults to `'full'`. Jitter prevents synchronised retry storms when
-     * many callers fail at the same instant (e.g. after an upstream outage
-     * recovers) — without it, all callers retry on the same tick.
-     */
     jitter?: 'none' | 'full' | 'equal' | 'decorrelated';
-    /**
-     * Predicate called after each failure, before the next attempt.
-     * Return `false` to stop retrying immediately and surface the error.
-     *
-     * Called for every failure including the last attempt (so observers stay
-     * informed); the return value is only consulted when there are remaining
-     * attempts.
-     *
-     * Use this to skip retries for errors that are definitively non-recoverable
-     * (e.g. HTTP 4xx, AuthError, ValidationError).
-     *
-     * Default behaviour: retry on every error except `AbortError` (which
-     * indicates the caller or a timeout cancelled the operation).
-     *
-     * @param error   The error thrown by the most recent attempt.
-     * @param attempt The 1-based number of the attempt that just failed.
-     */
     shouldRetry?: (error: unknown, attempt: number) => boolean;
+    shouldRetryResult?: <V>(value: V, attempt: number) => boolean;
+    dangerouslyUnref?: boolean;
 }
 export interface TimeoutOptions {
-    /**
-     * Abort after this many milliseconds.
-     * Must be a positive finite number.
-     */
     ms: number;
+    strategy?: 'race' | 'cooperative';
 }
 export interface DedupeOptions {
-    /**
-     * Collapse concurrent calls sharing the same key into one in-flight Promise.
-     * Opt-in: be explicit when you want this behaviour.
-     */
     enabled: boolean;
-    /**
-     * Safety-net TTL for the in-flight entry, in milliseconds.
-     *
-     * If the originator's promise does not settle within this window, the
-     * entry is removed from the store so subsequent callers can start fresh.
-     * Originator's promise continues in the background until it settles or
-     * an outer timeout fires.
-     *
-     * Default: `Infinity` (no safety net). Pair with `timeout` or
-     * `totalTimeout` for proper cancellation in production.
-     */
     inflightTtl?: number;
 }
 export interface CacheOptions {
-    /** Keep a successful result for this many milliseconds. Must be > 0. */
     ttl: number;
 }
-export interface ActOptions {
+export interface ActOptions<T = unknown> {
     retry?: RetryOptions;
-    /** Per-attempt deadline. Each retry gets a fresh clock. */
     timeout?: TimeoutOptions;
-    /**
-     * Collapse concurrent calls with the same key into one in-flight Promise.
-     *
-     * Shorthand:  `dedupe: true`
-     * Full form:  `dedupe: { enabled: true, inflightTtl: 30_000 }`
-     */
     dedupe?: boolean | DedupeOptions;
     cache?: CacheOptions;
-    /**
-     * Hard budget over the ENTIRE operation — including all retry attempts,
-     * delays, and the per-attempt timeout.
-     *
-     * Distinct from `timeout`, which resets the clock on every attempt.
-     * Use both together to express: "each attempt may take at most X ms,
-     * but the whole thing must finish within Y ms."
-     *
-     * Rejects with {@link TotalTimeoutError} if the budget fires.
-     */
     totalTimeout?: TimeoutOptions;
-    /**
-     * Caller-provided cancellation signal.
-     *
-     * When this signal aborts:
-     *  - if the operation has not yet started, it rejects immediately with
-     *    the signal's `reason`,
-     *  - if it is in progress, the inner {@link ActFn} receives an aborted
-     *    signal (cooperative cancellation),
-     *  - if it has already settled, the result is returned as normal.
-     *
-     * Combined with `timeout` / `totalTimeout`, this gives you full control
-     * over cancellation from outside `act()`.
-     */
     signal?: AbortSignal;
+    observability?: ObservabilityHooks;
+    traceId?: string;
+    circuitBreaker?: CircuitBreakerOptions;
+    bulkhead?: BulkheadOptions;
+    rateLimit?: RateLimitOptions;
+    hedge?: HedgeOptions;
+    fallback?: FallbackOptions<T>;
+    audit?: AuditOptions;
 }
-/**
- * Mutable bag mutated in-place during execution.
- * Policies annotate it; act() reads the final state to build ActResult.
- *
- * For dedupe joiners: the bag is copied from the originator's bag after the
- * in-flight promise settles (success or failure), so `attempts` reflects
- * the real effort, not the default `1`.
- */
+export interface CircuitBreakerOptions {
+    threshold: number;
+    cooldownMs: number;
+    resetTimeoutMs?: number;
+    strategy?: 'consecutive' | 'count';
+    countSize?: number;
+    countThreshold?: number;
+    countMinimumCalls?: number;
+}
+export interface BulkheadOptions {
+    maxConcurrent: number;
+    queueTimeoutMs?: number;
+    maxQueueSize?: number;
+}
+export interface RateLimitOptions {
+    maxCalls: number;
+    windowMs: number;
+}
+export interface HedgeOptions {
+    delayMs: number;
+    placement?: 'outside-retry' | 'inside-retry';
+    keepLoser?: boolean;
+}
+export interface FallbackOptions<T> {
+    value: T | (() => T | Promise<T>);
+}
+export interface AuditOptions {
+    log: (entry: AuditEntry) => void;
+}
+export interface AuditEntry {
+    key: string;
+    traceId: string;
+    timestamp: number;
+    durationMs: number;
+    ok: boolean;
+    attempts: number;
+    failedBy?: ActlyFailedBy;
+    error?: unknown;
+}
+export type ActlyFailedBy = 'abort' | 'timeout' | 'total-timeout' | 'retry-exhausted' | 'fn-error' | 'validation' | 'circuit-open' | 'bulkhead-full' | 'rate-limited' | 'resource-exhausted' | 'hedge-timeout';
 export interface RunMeta {
     attempts: number;
     source: ActSource;
 }
-/** Everything a policy receives about the current run. */
+export type { ObservabilityContext } from '../observability.js';
+import type { ObservabilityContext } from '../observability.js';
 export interface PolicyContext {
     key: string;
     store: AnyStateStore;
     meta: RunMeta;
+    observability?: ObservabilityContext;
 }
-/**
- * The ONLY shape the executor knows about policies.
- *
- * A policy wraps `ActFn<T>` and returns a new `ActFn<T>`. It may intercept
- * before, after, or instead of the inner call. The executor never imports
- * a concrete policy — only this type.
- */
 export type PolicyApplier<T> = (fn: ActFn<T>, ctx: PolicyContext) => ActFn<T>;
 import type { SyncStateStore, AsyncStateStore } from '../stores/base.js';
 export type { SyncStateStore, AsyncStateStore };
-/**
- * Public store type. v1.1+: alias for `SyncStateStore`.
- *
- * Kept for backwards compatibility — every v1.0 consumer typed against
- * `StateStore` continues to compile without changes. A future major version
- * may widen this to `SyncStateStore | AsyncStateStore`.
- */
+import type { ObservabilityHooks as ObsHooks } from '../observability.js';
+export type ObservabilityHooks = ObsHooks;
 export type StateStore = SyncStateStore;
-/**
- * Union of sync and async stores. Used internally by `PolicyContext` and
- * exported for consumers building custom policy chains or store adapters.
- */
 export type AnyStateStore = SyncStateStore | AsyncStateStore;
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}

package/dist/types/index.js

@@ -1,3 +1 @@
-// ─── Public surface ────────────────────────────────────────────────────────────
 export {};
-//# sourceMappingURL=index.js.map

package/dist/utils/abort.cjs

@@ -1,94 +1,71 @@
 "use strict";
-// ─── AbortSignal helpers ──────────────────────────────────────────────────────
-//
-// Centralised utilities for composing AbortSignals. These exist because
-// Node 18 lacks `AbortSignal.any` (added in Node 20) and we want to keep
-// the `engines` floor at 18 for backwards compatibility with existing
-// consumers.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.anySignal = anySignal;
 exports.raceAbort = raceAbort;
 exports.sleep = sleep;
 exports.isAbortError = isAbortError;
 exports.linkSignal = linkSignal;
-/**
- * Polyfill for `AbortSignal.any(signals)` (Node 20+).
- *
- * Returns a single signal that aborts when ANY of the input signals aborts,
- * with the same reason. If any input is already aborted, the returned signal
- * is aborted synchronously.
- *
- * Listener registration is `{ once: true }` — once any signal fires, we stop
- * listening on the others. The composite signal cannot be "un-aborted".
- */
+const NATIVE_ANY = AbortSignal.any;
 function anySignal(signals) {
-    // Fast path: native implementation (Node 20+, modern browsers, Bun).
-    // The cast is safe — the runtime check guards the call.
-    const native = AbortSignal.any;
-    if (typeof native === 'function')
-        return native.call(AbortSignal, signals);
-    // Polyfill for Node 18.
+    const filtered = signals.filter((s) => s != null);
+    if (filtered.length === 0)
+        return new AbortController().signal;
+    if (filtered.length === 1)
+        return filtered[0];
+    if (NATIVE_ANY)
+        return NATIVE_ANY.call(AbortSignal, filtered);
     const controller = new AbortController();
-    for (const signal of signals) {
+    const listeners = [];
+    for (const signal of filtered) {
         if (signal.aborted) {
             controller.abort(signal.reason);
             break;
         }
-        signal.addEventListener('abort', () => controller.abort(signal.reason), { once: true });
+        const onAbort = () => {
+            controller.abort(signal.reason);
+            for (const off of listeners)
+                off();
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        listeners.push(() => signal.removeEventListener('abort', onAbort));
+    }
+    if (controller.signal.aborted) {
+        for (const off of listeners)
+            off();
     }
     return controller.signal;
 }
-/**
- * Race a promise against an AbortSignal.
- *
- * - If the signal is already aborted, rejects immediately with `signal.reason`.
- * - If the signal aborts while the promise is pending, rejects with `signal.reason`.
- * - If the promise settles first, returns its value (or rejects with its error).
- *
- * The listener is registered with `{ once: true }` and never leaks: either
- * the signal fires (listener auto-removed) or the promise settles (the
- * signal will eventually be GC'd along with the listener).
- *
- * Used by `dedupePolicy` so joiners can cancel their own `await` even if the
- * originator's `fn` is still running.
- */
 function raceAbort(promise, signal) {
-    if (signal.aborted)
+    if (signal.aborted) {
+        promise.catch(() => { });
         return Promise.reject(signal.reason);
+    }
     return new Promise((resolve, reject) => {
         let settled = false;
         const onAbort = () => {
             if (settled)
                 return;
             settled = true;
+            signal.removeEventListener('abort', onAbort);
             reject(signal.reason);
         };
-        signal.addEventListener('abort', onAbort, { once: true });
+        signal.addEventListener('abort', onAbort);
         promise.then((value) => {
             if (settled)
                 return;
             settled = true;
+            signal.removeEventListener('abort', onAbort);
             resolve(value);
         }, (error) => {
             if (settled)
                 return;
             settled = true;
+            signal.removeEventListener('abort', onAbort);
             reject(error);
         });
     });
 }
-/**
- * Sleep for `ms` milliseconds, but abort early if `signal` fires.
- *
- * Resolves normally on timer expiry. Rejects with `signal.reason` if the
- * signal aborts before the timer fires. If the signal is already aborted
- * when called, rejects synchronously (in microtask).
- *
- * Used by `retryPolicy` to make backoff delays interruptible: when an outer
- * `totalTimeout` fires mid-delay, the delay rejects immediately instead of
- * blocking the retry loop until the timer would have elapsed.
- */
-function sleep(ms, signal) {
+function sleep(ms, signal, opts) {
     if (ms <= 0) {
         if (signal?.aborted)
             return Promise.reject(signal.reason);
@@ -101,42 +78,38 @@ function sleep(ms, signal) {
             signal?.removeEventListener('abort', onAbort);
             resolve();
         }, ms);
+        if (opts?.unref && typeof timer.unref === 'function') {
+            timer.unref();
+        }
         const onAbort = () => {
             clearTimeout(timer);
             reject(signal.reason);
         };
-        signal?.addEventListener('abort', onAbort, { once: true });
+        signal?.addEventListener('abort', onAbort);
     });
 }
-/**
- * True if `err` is an `AbortError` (DOMException name or Error name).
- *
- * The default `shouldRetry` predicate uses this to skip retrying on
- * cancellations — if the caller aborted, retrying would just abort again.
- */
 function isAbortError(err) {
     if (err == null || typeof err !== 'object')
         return false;
+    if (err.code === 'ACTLY_ABORT')
+        return true;
     const name = err.name;
-    return name === 'AbortError' || name === 'TimeoutError' &&
+    if (name === 'AbortError')
+        return true;
+    if (name === 'TimeoutError' &&
         err instanceof Error &&
-        // DOMException with name 'TimeoutError' is what AbortSignal.timeout throws.
-        // Distinguish from our own TimeoutError class by checking for DOMException.
         typeof DOMException !== 'undefined' &&
-        err instanceof DOMException;
+        err instanceof DOMException) {
+        return true;
+    }
+    return false;
 }
-/**
- * Link a parent signal to a child controller: when the parent aborts, the
- * child is aborted with the same reason. No-op if the parent is already
- * aborted (the caller should check `parent.aborted` separately if it cares
- * about synchronous abort).
- *
- * The listener is `{ once: true }` — no leak.
- */
 function linkSignal(parent, child) {
     if (parent.aborted) {
         child.abort(parent.reason);
-        return;
+        return () => { };
     }
-    parent.addEventListener('abort', () => child.abort(parent.reason), { once: true });
+    const onAbort = () => child.abort(parent.reason);
+    parent.addEventListener('abort', onAbort);
+    return () => parent.removeEventListener('abort', onAbort);
 }

package/dist/utils/abort.d.ts

@@ -1,55 +1,8 @@
-/**
- * Polyfill for `AbortSignal.any(signals)` (Node 20+).
- *
- * Returns a single signal that aborts when ANY of the input signals aborts,
- * with the same reason. If any input is already aborted, the returned signal
- * is aborted synchronously.
- *
- * Listener registration is `{ once: true }` — once any signal fires, we stop
- * listening on the others. The composite signal cannot be "un-aborted".
- */
 export declare function anySignal(signals: ReadonlyArray<AbortSignal>): AbortSignal;
-/**
- * Race a promise against an AbortSignal.
- *
- * - If the signal is already aborted, rejects immediately with `signal.reason`.
- * - If the signal aborts while the promise is pending, rejects with `signal.reason`.
- * - If the promise settles first, returns its value (or rejects with its error).
- *
- * The listener is registered with `{ once: true }` and never leaks: either
- * the signal fires (listener auto-removed) or the promise settles (the
- * signal will eventually be GC'd along with the listener).
- *
- * Used by `dedupePolicy` so joiners can cancel their own `await` even if the
- * originator's `fn` is still running.
- */
 export declare function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T>;
-/**
- * Sleep for `ms` milliseconds, but abort early if `signal` fires.
- *
- * Resolves normally on timer expiry. Rejects with `signal.reason` if the
- * signal aborts before the timer fires. If the signal is already aborted
- * when called, rejects synchronously (in microtask).
- *
- * Used by `retryPolicy` to make backoff delays interruptible: when an outer
- * `totalTimeout` fires mid-delay, the delay rejects immediately instead of
- * blocking the retry loop until the timer would have elapsed.
- */
-export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
-/**
- * True if `err` is an `AbortError` (DOMException name or Error name).
- *
- * The default `shouldRetry` predicate uses this to skip retrying on
- * cancellations — if the caller aborted, retrying would just abort again.
- */
+export declare function sleep(ms: number, signal?: AbortSignal, opts?: {
+    unref?: boolean;
+}): Promise<void>;
 export declare function isAbortError(err: unknown): boolean;
-/**
- * Link a parent signal to a child controller: when the parent aborts, the
- * child is aborted with the same reason. No-op if the parent is already
- * aborted (the caller should check `parent.aborted` separately if it cares
- * about synchronous abort).
- *
- * The listener is `{ once: true }` — no leak.
- */
-export declare function linkSignal(parent: AbortSignal, child: AbortController): void;
+export declare function linkSignal(parent: AbortSignal, child: AbortController): () => void;
 //# sourceMappingURL=abort.d.ts.map

package/dist/utils/abort.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../src/utils/abort.ts"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,WAAW,CAwB1E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,CAAC,CAAC,CA2BZ;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBrE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CASlD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,eAAe,GACrB,IAAI,CAUN"}
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../src/utils/abort.ts"],"names":[],"mappings":"AAaA,wBAAgB,SAAS,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,WAAW,CAgC1E;AAOD,wBAAgB,SAAS,CAAC,CAAC,EACzB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,CAAC,CAAC,CAmCZ;AAWD,wBAAgB,KAAK,CACnB,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,WAAW,EACpB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACzB,OAAO,CAAC,IAAI,CAAC,CAyBf;AAQD,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAelD;AASD,wBAAgB,UAAU,CACxB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,eAAe,GACrB,MAAM,IAAI,CAQZ"}