actly 1.2.0 → 1.3.0

package/dist/policies/dedupe.js

@@ -1,90 +1,46 @@
 import { REQUIRES_SYNC_STORE } from '../core/executor.js';
 import { raceAbort } from '../utils/abort.js';
-// Namespace so dedupe keys never collide with cache keys in the shared store.
+import { safeCall } from '../utils/safeCall.js';
+import { LIMITS } from '../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.
- */
 export function dedupePolicy(opts = { enabled: true }) {
-    const inflightTtl = opts.inflightTtl;
+    const inflightTtl = opts.inflightTtl ?? 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++;
+                    safeCall(obs.hooks.onDedupeJoin, {
+                        type: 'dedupe-join', key: syncCtx.key, traceId: obs.traceId,
+                        timestamp: Date.now(), joinerPosition: obs.joinerCounter,
+                    });
+                }
                 try {
                     const value = await 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 = {
@@ -93,24 +49,20 @@ export 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 raceAbort(rawPromise, signal);
         };
     };
     applier[REQUIRES_SYNC_STORE] = true;
     return applier;
 }
-//# sourceMappingURL=dedupe.js.map

package/dist/policies/noop.cjs

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noopPolicy = noopPolicy;
+function noopPolicy() {
+    return (fn, _ctx) => fn;
+}

package/dist/policies/noop.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"noop.d.ts","sourceRoot":"","sources":["../../src/policies/noop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,MAAM,mBAAmB,CAAA;AAoB5E,wBAAgB,UAAU,CAAC,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,CAEhD"}

package/dist/policies/noop.js

@@ -0,0 +1,3 @@
+export function noopPolicy() {
+    return (fn, _ctx) => fn;
+}

package/dist/policies/rateLimit.cjs

@@ -7,8 +7,8 @@ const NS = 'rl:';
 function getState(store, key) {
     return store.get(NS + key) ?? { timestamps: [] };
 }
-function setState(store, key, state) {
-    store.set(NS + key, state);
+function setState(store, key, state, ttlMs) {
+    store.set(NS + key, state, ttlMs);
 }
 function rateLimitPolicy(opts) {
     const maxCalls = Math.max(1, Math.floor(opts.maxCalls));
@@ -16,17 +16,27 @@ function rateLimitPolicy(opts) {
     const applier = (fn, ctx) => {
         const syncCtx = ctx;
         return async (signal) => {
+            if (signal.aborted)
+                return Promise.reject(signal.reason);
             const key = syncCtx.key;
             const now = Date.now();
             const state = getState(syncCtx.store, key);
             const cutoff = now - windowMs;
-            state.timestamps = state.timestamps.filter(t => t > cutoff);
+            const ts = state.timestamps;
+            if (ts.length > 0 && ts[0] <= cutoff) {
+                let i = 0;
+                while (i < ts.length && ts[i] <= cutoff)
+                    i++;
+                if (i > 0) {
+                    state.timestamps = i === ts.length ? [] : ts.slice(i);
+                }
+            }
             if (state.timestamps.length >= maxCalls) {
-                setState(syncCtx.store, key, state);
+                setState(syncCtx.store, key, state, windowMs);
                 throw new errors_js_1.RateLimitError(key, maxCalls, windowMs);
             }
             state.timestamps.push(now);
-            setState(syncCtx.store, key, state);
+            setState(syncCtx.store, key, state, windowMs);
             return fn(signal);
         };
     };

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

@@ -1 +1 @@
-{"version":3,"file":"rateLimit.d.ts","sourceRoot":"","sources":["../../src/policies/rateLimit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAmB9F,wBAAgB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,gBAAgB,GAAG,aAAa,CAAC,CAAC,CAAC,CA6B3E"}
+{"version":3,"file":"rateLimit.d.ts","sourceRoot":"","sources":["../../src/policies/rateLimit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAmB9F,wBAAgB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,gBAAgB,GAAG,aAAa,CAAC,CAAC,CAAC,CA6C3E"}

package/dist/policies/rateLimit.js

@@ -4,8 +4,8 @@ const NS = 'rl:';
 function getState(store, key) {
     return store.get(NS + key) ?? { timestamps: [] };
 }
-function setState(store, key, state) {
-    store.set(NS + key, state);
+function setState(store, key, state, ttlMs) {
+    store.set(NS + key, state, ttlMs);
 }
 export function rateLimitPolicy(opts) {
     const maxCalls = Math.max(1, Math.floor(opts.maxCalls));
@@ -13,21 +13,30 @@ export function rateLimitPolicy(opts) {
     const applier = (fn, ctx) => {
         const syncCtx = ctx;
         return async (signal) => {
+            if (signal.aborted)
+                return Promise.reject(signal.reason);
             const key = syncCtx.key;
             const now = Date.now();
             const state = getState(syncCtx.store, key);
             const cutoff = now - windowMs;
-            state.timestamps = state.timestamps.filter(t => t > cutoff);
+            const ts = state.timestamps;
+            if (ts.length > 0 && ts[0] <= cutoff) {
+                let i = 0;
+                while (i < ts.length && ts[i] <= cutoff)
+                    i++;
+                if (i > 0) {
+                    state.timestamps = i === ts.length ? [] : ts.slice(i);
+                }
+            }
             if (state.timestamps.length >= maxCalls) {
-                setState(syncCtx.store, key, state);
+                setState(syncCtx.store, key, state, windowMs);
                 throw new RateLimitError(key, maxCalls, windowMs);
             }
             state.timestamps.push(now);
-            setState(syncCtx.store, key, state);
+            setState(syncCtx.store, key, state, windowMs);
             return fn(signal);
         };
     };
     applier[REQUIRES_SYNC_STORE] = true;
     return applier;
 }
-//# sourceMappingURL=rateLimit.js.map

package/dist/policies/retry.cjs

@@ -3,122 +3,157 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.retryPolicy = retryPolicy;
 const backoff_js_1 = require("../utils/backoff.js");
 const abort_js_1 = require("../utils/abort.js");
+const safeCall_js_1 = require("../utils/safeCall.js");
 const errors_js_1 = require("../errors.js");
-// ─── Default predicate ────────────────────────────────────────────────────────
-/**
- * Default `shouldRetry`: retry on any error EXCEPT abort errors.
- *
- * Abort errors indicate the caller or a timeout cancelled the operation —
- * retrying would just abort again on the next attempt, wasting delay budget.
- *
- * User-supplied `shouldRetry` overrides this entirely.
- */
+const limits_js_1 = require("../utils/limits.js");
 function defaultShouldRetry(error, _attempt) {
-    return !(0, abort_js_1.isAbortError)(error);
+    if ((0, abort_js_1.isAbortError)(error))
+        return false;
+    if (typeof error === 'object' && error !== null) {
+        const code = error.code;
+        if (code === 'ACTLY_TIMEOUT' || code === 'ACTLY_TOTAL_TIMEOUT')
+            return false;
+    }
+    return true;
 }
-// ─── Policy ───────────────────────────────────────────────────────────────────
-/**
- * Retry `fn` up to `opts.attempts` times on retryable errors.
- *
- * Writes the live attempt count into `ctx.meta.attempts` so `act()` can
- * report it in the final `ActResult`.
- *
- * # Signal awareness
- *
- * - Before each attempt, checks `parentSignal.aborted`. If the parent (e.g.
- *   `totalTimeout` or caller) has aborted, throws the parent's reason
- *   immediately — no more attempts.
- * - Sleeps between attempts use `sleep(delay, parentSignal)`. If the parent
- *   aborts mid-delay, the sleep rejects immediately instead of blocking
- *   the loop until the timer would have elapsed.
- *
- * # `shouldRetry` invocation
- *
- * Called after EVERY failure, including the last attempt. This preserves the
- * predicate's contract for observers / metrics that rely on it being called
- * per-attempt. The return value is only consulted when `attempt < max`.
- *
- * # Default predicate
- *
- * If `shouldRetry` is omitted, uses `defaultShouldRetry` which retries on
- * every error EXCEPT abort errors (so timeouts and caller cancellations
- * don't waste retry budget).
- */
 function retryPolicy(opts) {
     const max = Math.max(1, Math.floor(opts.attempts));
     const shouldRetry = opts.shouldRetry ?? defaultShouldRetry;
+    const shouldRetryResult = opts.shouldRetryResult;
+    const dangerouslyUnref = opts.dangerouslyUnref === true;
+    const sleepOpts = dangerouslyUnref ? { unref: true } : undefined;
+    const backoffFn = opts.backoffFn;
     return (fn, ctx) => async (parentSignal) => {
-        const errors = [];
-        let lastErr;
+        const backoffState = {};
+        let errors;
         let retriedAtLeastOnce = false;
         const obs = ctx.observability;
         for (let attempt = 1; attempt <= max; attempt++) {
-            // Parent (totalTimeout or caller signal) already aborted — bail.
             if (parentSignal.aborted)
                 throw parentSignal.reason;
             ctx.meta.attempts = attempt;
             const attemptStart = Date.now();
             try {
-                // Emit onAttempt before each attempt. (We could emit
-                // after with duration/error, but before lets observers track
-                // in-flight attempts in real time.)
                 if (obs) {
-                    obs.hooks.onAttempt?.({
+                    (0, safeCall_js_1.safeCall)(obs.hooks.onAttempt, {
                         type: 'attempt', key: ctx.key, traceId: obs.traceId,
                         timestamp: attemptStart, attempt,
                     });
                 }
-                return await fn(parentSignal);
+                const value = await fn(parentSignal);
+                if (shouldRetryResult) {
+                    let accept;
+                    try {
+                        const raw = shouldRetryResult(value, attempt);
+                        accept = typeof raw === 'boolean' ? raw : true;
+                    }
+                    catch {
+                        return value;
+                    }
+                    if (accept)
+                        return value;
+                    const syntheticError = new Error(`Actly: shouldRetryResult returned false on attempt ${attempt}`);
+                    if (errors === undefined)
+                        errors = [];
+                    if (errors.length < 10) {
+                        errors.push(syntheticError);
+                    }
+                    else {
+                        errors.shift();
+                        errors.push(syntheticError);
+                    }
+                    if (attempt >= max) {
+                        if (obs) {
+                            (0, safeCall_js_1.safeCall)(obs.hooks.onRetry, {
+                                type: 'retry', key: ctx.key, traceId: obs.traceId,
+                                timestamp: Date.now(), attempt, delayMs: 0,
+                                error: syntheticError,
+                            });
+                        }
+                        return value;
+                    }
+                    retriedAtLeastOnce = true;
+                    if (parentSignal.aborted)
+                        throw parentSignal.reason;
+                    let rawDelay;
+                    try {
+                        rawDelay = backoffFn
+                            ? backoffFn(attempt, syntheticError, backoffState)
+                            : (0, backoff_js_1.computeDelay)(attempt, opts);
+                    }
+                    catch {
+                        rawDelay = (0, backoff_js_1.computeDelay)(attempt, opts);
+                    }
+                    const safeDelay = Number.isFinite(rawDelay) ? rawDelay : 0;
+                    const delay = Math.min(Math.max(0, safeDelay), limits_js_1.LIMITS.MAX_RETRY_DELAY_MS);
+                    if (obs) {
+                        (0, safeCall_js_1.safeCall)(obs.hooks.onRetry, {
+                            type: 'retry', key: ctx.key, traceId: obs.traceId,
+                            timestamp: Date.now(), attempt, delayMs: delay,
+                            error: syntheticError,
+                        });
+                    }
+                    if (delay > 0)
+                        await (0, abort_js_1.sleep)(delay, parentSignal, sleepOpts);
+                    continue;
+                }
+                return value;
             }
             catch (err) {
-                lastErr = err;
-                errors.push(err);
-                // Invoke shouldRetry. If the predicate throws, treat as "don't retry"
-                // and surface the original fn error (not the predicate error).
+                if (errors === undefined)
+                    errors = [];
+                if (errors.length < 10) {
+                    errors.push(err);
+                }
+                else {
+                    errors.shift();
+                    errors.push(err);
+                }
                 let retryable;
                 try {
                     retryable = shouldRetry(err, attempt);
                 }
                 catch {
-                    // Predicate threw — don't retry, surface original error
                     throw err;
                 }
                 if (attempt >= max) {
-                    // Last attempt. If we retried at least once (predicate
-                    // allowed retries), wrap in RetryExhaustedError for context.
                     if (retriedAtLeastOnce) {
                         throw new errors_js_1.RetryExhaustedError({
                             key: ctx.key,
                             attempts: attempt,
                             lastError: err,
-                            errors,
+                            errors: errors ?? [],
                         });
                     }
                     throw err;
                 }
-                if (!retryable) {
-                    // Non-retryable error — bail immediately.
+                if (!retryable)
                     throw err;
-                }
-                // Mark that we retried at least once — affects final wrap.
                 retriedAtLeastOnce = true;
-                // Parent aborted mid-attempt — don't sleep, bail.
                 if (parentSignal.aborted)
                     throw parentSignal.reason;
-                const delay = (0, backoff_js_1.computeDelay)(attempt, opts);
-                // Emit onRetry before the delay sleep.
+                let rawDelay;
+                try {
+                    rawDelay = backoffFn
+                        ? backoffFn(attempt, err, backoffState)
+                        : (0, backoff_js_1.computeDelay)(attempt, opts);
+                }
+                catch {
+                    rawDelay = (0, backoff_js_1.computeDelay)(attempt, opts);
+                }
+                const safeDelay = Number.isFinite(rawDelay) ? rawDelay : 0;
+                const delay = Math.min(Math.max(0, safeDelay), limits_js_1.LIMITS.MAX_RETRY_DELAY_MS);
                 if (obs) {
-                    obs.hooks.onRetry?.({
+                    (0, safeCall_js_1.safeCall)(obs.hooks.onRetry, {
                         type: 'retry', key: ctx.key, traceId: obs.traceId,
                         timestamp: Date.now(), attempt, delayMs: delay, error: err,
                     });
                 }
                 if (delay > 0) {
-                    await (0, abort_js_1.sleep)(delay, parentSignal);
+                    await (0, abort_js_1.sleep)(delay, parentSignal, sleepOpts);
                 }
             }
         }
-        // Unreachable: the loop either returns or throws on every iteration.
-        throw lastErr;
+        throw new Error('Actly: retryPolicy reached unreachable state');
     };
 }

package/dist/policies/retry.d.ts

@@ -1,30 +1,3 @@
 import type { PolicyApplier, RetryOptions } from '../types/index.js';
-/**
- * Retry `fn` up to `opts.attempts` times on retryable errors.
- *
- * Writes the live attempt count into `ctx.meta.attempts` so `act()` can
- * report it in the final `ActResult`.
- *
- * # Signal awareness
- *
- * - Before each attempt, checks `parentSignal.aborted`. If the parent (e.g.
- *   `totalTimeout` or caller) has aborted, throws the parent's reason
- *   immediately — no more attempts.
- * - Sleeps between attempts use `sleep(delay, parentSignal)`. If the parent
- *   aborts mid-delay, the sleep rejects immediately instead of blocking
- *   the loop until the timer would have elapsed.
- *
- * # `shouldRetry` invocation
- *
- * Called after EVERY failure, including the last attempt. This preserves the
- * predicate's contract for observers / metrics that rely on it being called
- * per-attempt. The return value is only consulted when `attempt < max`.
- *
- * # Default predicate
- *
- * If `shouldRetry` is omitted, uses `defaultShouldRetry` which retries on
- * every error EXCEPT abort errors (so timeouts and caller cancellations
- * don't waste retry budget).
- */
 export declare function retryPolicy<T>(opts: RetryOptions): PolicyApplier<T>;
 //# sourceMappingURL=retry.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/policies/retry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAqB1F;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,CAAC,CAAC,CAuFnE"}
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/policies/retry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAsC1F,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,CAAC,CAAC,CA4KnE"}