actly 1.0.2 → 1.1.5

package/dist/stores/memory.cjs

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryStore = void 0;
+function isUnrefable(t) {
+    return typeof t.unref === 'function';
+}
+// ─── Implementation ───────────────────────────────────────────────────────────
+/**
+ * Reference `SyncStateStore` implementation backed by a `Map`.
+ *
+ * # LRU semantics
+ *
+ * `Map` iteration order is insertion order, so we implement LRU by
+ * `delete` + `set` on every access — the most-recently-touched key ends up
+ * at the end of the iteration, and the oldest is `entries.keys().next().value`.
+ *
+ * # Expiry
+ *
+ * Lazy on `get()` / `has()`: expired entries are deleted when touched.
+ * Background sweep (optional) reclaims entries that are never re-read.
+ */
+class InMemoryStore {
+    _sync = true;
+    entries = new Map();
+    maxSize;
+    cleanupTimer;
+    constructor(options = {}) {
+        const { autoCleanup = false, cleanupIntervalMs = 30_000, maxSize = Number.POSITIVE_INFINITY, } = options;
+        if (!Number.isFinite(maxSize) || maxSize <= 0) {
+            // Infinity is allowed (unbounded); any other non-positive finite value
+            // is a programmer error.
+            if (maxSize !== Number.POSITIVE_INFINITY) {
+                throw new RangeError(`Actly: InMemoryStore maxSize must be a positive finite number or Infinity, got ${maxSize}`);
+            }
+        }
+        this.maxSize = maxSize;
+        if (autoCleanup) {
+            const timer = setInterval(() => this._sweep(), cleanupIntervalMs);
+            if (isUnrefable(timer))
+                timer.unref();
+            this.cleanupTimer = timer;
+        }
+    }
+    get(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        // LRU refresh: move to most-recent position.
+        // delete + set is the canonical pattern for reordering a Map.
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        return entry.value;
+    }
+    set(key, value, ttlMs) {
+        // Evict if at capacity AND adding a new key (updates don't grow size).
+        if (!this.entries.has(key) && this.entries.size >= this.maxSize) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest !== undefined)
+                this.entries.delete(oldest);
+        }
+        const expiresAt = ttlMs != null && ttlMs > 0 ? Date.now() + ttlMs : null;
+        // delete + set ensures the key is moved to the most-recent position
+        // even on update, keeping LRU order consistent.
+        this.entries.delete(key);
+        this.entries.set(key, { value, expiresAt });
+    }
+    delete(key) {
+        this.entries.delete(key);
+    }
+    has(key) {
+        // Inline the expiry check to avoid the LRU side-effect of get().
+        // `has()` should be a pure query, not a touch.
+        const entry = this.entries.get(key);
+        if (!entry)
+            return false;
+        if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+            this.entries.delete(key);
+            return false;
+        }
+        return true;
+    }
+    clear() {
+        this.entries.clear();
+    }
+    /**
+     * Return the count of live (non-expired) entries.
+     *
+     * Pure query — does NOT touch LRU order. Expired entries discovered during
+     * the scan are evicted opportunistically (they were already invisible to
+     * `get()`, so eviction has no observable effect beyond memory reclamation).
+     *
+     * Two-pass to avoid mutating the Map during iteration (spec-safe).
+     */
+    size() {
+        const now = Date.now();
+        const expired = [];
+        let count = 0;
+        for (const [key, entry] of this.entries) {
+            if (entry.expiresAt !== null && entry.expiresAt <= now) {
+                expired.push(key);
+            }
+            else {
+                count++;
+            }
+        }
+        for (const key of expired)
+            this.entries.delete(key);
+        return count;
+    }
+    /**
+     * Stop the background cleanup timer and release internal state.
+     * Safe to call multiple times — subsequent calls are no-ops.
+     */
+    destroy() {
+        if (this.cleanupTimer !== undefined) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+    }
+    /**
+     * Sweep all entries and remove those past their expiry time.
+     * Called by the autoCleanup interval; not part of the public contract.
+     */
+    _sweep() {
+        const now = Date.now();
+        const expired = [];
+        for (const [key, entry] of this.entries) {
+            if (entry.expiresAt !== null && now > entry.expiresAt) {
+                expired.push(key);
+            }
+        }
+        for (const key of expired)
+            this.entries.delete(key);
+    }
+}
+exports.InMemoryStore = InMemoryStore;

package/dist/stores/memory.d.ts

@@ -0,0 +1,79 @@
+import type { SyncStateStore } from './base.js';
+export interface InMemoryStoreOptions {
+    /**
+     * Periodically sweep and remove expired entries in the background.
+     *
+     * Disabled by default. The store evicts lazily on `get()` / `has()` access,
+     * which is sufficient for most use cases. Enable `autoCleanup` when the
+     * store is long-lived and accumulates many TTL'd entries that are never
+     * re-read — for example, a server-side cache that receives write-heavy
+     * traffic with low subsequent read rates.
+     */
+    autoCleanup?: boolean;
+    /**
+     * Interval between background sweeps in milliseconds.
+     * Defaults to 30 000 (30 seconds). Ignored when `autoCleanup` is false.
+     */
+    cleanupIntervalMs?: number;
+    /**
+     * Maximum number of live entries the store will hold.
+     *
+     * When `set()` would exceed this limit, the least-recently-used entry is
+     * evicted before the new one is inserted (LRU semantics). Updates to an
+     * existing key do not trigger eviction.
+     *
+     * Defaults to `Infinity` (unbounded). Set a finite value for long-running
+     * caches with high-cardinality keys to bound memory usage.
+     *
+     * The LRU order is updated on `get()` and `set()` — both move the accessed
+     * key to the most-recent position.
+     */
+    maxSize?: number;
+}
+/**
+ * Reference `SyncStateStore` implementation backed by a `Map`.
+ *
+ * # LRU semantics
+ *
+ * `Map` iteration order is insertion order, so we implement LRU by
+ * `delete` + `set` on every access — the most-recently-touched key ends up
+ * at the end of the iteration, and the oldest is `entries.keys().next().value`.
+ *
+ * # Expiry
+ *
+ * Lazy on `get()` / `has()`: expired entries are deleted when touched.
+ * Background sweep (optional) reclaims entries that are never re-read.
+ */
+export declare class InMemoryStore implements SyncStateStore {
+    readonly _sync: true;
+    private readonly entries;
+    private readonly maxSize;
+    private cleanupTimer;
+    constructor(options?: InMemoryStoreOptions);
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, ttlMs?: number): void;
+    delete(key: string): void;
+    has(key: string): boolean;
+    clear(): void;
+    /**
+     * Return the count of live (non-expired) entries.
+     *
+     * Pure query — does NOT touch LRU order. Expired entries discovered during
+     * the scan are evicted opportunistically (they were already invisible to
+     * `get()`, so eviction has no observable effect beyond memory reclamation).
+     *
+     * Two-pass to avoid mutating the Map during iteration (spec-safe).
+     */
+    size(): number;
+    /**
+     * Stop the background cleanup timer and release internal state.
+     * Safe to call multiple times — subsequent calls are no-ops.
+     */
+    destroy(): void;
+    /**
+     * Sweep all entries and remove those past their expiry time.
+     * Called by the autoCleanup interval; not part of the public contract.
+     */
+    private _sweep;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/stores/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/stores/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAwB/C,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAID;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,QAAQ,CAAC,KAAK,EAAG,IAAI,CAAS;IAE9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,YAAY,CAA4C;gBAEpD,OAAO,GAAE,oBAAyB;IA0B9C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAiBlC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAcnD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAYzB,KAAK,IAAI,IAAI;IAIb;;;;;;;;OAQG;IACH,IAAI,IAAI,MAAM;IAiBd;;;OAGG;IACH,OAAO,IAAI,IAAI;IAOf;;;OAGG;IACH,OAAO,CAAC,MAAM;CAUf"}

package/dist/stores/memory.js

@@ -0,0 +1,137 @@
+function isUnrefable(t) {
+    return typeof t.unref === 'function';
+}
+// ─── Implementation ───────────────────────────────────────────────────────────
+/**
+ * Reference `SyncStateStore` implementation backed by a `Map`.
+ *
+ * # LRU semantics
+ *
+ * `Map` iteration order is insertion order, so we implement LRU by
+ * `delete` + `set` on every access — the most-recently-touched key ends up
+ * at the end of the iteration, and the oldest is `entries.keys().next().value`.
+ *
+ * # Expiry
+ *
+ * Lazy on `get()` / `has()`: expired entries are deleted when touched.
+ * Background sweep (optional) reclaims entries that are never re-read.
+ */
+export class InMemoryStore {
+    _sync = true;
+    entries = new Map();
+    maxSize;
+    cleanupTimer;
+    constructor(options = {}) {
+        const { autoCleanup = false, cleanupIntervalMs = 30_000, maxSize = Number.POSITIVE_INFINITY, } = options;
+        if (!Number.isFinite(maxSize) || maxSize <= 0) {
+            // Infinity is allowed (unbounded); any other non-positive finite value
+            // is a programmer error.
+            if (maxSize !== Number.POSITIVE_INFINITY) {
+                throw new RangeError(`Actly: InMemoryStore maxSize must be a positive finite number or Infinity, got ${maxSize}`);
+            }
+        }
+        this.maxSize = maxSize;
+        if (autoCleanup) {
+            const timer = setInterval(() => this._sweep(), cleanupIntervalMs);
+            if (isUnrefable(timer))
+                timer.unref();
+            this.cleanupTimer = timer;
+        }
+    }
+    get(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        // LRU refresh: move to most-recent position.
+        // delete + set is the canonical pattern for reordering a Map.
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        return entry.value;
+    }
+    set(key, value, ttlMs) {
+        // Evict if at capacity AND adding a new key (updates don't grow size).
+        if (!this.entries.has(key) && this.entries.size >= this.maxSize) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest !== undefined)
+                this.entries.delete(oldest);
+        }
+        const expiresAt = ttlMs != null && ttlMs > 0 ? Date.now() + ttlMs : null;
+        // delete + set ensures the key is moved to the most-recent position
+        // even on update, keeping LRU order consistent.
+        this.entries.delete(key);
+        this.entries.set(key, { value, expiresAt });
+    }
+    delete(key) {
+        this.entries.delete(key);
+    }
+    has(key) {
+        // Inline the expiry check to avoid the LRU side-effect of get().
+        // `has()` should be a pure query, not a touch.
+        const entry = this.entries.get(key);
+        if (!entry)
+            return false;
+        if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+            this.entries.delete(key);
+            return false;
+        }
+        return true;
+    }
+    clear() {
+        this.entries.clear();
+    }
+    /**
+     * Return the count of live (non-expired) entries.
+     *
+     * Pure query — does NOT touch LRU order. Expired entries discovered during
+     * the scan are evicted opportunistically (they were already invisible to
+     * `get()`, so eviction has no observable effect beyond memory reclamation).
+     *
+     * Two-pass to avoid mutating the Map during iteration (spec-safe).
+     */
+    size() {
+        const now = Date.now();
+        const expired = [];
+        let count = 0;
+        for (const [key, entry] of this.entries) {
+            if (entry.expiresAt !== null && entry.expiresAt <= now) {
+                expired.push(key);
+            }
+            else {
+                count++;
+            }
+        }
+        for (const key of expired)
+            this.entries.delete(key);
+        return count;
+    }
+    /**
+     * Stop the background cleanup timer and release internal state.
+     * Safe to call multiple times — subsequent calls are no-ops.
+     */
+    destroy() {
+        if (this.cleanupTimer !== undefined) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+    }
+    /**
+     * Sweep all entries and remove those past their expiry time.
+     * Called by the autoCleanup interval; not part of the public contract.
+     */
+    _sweep() {
+        const now = Date.now();
+        const expired = [];
+        for (const [key, entry] of this.entries) {
+            if (entry.expiresAt !== null && now > entry.expiresAt) {
+                expired.push(key);
+            }
+        }
+        for (const key of expired)
+            this.entries.delete(key);
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/stores/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/stores/memory.ts"],"names":[],"mappings":"AAkBA,SAAS,WAAW,CAAC,CAAU;IAC7B,OAAO,OAAQ,CAAoB,CAAC,KAAK,KAAK,UAAU,CAAA;AAC1D,CAAC;AAsCD,iFAAiF;AAEjF;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,aAAa;IACf,KAAK,GAAG,IAAa,CAAA;IAEb,OAAO,GAAG,IAAI,GAAG,EAA0B,CAAA;IAC3C,OAAO,CAAQ;IACxB,YAAY,CAA4C;IAEhE,YAAY,UAAgC,EAAE;QAC5C,MAAM,EACJ,WAAW,GAAG,KAAK,EACnB,iBAAiB,GAAG,MAAM,EAC1B,OAAO,GAAG,MAAM,CAAC,iBAAiB,GACnC,GAAG,OAAO,CAAA;QAEX,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,IAAI,CAAC,EAAE,CAAC;YAC9C,uEAAuE;YACvE,yBAAyB;YACzB,IAAI,OAAO,KAAK,MAAM,CAAC,iBAAiB,EAAE,CAAC;gBACzC,MAAM,IAAI,UAAU,CAClB,kFAAkF,OAAO,EAAE,CAC5F,CAAA;YACH,CAAC;QACH,CAAC;QAED,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;QAEtB,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,iBAAiB,CAAC,CAAA;YACjE,IAAI,WAAW,CAAC,KAAK,CAAC;gBAAE,KAAK,CAAC,KAAK,EAAE,CAAA;YACrC,IAAI,CAAC,YAAY,GAAG,KAAK,CAAA;QAC3B,CAAC;IACH,CAAC;IAED,GAAG,CAAI,GAAW;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACnC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAA;QAE5B,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YAC7D,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YACxB,OAAO,SAAS,CAAA;QAClB,CAAC;QAED,6CAA6C;QAC7C,8DAA8D;QAC9D,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACxB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;QAE5B,OAAO,KAAK,CAAC,KAAU,CAAA;IACzB,CAAC;IAED,GAAG,CAAI,GAAW,EAAE,KAAQ,EAAE,KAAc;QAC1C,uEAAuE;QACvE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAChE,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAA;YAC/C,IAAI,MAAM,KAAK,SAAS;gBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACvD,CAAC;QAED,MAAM,SAAS,GAAG,KAAK,IAAI,IAAI,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAA;QACxE,oEAAoE;QACpE,gDAAgD;QAChD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACxB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAA;IAC7C,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC1B,CAAC;IAED,GAAG,CAAC,GAAW;QACb,iEAAiE;QACjE,+CAA+C;QAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACnC,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAA;QACxB,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YAC7D,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YACxB,OAAO,KAAK,CAAA;QACd,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;IACtB,CAAC;IAED;;;;;;;;OAQG;IACH,IAAI;QACF,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QACtB,MAAM,OAAO,GAAa,EAAE,CAAA;QAC5B,IAAI,KAAK,GAAG,CAAC,CAAA;QAEb,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACxC,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,IAAI,KAAK,CAAC,SAAS,IAAI,GAAG,EAAE,CAAC;gBACvD,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;YACnB,CAAC;iBAAM,CAAC;gBACN,KAAK,EAAE,CAAA;YACT,CAAC;QACH,CAAC;QAED,KAAK,MAAM,GAAG,IAAI,OAAO;YAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACnD,OAAO,KAAK,CAAA;IACd,CAAC;IAED;;;OAGG;IACH,OAAO;QACL,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACpC,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,CAAA;YAChC,IAAI,CAAC,YAAY,GAAG,SAAS,CAAA;QAC/B,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,MAAM;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QACtB,MAAM,OAAO,GAAa,EAAE,CAAA;QAC5B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACxC,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;gBACtD,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;YACnB,CAAC;QACH,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,OAAO;YAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IACrD,CAAC;CACF"}

package/dist/types/index.d.ts

@@ -1,51 +1,131 @@
-/** The async function ACT wraps */
-export type ActFn<T> = () => Promise<T>;
-/** Where a successful result came from */
+/**
+ * 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 */
+    /**
+     * 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;
 }
 export interface ActFailure {
     ok: false;
     error: unknown;
-    /** Number of attempts made before final failure */
+    /**
+     * Number of attempts made before final failure.
+     * For dedupe joiners: mirrors the originator's attempt count.
+     */
     attempts: number;
 }
 export type ActResult<T> = ActSuccess<T> | ActFailure;
 export interface RetryOptions {
-    /** Total number of attempts including the first call. Must be >= 1. */
+    /**
+     * 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 ms. 0 = no delay. */
+    /**
+     * 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)
+     *  - `'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.
+     */
+    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.
+     * 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.
-     *
-     * @example
-     * shouldRetry: (err, attempt) =>
-     *   !(err instanceof HttpError && err.status < 500)
      */
     shouldRetry?: (error: unknown, attempt: number) => boolean;
 }
 export interface TimeoutOptions {
-    /** Abort after this many ms */
+    /**
+     * Abort after this many milliseconds.
+     * Must be a positive finite number.
+     */
     ms: number;
 }
 export interface DedupeOptions {
@@ -54,63 +134,100 @@ export interface DedupeOptions {
      * 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 ms */
+    /** Keep a successful result for this many milliseconds. Must be > 0. */
     ttl: number;
 }
 export interface ActOptions {
     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 }`
-     *
-     * Both are equivalent. The object form exists for forward compatibility.
+     * 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 timeout per attempt.
+     * 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 TotalTimeoutError if the deadline fires.
+     * 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;
 }
 /**
  * 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 RunMeta {
     attempts: number;
     source: ActSource;
 }
-/** Everything a policy receives about the current run */
+/** Everything a policy receives about the current run. */
 export interface PolicyContext {
     key: string;
-    store: StateStore;
+    store: AnyStateStore;
     meta: RunMeta;
 }
 /**
  * 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.
+ * 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>;
-/** Minimal key-value contract used by dedupe and cache policies */
-export interface StateStore {
-    get<T>(key: string): T | undefined;
-    set<T>(key: string, value: T, ttlMs?: number): void;
-    delete(key: string): void;
-    has(key: string): boolean;
-}
+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`.
+ */
+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":"AAEA,mCAAmC;AACnC,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,CAAA;AAEvC,0CAA0C;AAC1C,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,CAAA;AAEzC,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,EAAE,EAAE,IAAI,CAAA;IACR,KAAK,EAAE,CAAC,CAAA;IACR,MAAM,EAAE,SAAS,CAAA;IACjB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,KAAK,CAAA;IACT,KAAK,EAAE,OAAO,CAAA;IACd,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAA;AAIrD,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAA;IAChB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,aAAa,CAAA;IAC3C;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAA;CAC3D;AAED,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAA;CACX;AAED,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAS,YAAY,CAAA;IAC3B,OAAO,CAAC,EAAO,cAAc,CAAA;IAC7B;;;;;;;OAOG;IACH,MAAM,CAAC,EAAQ,OAAO,GAAG,aAAa,CAAA;IACtC,KAAK,CAAC,EAAS,YAAY,CAAA;IAC3B;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,cAAc,CAAA;CAC9B;AAID;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAI,SAAS,CAAA;CACpB;AAED,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAI,MAAM,CAAA;IACb,KAAK,EAAE,UAAU,CAAA;IACjB,IAAI,EAAG,OAAO,CAAA;CACf;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,KAAK,KAAK,CAAC,CAAC,CAAC,CAAA;AAI7E,mEAAmE;AACnE,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAA;IAClC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAC1B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}