actly 1.1.0 → 1.2.0

package/dist/utils/abort.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Compose multiple AbortSignals into one. Aborts when ANY input aborts,
+ * with the same reason.
+ *
+ * Uses native `AbortSignal.any()` on Node 20+ (zero allocations, no
+ * listener leaks — the runtime owns the lifecycle). Falls back to a
+ * polyfill that explicitly removes listeners on first abort.
+ *
+ * # Listener safety
+ *
+ * The polyfill registers `{ once: true }` listeners on each input and
+ * manually removes the others when one fires. After settlement, the
+ * composite signal holds zero references to the inputs — they may be GC'd.
+ */
+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).
+ *
+ * # Listener safety
+ *
+ * On success path, the abort listener is explicitly removed. A
+ * `{ once: true }` listener would stay attached on long-lived signals,
+ * leaking one closure per call.
+ *
+ * # Mark-as-handled
+ *
+ * When the signal aborts first, the original `promise` may still settle
+ * later (success or failure). We attach a no-op `.catch` to it so V8
+ * doesn't emit an `unhandledRejection` warning. The error is NOT
+ * swallowed from the caller — the caller already received `signal.reason`.
+ */
+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).
+ *
+ * # Timer hygiene
+ *
+ * The internal `setTimeout` is `unref`'d on Node so it doesn't keep the
+ * event loop alive solely for this sleep. On browsers there is no
+ * equivalent — the timer is short-lived enough not to matter.
+ */
+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.
+ *
+ * # Contract
+ *
+ * Returns an `unlink()` function that removes the listener. Callers MUST
+ * call `unlink()` on success path — otherwise the listener stays attached
+ * to the parent forever, leaking one closure per call.
+ *
+ * If the parent is already aborted, the child is aborted synchronously
+ * and `unlink` is a no-op.
+ *
+ * # Prefer `anySignal()` instead
+ *
+ * For new code, prefer `anySignal([parent, timeoutSignal])` which uses
+ * the native Node 20+ implementation and handles cleanup automatically.
+ * This function exists for call sites that need an `AbortController`
+ * (not just a signal) — e.g. to layer additional abort sources.
+ */
+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":"AAYA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,WAAW,CAsC1E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,CAAC,CAAC,CAsCZ;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BrE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAelD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,eAAe,GACrB,MAAM,IAAI,CAQZ"}

package/dist/utils/abort.js

@@ -0,0 +1,206 @@
+// ─── AbortSignal helpers ──────────────────────────────────────────────────────
+//
+// Contract: zero listener accumulation on long-lived AbortSignals.
+//
+// Every `addEventListener('abort', ...)` MUST be paired with a
+// `removeEventListener` on the success path, OR use `AbortSignal.any()`
+// (Node 20+ native) which handles cleanup automatically.
+//
+// Long-lived signals (server shutdown, request pool) must not accumulate
+// one listener per `act()` call — that would cause
+// `MaxListenersExceededWarning` and unbounded closure retention.
+/**
+ * Compose multiple AbortSignals into one. Aborts when ANY input aborts,
+ * with the same reason.
+ *
+ * Uses native `AbortSignal.any()` on Node 20+ (zero allocations, no
+ * listener leaks — the runtime owns the lifecycle). Falls back to a
+ * polyfill that explicitly removes listeners on first abort.
+ *
+ * # Listener safety
+ *
+ * The polyfill registers `{ once: true }` listeners on each input and
+ * manually removes the others when one fires. After settlement, the
+ * composite signal holds zero references to the inputs — they may be GC'd.
+ */
+export function anySignal(signals) {
+    // Filter out undefined / null defensively.
+    const filtered = signals.filter((s) => s != null);
+    if (filtered.length === 0) {
+        // No inputs → never-aborting signal. Use a fresh controller so callers
+        // get a real AbortSignal, not a hand-rolled mock.
+        return new AbortController().signal;
+    }
+    if (filtered.length === 1)
+        return filtered[0];
+    // Native path (Node 20+, modern browsers, Bun).
+    const native = AbortSignal.any;
+    if (typeof native === 'function') {
+        return native.call(AbortSignal, filtered);
+    }
+    // Polyfill: only used when native is missing. Listener-safe.
+    const controller = new AbortController();
+    const listeners = [];
+    for (const signal of filtered) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+            break;
+        }
+        const onAbort = () => {
+            controller.abort(signal.reason);
+            // Remove all other listeners — they hold closures over `signal`
+            // and would otherwise keep the inputs alive past settlement.
+            for (const off of listeners)
+                off();
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        listeners.push(() => signal.removeEventListener('abort', onAbort));
+    }
+    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).
+ *
+ * # Listener safety
+ *
+ * On success path, the abort listener is explicitly removed. A
+ * `{ once: true }` listener would stay attached on long-lived signals,
+ * leaking one closure per call.
+ *
+ * # Mark-as-handled
+ *
+ * When the signal aborts first, the original `promise` may still settle
+ * later (success or failure). We attach a no-op `.catch` to it so V8
+ * doesn't emit an `unhandledRejection` warning. The error is NOT
+ * swallowed from the caller — the caller already received `signal.reason`.
+ */
+export function raceAbort(promise, signal) {
+    if (signal.aborted) {
+        // Mark the promise as handled — its eventual rejection won't surface
+        // as an unhandled rejection. Its eventual success is dropped silently,
+        // which is correct: the caller has already moved on.
+        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);
+        };
+        // Not using `{ once: true }` — we want explicit removal on success
+        // path so the listener doesn't linger on a long-lived signal.
+        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).
+ *
+ * # Timer hygiene
+ *
+ * The internal `setTimeout` is `unref`'d on Node so it doesn't keep the
+ * event loop alive solely for this sleep. On browsers there is no
+ * equivalent — the timer is short-lived enough not to matter.
+ */
+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);
+        // NOTE: do NOT `unref()` this timer. Unlike InMemoryStore's autoCleanup
+        // interval (which is a background housekeeping task), `sleep()` IS the
+        // operation the caller is awaiting. If we unref'd it, Node could exit
+        // the process while a retry delay was pending — silently dropping the
+        // operation. The timer is short-lived (cleared in onAbort or after ms),
+        // so the cost of keeping the loop alive is bounded.
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        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.
+ */
+export function isAbortError(err) {
+    if (err == null || typeof err !== 'object')
+        return false;
+    const name = err.name;
+    if (name === 'AbortError')
+        return true;
+    // DOMException with name 'TimeoutError' is what AbortSignal.timeout throws.
+    // Distinguish from our own TimeoutError class by checking for DOMException.
+    if (name === 'TimeoutError' &&
+        err instanceof Error &&
+        typeof DOMException !== 'undefined' &&
+        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.
+ *
+ * # Contract
+ *
+ * Returns an `unlink()` function that removes the listener. Callers MUST
+ * call `unlink()` on success path — otherwise the listener stays attached
+ * to the parent forever, leaking one closure per call.
+ *
+ * If the parent is already aborted, the child is aborted synchronously
+ * and `unlink` is a no-op.
+ *
+ * # Prefer `anySignal()` instead
+ *
+ * For new code, prefer `anySignal([parent, timeoutSignal])` which uses
+ * the native Node 20+ implementation and handles cleanup automatically.
+ * This function exists for call sites that need an `AbortController`
+ * (not just a signal) — e.g. to layer additional abort sources.
+ */
+export function linkSignal(parent, child) {
+    if (parent.aborted) {
+        child.abort(parent.reason);
+        return () => { };
+    }
+    const onAbort = () => child.abort(parent.reason);
+    parent.addEventListener('abort', onAbort);
+    return () => parent.removeEventListener('abort', onAbort);
+}
+//# 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/abortPool.cjs

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.acquireController = acquireController;
+exports.releaseController = releaseController;
+exports.poolSize = poolSize;
+const pool = [];
+const MAX_POOL_SIZE = 64;
+function acquireController() {
+    while (pool.length > 0) {
+        const c = pool.pop();
+        if (!c.signal.aborted) {
+            return c;
+        }
+    }
+    return new AbortController();
+}
+function releaseController(c) {
+    if (c.signal.aborted)
+        return;
+    if (pool.length >= MAX_POOL_SIZE)
+        return;
+    pool.push(c);
+}
+function poolSize() {
+    return pool.length;
+}

package/dist/utils/abortPool.d.ts

@@ -0,0 +1,4 @@
+export declare function acquireController(): AbortController;
+export declare function releaseController(c: AbortController): void;
+export declare function poolSize(): number;
+//# sourceMappingURL=abortPool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"abortPool.d.ts","sourceRoot":"","sources":["../../src/utils/abortPool.ts"],"names":[],"mappings":"AAGA,wBAAgB,iBAAiB,IAAI,eAAe,CAQnD;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,eAAe,GAAG,IAAI,CAI1D;AAED,wBAAgB,QAAQ,IAAI,MAAM,CAEjC"}

package/dist/utils/abortPool.js

@@ -0,0 +1,22 @@
+const pool = [];
+const MAX_POOL_SIZE = 64;
+export function acquireController() {
+    while (pool.length > 0) {
+        const c = pool.pop();
+        if (!c.signal.aborted) {
+            return c;
+        }
+    }
+    return new AbortController();
+}
+export function releaseController(c) {
+    if (c.signal.aborted)
+        return;
+    if (pool.length >= MAX_POOL_SIZE)
+        return;
+    pool.push(c);
+}
+export function poolSize() {
+    return pool.length;
+}
+//# sourceMappingURL=abortPool.js.map

package/dist/utils/abortPool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abortPool.js","sourceRoot":"","sources":["../../src/utils/abortPool.ts"],"names":[],"mappings":"AAAA,MAAM,IAAI,GAAsB,EAAE,CAAA;AAClC,MAAM,aAAa,GAAG,EAAE,CAAA;AAExB,MAAM,UAAU,iBAAiB;IAC/B,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,EAAG,CAAA;QACrB,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACtB,OAAO,CAAC,CAAA;QACV,CAAC;IACH,CAAC;IACD,OAAO,IAAI,eAAe,EAAE,CAAA;AAC9B,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,CAAkB;IAClD,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO;QAAE,OAAM;IAC5B,IAAI,IAAI,CAAC,MAAM,IAAI,aAAa;QAAE,OAAM;IACxC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACd,CAAC;AAED,MAAM,UAAU,QAAQ;IACtB,OAAO,IAAI,CAAC,MAAM,CAAA;AACpB,CAAC"}

package/dist/utils/backoff.cjs

@@ -0,0 +1,54 @@
+"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
+    // All jitter variants produce a delay in [0, delay].
+    // The `decorrelated` formula `base + random() * (delay - base)` assumes
+    // delay >= base, which can be violated when maxDelay caps below base.
+    // Fix: clamp the final result to [0, delay] to guarantee the cap holds.
+    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': {
+            // If delay < base (maxDelay capped below base), decorrelated degrades
+            // to full jitter — the formula would otherwise produce values > delay.
+            const lo = Math.min(base, delay);
+            const hi = delay;
+            const result = lo + Math.random() * (hi - lo);
+            return Math.max(0, Math.min(result, delay));
+        }
+        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,CAoCxE"}

package/dist/utils/backoff.js

@@ -0,0 +1,52 @@
+/**
+ * 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
+    // All jitter variants produce a delay in [0, delay].
+    // The `decorrelated` formula `base + random() * (delay - base)` assumes
+    // delay >= base, which can be violated when maxDelay caps below base.
+    // Fix: clamp the final result to [0, delay] to guarantee the cap holds.
+    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': {
+            // If delay < base (maxDelay capped below base), decorrelated degrades
+            // to full jitter — the formula would otherwise produce values > delay.
+            const lo = Math.min(base, delay);
+            const hi = delay;
+            const result = lo + Math.random() * (hi - lo);
+            return Math.max(0, Math.min(result, delay));
+        }
+        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,qDAAqD;IACrD,wEAAwE;IACxE,sEAAsE;IACtE,wEAAwE;IACxE,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,CAAC;YACpB,sEAAsE;YACtE,uEAAuE;YACvE,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;YAChC,MAAM,EAAE,GAAG,KAAK,CAAA;YAChB,MAAM,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAA;YAC7C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAA;QAC7C,CAAC;QACD,OAAO,CAAC,CAAa,OAAO,KAAK,CAAA;IACnC,CAAC;AACH,CAAC"}

package/dist/utils/key.cjs

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * Key sanitisation — the first line of defence against:
+ *
+ *  - **Prototype pollution**: `__proto__`, `constructor`, `prototype` as keys
+ *    bypass namespace isolation in plain-object store adapters.
+ *  - **Control-char injection**: `\x00`–`\x1f`, `\x7f` break some store
+ *    backends (Redis Lua, HTTP header logs, JSON-LD contexts).
+ *  - **CRLF injection**: `\r\n` in keys can break naive log/HTTP serializers.
+ *  - **Memory exhaustion**: unbounded key length lets a caller store a 10MB
+ *    string as a key, bloating the store and blocking iteration.
+ *  - **Namespace collision**: user keys starting with `dedupe:`, `cache:`,
+ *    or `__inflight:` would clobber internal slots.
+ *
+ * # Why a dedicated module?
+ *
+ * Key validation is security-sensitive. Centralising it here means every
+ * call site (`act()`, `invalidate()`, `withStore().invalidate()`) applies
+ * the same rules. Local inlining risks drift.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeKey = sanitizeKey;
+const limits_js_1 = require("./limits.js");
+const RESERVED_PREFIXES = ['dedupe:', 'cache:', '__inflight:', '__tenant:', 'tenant:'];
+/**
+ * Strings that, if used as Map keys, are safe — but if used as plain-object
+ * keys (e.g. a naive store adapter) enable prototype pollution. Reject them
+ * regardless of store type: the contract is "your key is safe everywhere".
+ */
+const FORBIDDEN_LITERALS = new Set(['__proto__', 'constructor', 'prototype']);
+/**
+ * Reject any character in the C0 control range, DEL (0x7f), or CRLF.
+ * Allow TAB (0x09) and LF (0x0a) since some callers embed newlines in
+ * structured keys legitimately — but CR is always forbidden.
+ */
+const UNSAFE_CHAR = /[\x00-\x08\x0b\x0c\x0d\x0e-\x1f\x7f]/;
+/**
+ * Validate a user-supplied key. Throws synchronously on invalid input.
+ *
+ * Programmer errors throw — they must not be swallowed into an `ActFailure`
+ * because the caller's code is broken.
+ *
+ * @returns the same `key` (for chaining); never transforms it.
+ */
+function sanitizeKey(key) {
+    if (typeof key !== 'string') {
+        throw new TypeError(`Actly: key must be a string, got ${typeName(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.");
+    }
+    if (key.length > limits_js_1.LIMITS.MAX_KEY_LENGTH) {
+        throw new RangeError(`Actly: key length ${key.length} exceeds limit ${limits_js_1.LIMITS.MAX_KEY_LENGTH}. ` +
+            `Long keys bloat stores and slow iteration. Hash externally if you need longer keys.`);
+    }
+    if (FORBIDDEN_LITERALS.has(key)) {
+        throw new RangeError(`Actly: key ${JSON.stringify(key)} is forbidden (prototype-pollution vector). ` +
+            `Pick a different key.`);
+    }
+    if (UNSAFE_CHAR.test(key)) {
+        throw new RangeError(`Actly: key contains control characters or CRLF, which break store backends ` +
+            `and log serializers. Got ${JSON.stringify(key)}.`);
+    }
+    for (const prefix of RESERVED_PREFIXES) {
+        if (key.startsWith(prefix)) {
+            throw new RangeError(`Actly: key must not start with reserved prefix "${prefix}" ` +
+                `(got ${JSON.stringify(key)}). These namespaces are used internally.`);
+        }
+    }
+    return key;
+}
+function typeName(v) {
+    if (v === null)
+        return 'null';
+    return typeof v;
+}

package/dist/utils/key.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Key sanitisation — the first line of defence against:
+ *
+ *  - **Prototype pollution**: `__proto__`, `constructor`, `prototype` as keys
+ *    bypass namespace isolation in plain-object store adapters.
+ *  - **Control-char injection**: `\x00`–`\x1f`, `\x7f` break some store
+ *    backends (Redis Lua, HTTP header logs, JSON-LD contexts).
+ *  - **CRLF injection**: `\r\n` in keys can break naive log/HTTP serializers.
+ *  - **Memory exhaustion**: unbounded key length lets a caller store a 10MB
+ *    string as a key, bloating the store and blocking iteration.
+ *  - **Namespace collision**: user keys starting with `dedupe:`, `cache:`,
+ *    or `__inflight:` would clobber internal slots.
+ *
+ * # Why a dedicated module?
+ *
+ * Key validation is security-sensitive. Centralising it here means every
+ * call site (`act()`, `invalidate()`, `withStore().invalidate()`) applies
+ * the same rules. Local inlining risks drift.
+ */
+/**
+ * Validate a user-supplied key. Throws synchronously on invalid input.
+ *
+ * Programmer errors throw — they must not be swallowed into an `ActFailure`
+ * because the caller's code is broken.
+ *
+ * @returns the same `key` (for chaining); never transforms it.
+ */
+export declare function sanitizeKey(key: string): string;
+//# sourceMappingURL=key.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../../src/utils/key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAoBH;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAqC/C"}