actly 1.0.2 → 1.1.5

package/dist/utils/abort.cjs

@@ -0,0 +1,142 @@
+"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".
+ */
+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 controller = new AbortController();
+    for (const signal of signals) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+            break;
+        }
+        signal.addEventListener('abort', () => controller.abort(signal.reason), { once: true });
+    }
+    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)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const onAbort = () => {
+            if (settled)
+                return;
+            settled = true;
+            reject(signal.reason);
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        }, (error) => {
+            if (settled)
+                return;
+            settled = true;
+            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) {
+    if (ms <= 0) {
+        if (signal?.aborted)
+            return Promise.reject(signal.reason);
+        return Promise.resolve();
+    }
+    if (signal?.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * 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;
+    const name = err.name;
+    return name === 'AbortError' || 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;
+}
+/**
+ * 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;
+    }
+    parent.addEventListener('abort', () => child.abort(parent.reason), { once: true });
+}

package/dist/utils/abort.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 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;
+//# sourceMappingURL=abort.d.ts.map

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

@@ -0,0 +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"}

package/dist/utils/abort.js

@@ -0,0 +1,136 @@
+// ─── 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.
+/**
+ * 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 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 controller = new AbortController();
+    for (const signal of signals) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+            break;
+        }
+        signal.addEventListener('abort', () => controller.abort(signal.reason), { once: true });
+    }
+    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.
+ */
+export function raceAbort(promise, signal) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const onAbort = () => {
+            if (settled)
+                return;
+            settled = true;
+            reject(signal.reason);
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        }, (error) => {
+            if (settled)
+                return;
+            settled = true;
+            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.
+ */
+export function sleep(ms, signal) {
+    if (ms <= 0) {
+        if (signal?.aborted)
+            return Promise.reject(signal.reason);
+        return Promise.resolve();
+    }
+    if (signal?.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * 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 function isAbortError(err) {
+    if (err == null || typeof err !== 'object')
+        return false;
+    const name = err.name;
+    return name === 'AbortError' || 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;
+}
+/**
+ * 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 function linkSignal(parent, child) {
+    if (parent.aborted) {
+        child.abort(parent.reason);
+        return;
+    }
+    parent.addEventListener('abort', () => child.abort(parent.reason), { once: true });
+}
+//# sourceMappingURL=abort.js.map

package/dist/utils/abort.js.map

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

package/dist/utils/backoff.cjs

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeDelay = computeDelay;
+/**
+ * Compute the delay before the next retry attempt, applying backoff, cap, and
+ * jitter in that order.
+ *
+ * Order matters:
+ *  1. `backoff` grows the base delay geometrically/linearly.
+ *  2. `maxDelay` caps the result (prevents exponential blowup).
+ *  3. `jitter` randomises within `[0, delay]` (prevents thundering herd).
+ *
+ * Returns 0 if `delayMs` is 0 or undefined — skipping the sleep entirely.
+ */
+function computeDelay(attempt, opts) {
+    const base = opts.delayMs ?? 0;
+    if (base === 0)
+        return 0;
+    // Step 1: backoff
+    let delay;
+    switch (opts.backoff ?? 'none') {
+        case 'linear':
+            delay = base * attempt;
+            break;
+        case 'exponential':
+            delay = base * 2 ** (attempt - 1);
+            break;
+        default: delay = base;
+    }
+    // Step 2: cap (guard against Infinity and NaN before Math.min)
+    const max = opts.maxDelay ?? Number.POSITIVE_INFINITY;
+    if (!Number.isFinite(delay))
+        delay = max;
+    delay = Math.min(delay, max);
+    // Step 3: jitter
+    switch (opts.jitter ?? 'full') {
+        case 'none': return delay;
+        case 'full': return Math.random() * delay;
+        case 'equal': return delay / 2 + Math.random() * delay / 2;
+        case 'decorrelated': return base + Math.random() * (delay - base);
+        default: return delay;
+    }
+}

package/dist/utils/backoff.d.ts

@@ -0,0 +1,14 @@
+import type { RetryOptions } from '../types/index.js';
+/**
+ * Compute the delay before the next retry attempt, applying backoff, cap, and
+ * jitter in that order.
+ *
+ * Order matters:
+ *  1. `backoff` grows the base delay geometrically/linearly.
+ *  2. `maxDelay` caps the result (prevents exponential blowup).
+ *  3. `jitter` randomises within `[0, delay]` (prevents thundering herd).
+ *
+ * Returns 0 if `delayMs` is 0 or undefined — skipping the sleep entirely.
+ */
+export declare function computeDelay(attempt: number, opts: RetryOptions): number;
+//# sourceMappingURL=backoff.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../../src/utils/backoff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAErD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,MAAM,CAyBxE"}

package/dist/utils/backoff.js

@@ -0,0 +1,41 @@
+/**
+ * Compute the delay before the next retry attempt, applying backoff, cap, and
+ * jitter in that order.
+ *
+ * Order matters:
+ *  1. `backoff` grows the base delay geometrically/linearly.
+ *  2. `maxDelay` caps the result (prevents exponential blowup).
+ *  3. `jitter` randomises within `[0, delay]` (prevents thundering herd).
+ *
+ * Returns 0 if `delayMs` is 0 or undefined — skipping the sleep entirely.
+ */
+export function computeDelay(attempt, opts) {
+    const base = opts.delayMs ?? 0;
+    if (base === 0)
+        return 0;
+    // Step 1: backoff
+    let delay;
+    switch (opts.backoff ?? 'none') {
+        case 'linear':
+            delay = base * attempt;
+            break;
+        case 'exponential':
+            delay = base * 2 ** (attempt - 1);
+            break;
+        default: delay = base;
+    }
+    // Step 2: cap (guard against Infinity and NaN before Math.min)
+    const max = opts.maxDelay ?? Number.POSITIVE_INFINITY;
+    if (!Number.isFinite(delay))
+        delay = max;
+    delay = Math.min(delay, max);
+    // Step 3: jitter
+    switch (opts.jitter ?? 'full') {
+        case 'none': return delay;
+        case 'full': return Math.random() * delay;
+        case 'equal': return delay / 2 + Math.random() * delay / 2;
+        case 'decorrelated': return base + Math.random() * (delay - base);
+        default: return delay;
+    }
+}
+//# sourceMappingURL=backoff.js.map

package/dist/utils/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../../src/utils/backoff.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,IAAkB;IAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAA;IAC9B,IAAI,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAA;IAExB,kBAAkB;IAClB,IAAI,KAAa,CAAA;IACjB,QAAQ,IAAI,CAAC,OAAO,IAAI,MAAM,EAAE,CAAC;QAC/B,KAAK,QAAQ;YAAO,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC;YAAC,MAAK;QACjD,KAAK,aAAa;YAAE,KAAK,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;YAAC,MAAK;QAC5D,OAAO,CAAC,CAAY,KAAK,GAAG,IAAI,CAAA;IAClC,CAAC;IAED,+DAA+D;IAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,IAAI,MAAM,CAAC,iBAAiB,CAAA;IACrD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,KAAK,GAAG,GAAG,CAAA;IACxC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;IAE5B,iBAAiB;IACjB,QAAQ,IAAI,CAAC,MAAM,IAAI,MAAM,EAAE,CAAC;QAC9B,KAAK,MAAM,CAAC,CAAS,OAAO,KAAK,CAAA;QACjC,KAAK,MAAM,CAAC,CAAS,OAAO,IAAI,CAAC,MAAM,EAAE,GAAG,KAAK,CAAA;QACjD,KAAK,OAAO,CAAC,CAAQ,OAAO,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,KAAK,GAAG,CAAC,CAAA;QACjE,KAAK,cAAc,CAAC,CAAC,OAAO,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,CAAA;QACjE,OAAO,CAAC,CAAa,OAAO,KAAK,CAAA;IACnC,CAAC;AACH,CAAC"}

package/dist/utils/validate.cjs

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertKey = assertKey;
+exports.assertRetryOptions = assertRetryOptions;
+exports.assertTimeoutOptions = assertTimeoutOptions;
+exports.assertCacheOptions = assertCacheOptions;
+exports.assertDedupeOptions = assertDedupeOptions;
+exports.assertOptions = assertOptions;
+/**
+ * Validate user-facing option shapes. Throws `RangeError` / `TypeError` on
+ * invalid input — these are programmer errors, not runtime failures, so
+ * throwing (rather than returning an `ActFailure`) is the right call.
+ *
+ * Called once at the top of `act()` so policies can assume well-formed input.
+ */
+function assertKey(key) {
+    if (typeof key !== 'string') {
+        throw new TypeError(`Actly: key must be a string, got ${typeof key}`);
+    }
+    if (key.length === 0) {
+        throw new RangeError("Actly: key must be non-empty. An empty key collapses every caller " +
+            "onto the same dedupe/cache slot — almost certainly a bug.");
+    }
+    // Reject reserved internal prefixes so user keys cannot collide with
+    // dedupe/cache namespace prefixes.
+    if (key.startsWith('dedupe:') || key.startsWith('cache:') || key.startsWith('__inflight:')) {
+        throw new RangeError(`Actly: key must not start with reserved prefix "dedupe:", "cache:", or "__inflight:" (got ${JSON.stringify(key)}).`);
+    }
+}
+function assertRetryOptions(opts) {
+    if (!Number.isInteger(opts.attempts) || opts.attempts < 1) {
+        throw new RangeError(`Actly: retry.attempts must be a positive integer, got ${opts.attempts}`);
+    }
+    if (opts.delayMs !== undefined) {
+        assertNonNegativeFinite('retry.delayMs', opts.delayMs);
+    }
+    if (opts.maxDelay !== undefined) {
+        assertNonNegativeFinite('retry.maxDelay', opts.maxDelay);
+    }
+    if (opts.shouldRetry !== undefined && typeof opts.shouldRetry !== 'function') {
+        throw new TypeError(`Actly: retry.shouldRetry must be a function, got ${typeof opts.shouldRetry}`);
+    }
+}
+function assertTimeoutOptions(opts, field) {
+    if (typeof opts.ms !== 'number' || !Number.isFinite(opts.ms) || opts.ms <= 0) {
+        throw new RangeError(`Actly: ${field}.ms must be a positive finite number, got ${opts.ms}`);
+    }
+}
+function assertCacheOptions(opts) {
+    if (typeof opts.ttl !== 'number' || !Number.isFinite(opts.ttl) || opts.ttl <= 0) {
+        throw new RangeError(`Actly: cache.ttl must be a positive finite number, got ${opts.ttl}`);
+    }
+}
+function assertDedupeOptions(opts) {
+    if (opts.inflightTtl !== undefined) {
+        assertNonNegativeFinite('dedupe.inflightTtl', opts.inflightTtl);
+    }
+}
+function assertOptions(options) {
+    if (options.retry)
+        assertRetryOptions(options.retry);
+    if (options.timeout)
+        assertTimeoutOptions(options.timeout, 'timeout');
+    if (options.totalTimeout)
+        assertTimeoutOptions(options.totalTimeout, 'totalTimeout');
+    if (options.cache)
+        assertCacheOptions(options.cache);
+    if (options.dedupe && typeof options.dedupe !== 'boolean') {
+        assertDedupeOptions(options.dedupe);
+    }
+    if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) {
+        throw new TypeError(`Actly: signal must be an AbortSignal, got ${options.signal === null ? 'null' : typeof options.signal}`);
+    }
+}
+function assertNonNegativeFinite(field, value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+        throw new RangeError(`Actly: ${field} must be a non-negative finite number, got ${value}`);
+    }
+}

package/dist/utils/validate.d.ts

@@ -0,0 +1,15 @@
+import type { ActOptions, CacheOptions, DedupeOptions, RetryOptions, TimeoutOptions } from '../types/index.js';
+/**
+ * Validate user-facing option shapes. Throws `RangeError` / `TypeError` on
+ * invalid input — these are programmer errors, not runtime failures, so
+ * throwing (rather than returning an `ActFailure`) is the right call.
+ *
+ * Called once at the top of `act()` so policies can assume well-formed input.
+ */
+export declare function assertKey(key: string): void;
+export declare function assertRetryOptions(opts: RetryOptions): void;
+export declare function assertTimeoutOptions(opts: TimeoutOptions, field: string): void;
+export declare function assertCacheOptions(opts: CacheOptions): void;
+export declare function assertDedupeOptions(opts: DedupeOptions): void;
+export declare function assertOptions(options: ActOptions): void;
+//# sourceMappingURL=validate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/utils/validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,cAAc,EACf,MAAM,mBAAmB,CAAA;AAE1B;;;;;;GAMG;AAEH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAiB3C;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAiB3D;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAM9E;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAM3D;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAI7D;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAavD"}

package/dist/utils/validate.js

@@ -0,0 +1,72 @@
+/**
+ * Validate user-facing option shapes. Throws `RangeError` / `TypeError` on
+ * invalid input — these are programmer errors, not runtime failures, so
+ * throwing (rather than returning an `ActFailure`) is the right call.
+ *
+ * Called once at the top of `act()` so policies can assume well-formed input.
+ */
+export function assertKey(key) {
+    if (typeof key !== 'string') {
+        throw new TypeError(`Actly: key must be a string, got ${typeof key}`);
+    }
+    if (key.length === 0) {
+        throw new RangeError("Actly: key must be non-empty. An empty key collapses every caller " +
+            "onto the same dedupe/cache slot — almost certainly a bug.");
+    }
+    // Reject reserved internal prefixes so user keys cannot collide with
+    // dedupe/cache namespace prefixes.
+    if (key.startsWith('dedupe:') || key.startsWith('cache:') || key.startsWith('__inflight:')) {
+        throw new RangeError(`Actly: key must not start with reserved prefix "dedupe:", "cache:", or "__inflight:" (got ${JSON.stringify(key)}).`);
+    }
+}
+export function assertRetryOptions(opts) {
+    if (!Number.isInteger(opts.attempts) || opts.attempts < 1) {
+        throw new RangeError(`Actly: retry.attempts must be a positive integer, got ${opts.attempts}`);
+    }
+    if (opts.delayMs !== undefined) {
+        assertNonNegativeFinite('retry.delayMs', opts.delayMs);
+    }
+    if (opts.maxDelay !== undefined) {
+        assertNonNegativeFinite('retry.maxDelay', opts.maxDelay);
+    }
+    if (opts.shouldRetry !== undefined && typeof opts.shouldRetry !== 'function') {
+        throw new TypeError(`Actly: retry.shouldRetry must be a function, got ${typeof opts.shouldRetry}`);
+    }
+}
+export function assertTimeoutOptions(opts, field) {
+    if (typeof opts.ms !== 'number' || !Number.isFinite(opts.ms) || opts.ms <= 0) {
+        throw new RangeError(`Actly: ${field}.ms must be a positive finite number, got ${opts.ms}`);
+    }
+}
+export function assertCacheOptions(opts) {
+    if (typeof opts.ttl !== 'number' || !Number.isFinite(opts.ttl) || opts.ttl <= 0) {
+        throw new RangeError(`Actly: cache.ttl must be a positive finite number, got ${opts.ttl}`);
+    }
+}
+export function assertDedupeOptions(opts) {
+    if (opts.inflightTtl !== undefined) {
+        assertNonNegativeFinite('dedupe.inflightTtl', opts.inflightTtl);
+    }
+}
+export function assertOptions(options) {
+    if (options.retry)
+        assertRetryOptions(options.retry);
+    if (options.timeout)
+        assertTimeoutOptions(options.timeout, 'timeout');
+    if (options.totalTimeout)
+        assertTimeoutOptions(options.totalTimeout, 'totalTimeout');
+    if (options.cache)
+        assertCacheOptions(options.cache);
+    if (options.dedupe && typeof options.dedupe !== 'boolean') {
+        assertDedupeOptions(options.dedupe);
+    }
+    if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) {
+        throw new TypeError(`Actly: signal must be an AbortSignal, got ${options.signal === null ? 'null' : typeof options.signal}`);
+    }
+}
+function assertNonNegativeFinite(field, value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+        throw new RangeError(`Actly: ${field} must be a non-negative finite number, got ${value}`);
+    }
+}
+//# sourceMappingURL=validate.js.map

package/dist/utils/validate.js.map

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