actly 1.1.0 → 1.1.5

package/dist/core/act.cjs

@@ -1,34 +1,110 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.act = act;
+exports.invalidate = invalidate;
+exports.withStore = withStore;
 const executor_js_1 = require("./executor.js");
 const retry_js_1 = require("../policies/retry.js");
 const timeout_js_1 = require("../policies/timeout.js");
 const dedupe_js_1 = require("../policies/dedupe.js");
 const cache_js_1 = require("../policies/cache.js");
 const memory_js_1 = require("../stores/memory.js");
+const base_js_1 = require("../stores/base.js");
+const abort_js_1 = require("../utils/abort.js");
+const validate_js_1 = require("../utils/validate.js");
 // Module-level default store so cache and dedupe persist across calls.
 // Always an InMemoryStore (SyncStateStore) — required because the default
 // chain may include dedupePolicy, which mandates synchronous store access.
-// For SSR isolation or per-test control, construct an InMemoryStore and
-// call execute() directly with an explicit store.
+// For SSR isolation or per-test control, use `withStore()` or call
+// `execute()` directly with an explicit store.
 const defaultStore = new memory_js_1.InMemoryStore();
+// Namespace prefixes used by policies. Kept here (not in policy files) so
+// `invalidate()` can resolve cache keys without importing policy internals.
+const CACHE_NS = 'cache:';
 /**
- * Execute fn with the given reliability policies.
+ * Normalise `dedupe: true` shorthand to `DedupeOptions`.
+ * Returns `undefined` if dedupe is disabled or absent.
+ */
+function normalizeDedupe(opt) {
+    if (opt === true)
+        return { enabled: true };
+    if (opt && typeof opt === 'object' && opt.enabled) {
+        return {
+            enabled: true,
+            ...(opt.inflightTtl !== undefined ? { inflightTtl: opt.inflightTtl } : {}),
+        };
+    }
+    return undefined;
+}
+/**
+ * Build the policy chain from `ActOptions`. The order is fixed and
+ * documented in `executor.ts`. Policies with no effect (e.g. `retry.attempts: 1`)
+ * are skipped — they would be pure overhead.
+ */
+function buildPolicies(options) {
+    const dedupe = normalizeDedupe(options.dedupe);
+    const policies = [];
+    // 0. Outermost: hard wall-clock budget over the entire operation.
+    //    If it fires, no inner policy can extend the deadline.
+    if (options.totalTimeout && options.totalTimeout.ms > 0) {
+        policies.push((0, timeout_js_1.totalTimeoutPolicy)(options.totalTimeout));
+    }
+    // 1. Cache: a hit short-circuits everything below it.
+    if (options.cache && options.cache.ttl > 0) {
+        policies.push((0, cache_js_1.cachePolicy)(options.cache));
+    }
+    // 2. Dedupe: collapses concurrent callers before retry fires.
+    if (dedupe) {
+        policies.push((0, dedupe_js_1.dedupePolicy)(dedupe));
+    }
+    // 3. Retry: owns the attempt loop.
+    //    `attempts: 1` is a no-op — skip to avoid overhead.
+    if (options.retry && options.retry.attempts > 1) {
+        policies.push((0, retry_js_1.retryPolicy)(options.retry));
+    }
+    // 4. Innermost: per-attempt clock. Resets on every retry.
+    if (options.timeout && options.timeout.ms > 0) {
+        policies.push((0, timeout_js_1.timeoutPolicy)(options.timeout));
+    }
+    return policies;
+}
+/**
+ * Build a root AbortController from `options.signal`.
+ *
+ * - If no user signal: returns a fresh controller that never aborts unless
+ *   an outer timeout policy aborts it.
+ * - If user signal is already aborted: returns a controller that is already
+ *   aborted with the user's reason (so the operation rejects immediately).
+ * - Otherwise: links the user signal to the controller.
+ */
+function buildRootSignal(userSignal) {
+    const controller = new AbortController();
+    if (userSignal)
+        (0, abort_js_1.linkSignal)(userSignal, controller);
+    return controller;
+}
+/**
+ * Execute `fn` with the given reliability policies.
  *
  * @param key     Stable identifier for this action. Scopes dedupe + cache.
- * @param fn      The async work to run.
+ * @param fn      The async work to run. Receives an `AbortSignal` for
+ *                cooperative cancellation (legacy `() => Promise<T>` is
+ *                still accepted — the signal is simply ignored).
  * @param options Which policies to apply and how. All fields are optional.
  *
- * @returns       ActResult<T> — always resolves, never throws.
- *                Check result.ok before reading result.value.
+ * @returns       `ActResult<T>` — always resolves, never throws.
+ *                Check `result.ok` before reading `result.value`.
  *
  * @example
- * const result = await act('user:42', () => fetchUser(42), {
- *   retry:   { attempts: 3, delayMs: 200, backoff: 'exponential' },
- *   timeout: { ms: 5_000 },
- *   dedupe:  true,
- *   cache:   { ttl: 60_000 },
+ * // With cooperative cancellation
+ * const result = await act('user:42', async (signal) => {
+ *   return fetch(`/api/users/42`, { signal })
+ * }, {
+ *   retry:        { attempts: 3, delayMs: 200, backoff: 'exponential' },
+ *   timeout:      { ms: 5_000 },
+ *   totalTimeout: { ms: 12_000 },
+ *   dedupe:       true,
+ *   cache:        { ttl: 60_000 },
  * })
  *
  * if (result.ok) {
@@ -38,36 +114,108 @@ const defaultStore = new memory_js_1.InMemoryStore();
  * }
  */
 async function act(key, fn, options = {}) {
+    // Validate input upfront. Programmer errors throw — they should not be
+    // swallowed into an ActFailure because the caller's code is broken.
+    (0, validate_js_1.assertKey)(key);
+    (0, validate_js_1.assertOptions)(options);
     const meta = { attempts: 1, source: 'fresh' };
-    // Normalise dedupe: true → { enabled: true } so the rest of the function
-    // always works with the object form.
-    const dedupe = typeof options.dedupe === 'boolean'
-        ? { enabled: options.dedupe }
-        : options.dedupe;
-    // Outermost -> innermost. See executor.ts for why this ordering matters.
-    const policies = [];
-    // totalTimeout sits before everything — it's a hard wall-clock budget over
-    // the entire operation. If it fires, no inner policy can extend the deadline.
-    if (options.totalTimeout && options.totalTimeout.ms > 0) {
-        policies.push((0, timeout_js_1.totalTimeoutPolicy)(options.totalTimeout)); // 0. hardest outer wall
-    }
-    if (options.cache && options.cache.ttl > 0) {
-        policies.push((0, cache_js_1.cachePolicy)(options.cache)); // 1. skip all on hit
-    }
-    if (dedupe?.enabled) {
-        policies.push((0, dedupe_js_1.dedupePolicy)()); // 2. collapse concurrent callers
-    }
-    if (options.retry && options.retry.attempts > 1) {
-        policies.push((0, retry_js_1.retryPolicy)(options.retry)); // 3. own the attempt loop
-    }
-    if (options.timeout && options.timeout.ms > 0) {
-        policies.push((0, timeout_js_1.timeoutPolicy)(options.timeout)); // 4. innermost — per-attempt clock
+    const rootController = buildRootSignal(options.signal);
+    // Fast-fail if the user signal is already aborted. We do this after
+    // validation so the caller still gets a TypeError for bad options rather
+    // than a silent abort.
+    if (rootController.signal.aborted) {
+        return { ok: false, error: rootController.signal.reason, attempts: 0 };
     }
+    const policies = buildPolicies(options);
     try {
-        const value = await (0, executor_js_1.execute)({ key, fn, policies, store: defaultStore, meta });
+        const value = await (0, executor_js_1.execute)({
+            key,
+            fn,
+            policies,
+            store: defaultStore,
+            meta,
+            signal: rootController.signal,
+        });
         return { ok: true, value, source: meta.source, attempts: meta.attempts };
     }
     catch (error) {
         return { ok: false, error, attempts: meta.attempts };
     }
 }
+/**
+ * Invalidate the cached value for `key` on the default module-level store.
+ *
+ * Only clears the cache slot — does not affect in-flight dedupe entries
+ * (those will settle on their own). Returns `true` if a cache entry was
+ * removed, `false` otherwise.
+ *
+ * Useful when you know the underlying data has changed and you want the
+ * next `act()` call to re-run `fn` instead of serving stale cache:
+ *
+ * ```ts
+ * await act('user:42', () => fetchUser(42), { cache: { ttl: 60_000 } })
+ * // ... user updates their profile ...
+ * invalidate('user:42')  // next call will re-fetch
+ * ```
+ */
+function invalidate(key) {
+    const cacheKey = CACHE_NS + key;
+    const existed = defaultStore.has(cacheKey);
+    defaultStore.delete(cacheKey);
+    return existed;
+}
+function withStore(store) {
+    const scopedAct = async (key, fn, options = {}) => {
+        (0, validate_js_1.assertKey)(key);
+        (0, validate_js_1.assertOptions)(options);
+        const meta = { attempts: 1, source: 'fresh' };
+        const rootController = buildRootSignal(options.signal);
+        if (rootController.signal.aborted) {
+            return { ok: false, error: rootController.signal.reason, attempts: 0 };
+        }
+        const policies = buildPolicies(options);
+        try {
+            const value = await (0, executor_js_1.execute)({
+                key,
+                fn,
+                policies,
+                store,
+                meta,
+                signal: rootController.signal,
+            });
+            return { ok: true, value, source: meta.source, attempts: meta.attempts };
+        }
+        catch (error) {
+            return { ok: false, error, attempts: meta.attempts };
+        }
+    };
+    // Build the `invalidate` implementation. The runtime branch on
+    // `isSyncStore` selects the correct path; the cast through `unknown`
+    // is required because TypeScript cannot narrow the union return type
+    // (`boolean | Promise<boolean>`) to match either overload signature
+    // individually. The overloads at the call site guarantee callers see
+    // the correct type.
+    const invalidateImpl = (key) => {
+        (0, validate_js_1.assertKey)(key);
+        const cacheKey = CACHE_NS + key;
+        if ((0, base_js_1.isSyncStore)(store)) {
+            const existed = store.has(cacheKey);
+            store.delete(cacheKey);
+            return existed;
+        }
+        // Async store branch.
+        return (async () => {
+            const existed = await store.has(cacheKey);
+            await store.delete(cacheKey);
+            return existed;
+        })();
+    };
+    // Attach `invalidate` and `store` to the function object. We use
+    // `Object.assign` rather than mutation so the types narrow cleanly at
+    // the call site. The cast through `unknown` is necessary because the
+    // implementation signature is wider than either overload.
+    return Object.assign(scopedAct, {
+        invalidate: invalidateImpl,
+        store,
+    });
+}

package/dist/core/act.d.ts

@@ -1,20 +1,26 @@
-import type { ActFn, ActOptions, ActResult } from '../types/index.js';
+import type { ActFn, ActOptions, ActResult, AnyStateStore, SyncStateStore, AsyncStateStore } from '../types/index.js';
 /**
- * Execute fn with the given reliability policies.
+ * Execute `fn` with the given reliability policies.
  *
  * @param key     Stable identifier for this action. Scopes dedupe + cache.
- * @param fn      The async work to run.
+ * @param fn      The async work to run. Receives an `AbortSignal` for
+ *                cooperative cancellation (legacy `() => Promise<T>` is
+ *                still accepted — the signal is simply ignored).
  * @param options Which policies to apply and how. All fields are optional.
  *
- * @returns       ActResult<T> — always resolves, never throws.
- *                Check result.ok before reading result.value.
+ * @returns       `ActResult<T>` — always resolves, never throws.
+ *                Check `result.ok` before reading `result.value`.
  *
  * @example
- * const result = await act('user:42', () => fetchUser(42), {
- *   retry:   { attempts: 3, delayMs: 200, backoff: 'exponential' },
- *   timeout: { ms: 5_000 },
- *   dedupe:  true,
- *   cache:   { ttl: 60_000 },
+ * // With cooperative cancellation
+ * const result = await act('user:42', async (signal) => {
+ *   return fetch(`/api/users/42`, { signal })
+ * }, {
+ *   retry:        { attempts: 3, delayMs: 200, backoff: 'exponential' },
+ *   timeout:      { ms: 5_000 },
+ *   totalTimeout: { ms: 12_000 },
+ *   dedupe:       true,
+ *   cache:        { ttl: 60_000 },
  * })
  *
  * if (result.ok) {
@@ -24,4 +30,69 @@ import type { ActFn, ActOptions, ActResult } from '../types/index.js';
  * }
  */
 export declare function act<T>(key: string, fn: ActFn<T>, options?: ActOptions): Promise<ActResult<T>>;
+/**
+ * Invalidate the cached value for `key` on the default module-level store.
+ *
+ * Only clears the cache slot — does not affect in-flight dedupe entries
+ * (those will settle on their own). Returns `true` if a cache entry was
+ * removed, `false` otherwise.
+ *
+ * Useful when you know the underlying data has changed and you want the
+ * next `act()` call to re-run `fn` instead of serving stale cache:
+ *
+ * ```ts
+ * await act('user:42', () => fetchUser(42), { cache: { ttl: 60_000 } })
+ * // ... user updates their profile ...
+ * invalidate('user:42')  // next call will re-fetch
+ * ```
+ */
+export declare function invalidate(key: string): boolean;
+/** Result of `withStore()` for a sync store: `act` + sync `invalidate`. */
+export interface ScopedActSync {
+    <T>(key: string, fn: ActFn<T>, options?: ActOptions): Promise<ActResult<T>>;
+    invalidate(key: string): boolean;
+    /** The store this scope is bound to. Useful for `store.destroy()` etc. */
+    readonly store: AnyStateStore;
+}
+/** Result of `withStore()` for an async store: `act` + async `invalidate`. */
+export interface ScopedActAsync {
+    <T>(key: string, fn: ActFn<T>, options?: ActOptions): Promise<ActResult<T>>;
+    invalidate(key: string): Promise<boolean>;
+    readonly store: AnyStateStore;
+}
+/**
+ * Create a scoped `act` function bound to an explicit store.
+ *
+ * Use this for:
+ *  - **SSR request isolation**: one store per request, no cross-request
+ *    cache/dedupe leakage.
+ *  - **Multi-tenant scenarios**: one store per tenant, no cross-tenant
+ *    data leakage.
+ *  - **Test isolation**: each test gets a fresh store, no shared state.
+ *
+ * The returned function has the same signature as `act()`. It also exposes
+ * an `invalidate(key)` method and a `store` reference for cleanup.
+ *
+ * For sync stores, `invalidate` returns `boolean` synchronously.
+ * For async stores, `invalidate` returns `Promise<boolean>`.
+ *
+ * @example
+ * ```ts
+ * import { withStore, InMemoryStore } from 'actly'
+ *
+ * const store = new InMemoryStore({ maxSize: 1000, autoCleanup: true })
+ * const act = withStore(store)
+ *
+ * try {
+ *   await act('user:42', () => fetchUser(42), { cache: { ttl: 60_000 } })
+ *   // ... user updates their profile ...
+ *   act.invalidate('user:42')  // next call re-fetches
+ * } finally {
+ *   store.destroy()
+ * }
+ * ```
+ */
+export declare function withStore(store: SyncStateStore): ScopedActSync;
+export declare function withStore(store: AsyncStateStore): ScopedActAsync;
+export declare function withStore(store: AnyStateStore): ScopedActSync | ScopedActAsync;
 //# sourceMappingURL=act.d.ts.map

package/dist/core/act.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../src/core/act.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAA0B,MAAM,mBAAmB,CAAA;AAe7F;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,GAAG,CAAC,CAAC,EACzB,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,EACZ,OAAO,GAAE,UAAe,GACvB,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAwCvB"}
+{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../src/core/act.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,EACL,UAAU,EACV,SAAS,EAGT,aAAa,EACb,cAAc,EACd,eAAe,EAChB,MAAM,mBAAmB,CAAA;AAgG1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,GAAG,CAAC,CAAC,EACzB,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,EACZ,OAAO,GAAE,UAAe,GACvB,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CA+BvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAK/C;AAID,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAA;IAC3E,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;CAC9B;AAED,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAA;IAC3E,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACzC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,aAAa,CAAA;AAC/D,wBAAgB,SAAS,CAAC,KAAK,EAAE,eAAe,GAAG,cAAc,CAAA;AACjE,wBAAgB,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,GAAG,cAAc,CAAA"}

package/dist/core/act.js

@@ -4,28 +4,102 @@ import { timeoutPolicy, totalTimeoutPolicy } from '../policies/timeout.js';
 import { dedupePolicy } from '../policies/dedupe.js';
 import { cachePolicy } from '../policies/cache.js';
 import { InMemoryStore } from '../stores/memory.js';
+import { isSyncStore } from '../stores/base.js';
+import { linkSignal } from '../utils/abort.js';
+import { assertKey, assertOptions, } from '../utils/validate.js';
 // Module-level default store so cache and dedupe persist across calls.
 // Always an InMemoryStore (SyncStateStore) — required because the default
 // chain may include dedupePolicy, which mandates synchronous store access.
-// For SSR isolation or per-test control, construct an InMemoryStore and
-// call execute() directly with an explicit store.
+// For SSR isolation or per-test control, use `withStore()` or call
+// `execute()` directly with an explicit store.
 const defaultStore = new InMemoryStore();
+// Namespace prefixes used by policies. Kept here (not in policy files) so
+// `invalidate()` can resolve cache keys without importing policy internals.
+const CACHE_NS = 'cache:';
 /**
- * Execute fn with the given reliability policies.
+ * Normalise `dedupe: true` shorthand to `DedupeOptions`.
+ * Returns `undefined` if dedupe is disabled or absent.
+ */
+function normalizeDedupe(opt) {
+    if (opt === true)
+        return { enabled: true };
+    if (opt && typeof opt === 'object' && opt.enabled) {
+        return {
+            enabled: true,
+            ...(opt.inflightTtl !== undefined ? { inflightTtl: opt.inflightTtl } : {}),
+        };
+    }
+    return undefined;
+}
+/**
+ * Build the policy chain from `ActOptions`. The order is fixed and
+ * documented in `executor.ts`. Policies with no effect (e.g. `retry.attempts: 1`)
+ * are skipped — they would be pure overhead.
+ */
+function buildPolicies(options) {
+    const dedupe = normalizeDedupe(options.dedupe);
+    const policies = [];
+    // 0. Outermost: hard wall-clock budget over the entire operation.
+    //    If it fires, no inner policy can extend the deadline.
+    if (options.totalTimeout && options.totalTimeout.ms > 0) {
+        policies.push(totalTimeoutPolicy(options.totalTimeout));
+    }
+    // 1. Cache: a hit short-circuits everything below it.
+    if (options.cache && options.cache.ttl > 0) {
+        policies.push(cachePolicy(options.cache));
+    }
+    // 2. Dedupe: collapses concurrent callers before retry fires.
+    if (dedupe) {
+        policies.push(dedupePolicy(dedupe));
+    }
+    // 3. Retry: owns the attempt loop.
+    //    `attempts: 1` is a no-op — skip to avoid overhead.
+    if (options.retry && options.retry.attempts > 1) {
+        policies.push(retryPolicy(options.retry));
+    }
+    // 4. Innermost: per-attempt clock. Resets on every retry.
+    if (options.timeout && options.timeout.ms > 0) {
+        policies.push(timeoutPolicy(options.timeout));
+    }
+    return policies;
+}
+/**
+ * Build a root AbortController from `options.signal`.
+ *
+ * - If no user signal: returns a fresh controller that never aborts unless
+ *   an outer timeout policy aborts it.
+ * - If user signal is already aborted: returns a controller that is already
+ *   aborted with the user's reason (so the operation rejects immediately).
+ * - Otherwise: links the user signal to the controller.
+ */
+function buildRootSignal(userSignal) {
+    const controller = new AbortController();
+    if (userSignal)
+        linkSignal(userSignal, controller);
+    return controller;
+}
+/**
+ * Execute `fn` with the given reliability policies.
  *
  * @param key     Stable identifier for this action. Scopes dedupe + cache.
- * @param fn      The async work to run.
+ * @param fn      The async work to run. Receives an `AbortSignal` for
+ *                cooperative cancellation (legacy `() => Promise<T>` is
+ *                still accepted — the signal is simply ignored).
  * @param options Which policies to apply and how. All fields are optional.
  *
- * @returns       ActResult<T> — always resolves, never throws.
- *                Check result.ok before reading result.value.
+ * @returns       `ActResult<T>` — always resolves, never throws.
+ *                Check `result.ok` before reading `result.value`.
  *
  * @example
- * const result = await act('user:42', () => fetchUser(42), {
- *   retry:   { attempts: 3, delayMs: 200, backoff: 'exponential' },
- *   timeout: { ms: 5_000 },
- *   dedupe:  true,
- *   cache:   { ttl: 60_000 },
+ * // With cooperative cancellation
+ * const result = await act('user:42', async (signal) => {
+ *   return fetch(`/api/users/42`, { signal })
+ * }, {
+ *   retry:        { attempts: 3, delayMs: 200, backoff: 'exponential' },
+ *   timeout:      { ms: 5_000 },
+ *   totalTimeout: { ms: 12_000 },
+ *   dedupe:       true,
+ *   cache:        { ttl: 60_000 },
  * })
  *
  * if (result.ok) {
@@ -35,37 +109,109 @@ const defaultStore = new InMemoryStore();
  * }
  */
 export async function act(key, fn, options = {}) {
+    // Validate input upfront. Programmer errors throw — they should not be
+    // swallowed into an ActFailure because the caller's code is broken.
+    assertKey(key);
+    assertOptions(options);
     const meta = { attempts: 1, source: 'fresh' };
-    // Normalise dedupe: true → { enabled: true } so the rest of the function
-    // always works with the object form.
-    const dedupe = typeof options.dedupe === 'boolean'
-        ? { enabled: options.dedupe }
-        : options.dedupe;
-    // Outermost -> innermost. See executor.ts for why this ordering matters.
-    const policies = [];
-    // totalTimeout sits before everything — it's a hard wall-clock budget over
-    // the entire operation. If it fires, no inner policy can extend the deadline.
-    if (options.totalTimeout && options.totalTimeout.ms > 0) {
-        policies.push(totalTimeoutPolicy(options.totalTimeout)); // 0. hardest outer wall
-    }
-    if (options.cache && options.cache.ttl > 0) {
-        policies.push(cachePolicy(options.cache)); // 1. skip all on hit
-    }
-    if (dedupe?.enabled) {
-        policies.push(dedupePolicy()); // 2. collapse concurrent callers
-    }
-    if (options.retry && options.retry.attempts > 1) {
-        policies.push(retryPolicy(options.retry)); // 3. own the attempt loop
-    }
-    if (options.timeout && options.timeout.ms > 0) {
-        policies.push(timeoutPolicy(options.timeout)); // 4. innermost — per-attempt clock
+    const rootController = buildRootSignal(options.signal);
+    // Fast-fail if the user signal is already aborted. We do this after
+    // validation so the caller still gets a TypeError for bad options rather
+    // than a silent abort.
+    if (rootController.signal.aborted) {
+        return { ok: false, error: rootController.signal.reason, attempts: 0 };
     }
+    const policies = buildPolicies(options);
     try {
-        const value = await execute({ key, fn, policies, store: defaultStore, meta });
+        const value = await execute({
+            key,
+            fn,
+            policies,
+            store: defaultStore,
+            meta,
+            signal: rootController.signal,
+        });
         return { ok: true, value, source: meta.source, attempts: meta.attempts };
     }
     catch (error) {
         return { ok: false, error, attempts: meta.attempts };
     }
 }
+/**
+ * Invalidate the cached value for `key` on the default module-level store.
+ *
+ * Only clears the cache slot — does not affect in-flight dedupe entries
+ * (those will settle on their own). Returns `true` if a cache entry was
+ * removed, `false` otherwise.
+ *
+ * Useful when you know the underlying data has changed and you want the
+ * next `act()` call to re-run `fn` instead of serving stale cache:
+ *
+ * ```ts
+ * await act('user:42', () => fetchUser(42), { cache: { ttl: 60_000 } })
+ * // ... user updates their profile ...
+ * invalidate('user:42')  // next call will re-fetch
+ * ```
+ */
+export function invalidate(key) {
+    const cacheKey = CACHE_NS + key;
+    const existed = defaultStore.has(cacheKey);
+    defaultStore.delete(cacheKey);
+    return existed;
+}
+export function withStore(store) {
+    const scopedAct = async (key, fn, options = {}) => {
+        assertKey(key);
+        assertOptions(options);
+        const meta = { attempts: 1, source: 'fresh' };
+        const rootController = buildRootSignal(options.signal);
+        if (rootController.signal.aborted) {
+            return { ok: false, error: rootController.signal.reason, attempts: 0 };
+        }
+        const policies = buildPolicies(options);
+        try {
+            const value = await execute({
+                key,
+                fn,
+                policies,
+                store,
+                meta,
+                signal: rootController.signal,
+            });
+            return { ok: true, value, source: meta.source, attempts: meta.attempts };
+        }
+        catch (error) {
+            return { ok: false, error, attempts: meta.attempts };
+        }
+    };
+    // Build the `invalidate` implementation. The runtime branch on
+    // `isSyncStore` selects the correct path; the cast through `unknown`
+    // is required because TypeScript cannot narrow the union return type
+    // (`boolean | Promise<boolean>`) to match either overload signature
+    // individually. The overloads at the call site guarantee callers see
+    // the correct type.
+    const invalidateImpl = (key) => {
+        assertKey(key);
+        const cacheKey = CACHE_NS + key;
+        if (isSyncStore(store)) {
+            const existed = store.has(cacheKey);
+            store.delete(cacheKey);
+            return existed;
+        }
+        // Async store branch.
+        return (async () => {
+            const existed = await store.has(cacheKey);
+            await store.delete(cacheKey);
+            return existed;
+        })();
+    };
+    // Attach `invalidate` and `store` to the function object. We use
+    // `Object.assign` rather than mutation so the types narrow cleanly at
+    // the call site. The cast through `unknown` is necessary because the
+    // implementation signature is wider than either overload.
+    return Object.assign(scopedAct, {
+        invalidate: invalidateImpl,
+        store,
+    });
+}
 //# sourceMappingURL=act.js.map

package/dist/core/act.js.map

@@ -1 +1 @@
-{"version":3,"file":"act.js","sourceRoot":"","sources":["../../src/core/act.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAa,eAAe,CAAA;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAS,sBAAsB,CAAA;AACrD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAQ,uBAAuB,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,MAAS,sBAAsB,CAAA;AACrD,OAAO,EAAE,aAAa,EAAE,MAAO,qBAAqB,CAAA;AAEpD,uEAAuE;AACvE,0EAA0E;AAC1E,2EAA2E;AAC3E,wEAAwE;AACxE,kDAAkD;AAClD,MAAM,YAAY,GAAG,IAAI,aAAa,EAAE,CAAA;AAExC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,GAAG,CACvB,GAAW,EACX,EAAY,EACZ,UAAsB,EAAE;IAExB,MAAM,IAAI,GAAY,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;IAEtD,yEAAyE;IACzE,qCAAqC;IACrC,MAAM,MAAM,GAAG,OAAO,OAAO,CAAC,MAAM,KAAK,SAAS;QAChD,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE;QAC7B,CAAC,CAAC,OAAO,CAAC,MAAM,CAAA;IAElB,yEAAyE;IACzE,MAAM,QAAQ,GAA4B,EAAE,CAAA;IAE5C,2EAA2E;IAC3E,8EAA8E;IAC9E,IAAI,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;QACxD,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAI,OAAO,CAAC,YAAY,CAAC,CAAC,CAAA,CAAC,wBAAwB;IACrF,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC;QAC3C,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAA,CAAe,qBAAqB;IAClF,CAAC;IAED,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;QACpB,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAK,CAAC,CAAA,CAA2B,iCAAiC;IAC9F,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;QAChD,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAA,CAAe,0BAA0B;IACvF,CAAC;IAED,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;QAC9C,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAI,OAAO,CAAC,OAAO,CAAC,CAAC,CAAA,CAAW,mCAAmC;IAChG,CAAC;IAED,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAA;QAC7E,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAA;IAC1E,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAA;IACtD,CAAC;AACH,CAAC"}
+{"version":3,"file":"act.js","sourceRoot":"","sources":["../../src/core/act.ts"],"names":[],"mappings":"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"}