actly 1.1.0 → 1.2.0

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,EAEhB,MAAM,mBAAmB,CAAA;AA4L1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,CA8JvB;AA+BD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAM/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"}