actly 1.0.2 → 1.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 ACT contributors
+Copyright (c) 2026 ACT contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -0,0 +1,380 @@
+# actly
+
+**Reliability primitive for async functions.**  
+Retry. Timeout. Dedupe. Cache. Composable, typed, zero-throw.
+
+```bash
+npm install actly
+```
+
+> Requires Node 18+. Ships ESM + CJS. Zero dependencies.
+
+---
+
+## The problem
+
+Every async call can fail. Networks blip. Services time out. The same UI mounts three times and fires the same fetch in parallel. You need retry logic, but not for 4xx errors. You need timeouts, but not the kind that let retry loops run forever.
+
+These patterns are solved the same way every time. `actly` solves them once.
+
+---
+
+## Quick start
+
+```ts
+import { act } from 'actly'
+
+const result = await act('user:42', () => fetchUser(42))
+
+if (result.ok) {
+  console.log(result.value)    // T
+  console.log(result.source)   // 'fresh' | 'cache'
+  console.log(result.attempts) // number
+} else {
+  console.error(result.error)  // unknown — never throws
+}
+```
+
+`act` always resolves. It never rejects. You check `.ok` and move on.
+
+---
+
+## API
+
+```ts
+act<T>(key: string, fn: () => Promise<T>, options?: ActOptions): Promise<ActResult<T>>
+```
+
+| Argument | Type | Description |
+|---|---|---|
+| `key` | `string` | Stable, unique identifier. Scopes dedupe and cache state. |
+| `fn` | `() => Promise<T>` | The async function to execute. |
+| `options` | `ActOptions` | All optional. See policies below. |
+
+### Result shape
+
+```ts
+type ActResult<T> =
+  | { ok: true;  value: T; source: 'fresh' | 'cache'; attempts: number }
+  | { ok: false; error: unknown;                       attempts: number }
+```
+
+---
+
+## Policies
+
+All policies are optional and compose freely. The execution order is **fixed**:
+
+```
+totalTimeout → cache → dedupe → retry → timeout
+```
+
+### Retry
+
+```ts
+const result = await act('payments:charge', () => chargeCard(payload), {
+  retry: {
+    attempts: 3,            // total attempts (including first)
+    delayMs:  200,          // base delay between attempts (ms)
+    backoff:  'exponential' // 'none' | 'linear' | 'exponential'
+  },
+})
+```
+
+`result.attempts` tells you how many tries it took.
+
+#### Selective retry with `shouldRetry`
+
+By default, every error triggers a retry. Use `shouldRetry` to skip retrying permanent errors — a `404` will never recover, a `503` might.
+
+```ts
+const result = await act('api:resource', () => fetchResource(id), {
+  retry: {
+    attempts: 4,
+    delayMs:  150,
+    backoff:  'exponential',
+    shouldRetry: (err, attempt) => {
+      if (err instanceof HttpError && err.status < 500) return false
+      return true
+    },
+  },
+})
+```
+
+`shouldRetry(error, attempt)` receives the error and the 1-based attempt number. Return `false` to surface the error immediately. Not called on the final attempt — that always surfaces.
+
+---
+
+### Timeout
+
+Per-attempt deadline. Each retry gets a fresh clock.
+
+```ts
+import { act, TimeoutError } from 'actly'
+
+const result = await act('geo:lookup', () => lookupCoords(ip), {
+  timeout: { ms: 3_000 },
+})
+
+if (!result.ok && result.error instanceof TimeoutError) {
+  console.log(`timed out after ${result.error.ms}ms`)
+}
+```
+
+---
+
+### Total timeout
+
+Hard budget over the **entire** operation — all attempts, delays, and per-attempt timeouts combined. The per-attempt `timeout` resets on retry; `totalTimeout` does not.
+
+```ts
+import { act, TimeoutError, TotalTimeoutError } from 'actly'
+
+const result = await act('search:query', () => runQuery(q), {
+  retry:        { attempts: 5, delayMs: 100, backoff: 'linear' },
+  timeout:      { ms: 2_000 },  // per attempt
+  totalTimeout: { ms: 8_000 },  // whole operation
+})
+
+if (!result.ok) {
+  if (result.error instanceof TotalTimeoutError) {
+    console.log(`budget exhausted after ${result.error.ms}ms`)
+  } else if (result.error instanceof TimeoutError) {
+    console.log(`last attempt timed out after ${result.error.ms}ms`)
+  }
+}
+```
+
+`TotalTimeoutError` and `TimeoutError` are separate classes — `instanceof` distinguishes which deadline fired.
+
+---
+
+### Dedupe
+
+Concurrent calls with the same key collapse into one in-flight Promise. The first caller executes; the rest wait and receive the same result. After settlement, the next call starts fresh.
+
+```ts
+const result = await act('config:load', () => loadRemoteConfig(), {
+  dedupe: true,
+})
+```
+
+`dedupe: { enabled: true }` is also valid — object form for forward compatibility.
+
+> **Note:** Deduped callers (those that joined an in-flight Promise) always receive `attempts: 1` in their result, because the retry counter belongs to the originating call. This is a known trade-off.
+
+---
+
+### Cache
+
+Stores successful results for `ttl` milliseconds. Failures are never cached. A cache hit short-circuits everything — dedupe, retry, and timeout are all skipped.
+
+```ts
+const result = await act('flags:all', () => fetchFeatureFlags(), {
+  cache: { ttl: 60_000 },
+})
+
+console.log(result.source) // 'fresh' on miss, 'cache' on hit
+```
+
+---
+
+### Combining policies
+
+```ts
+const result = await act('product:detail', () => fetchProduct(id), {
+  totalTimeout: { ms: 10_000 },  // outermost wall
+  cache:        { ttl: 30_000 }, // short-circuits on hit
+  dedupe:       true,            // collapses concurrent calls
+  retry:        { attempts: 3, delayMs: 100, backoff: 'linear' },
+  timeout:      { ms: 3_000 },   // per attempt
+})
+```
+
+---
+
+## Options reference
+
+```ts
+interface ActOptions {
+  retry?:        RetryOptions
+  timeout?:      TimeoutOptions      // per-attempt
+  totalTimeout?: TimeoutOptions      // entire operation
+  dedupe?:       boolean | DedupeOptions
+  cache?:        CacheOptions
+}
+
+interface RetryOptions {
+  attempts:     number
+  delayMs?:     number
+  backoff?:     'none' | 'linear' | 'exponential'
+  shouldRetry?: (error: unknown, attempt: number) => boolean
+}
+
+interface TimeoutOptions  { ms: number }
+interface DedupeOptions   { enabled: boolean }
+interface CacheOptions    { ttl: number }
+```
+
+---
+
+## Exported values
+
+```ts
+import {
+  act,                       // primary function
+  InMemoryStore,             // isolated store for SSR / tests
+  TimeoutError,              // per-attempt deadline (.ms)
+  TotalTimeoutError,         // total budget exhausted (.ms)
+} from 'actly'
+```
+
+---
+
+## Exported types
+
+```ts
+import type {
+  ActResult, ActSuccess, ActFailure, ActSource,
+  ActOptions, ActFn,
+  RetryOptions, TimeoutOptions, DedupeOptions, CacheOptions,
+  // v1.1 — store interfaces
+  SyncStateStore,
+  AsyncStateStore,
+  InMemoryStoreOptions,
+  // v1.0 alias — still valid, zero migration needed
+  StateStore,
+} from 'actly'
+```
+
+---
+
+## Custom store
+
+By default `act` uses a module-level `InMemoryStore`. For SSR request isolation or test control, instantiate your own:
+
+```ts
+import { InMemoryStore } from 'actly'
+
+// Basic
+const store = new InMemoryStore()
+
+// With background cleanup (useful for long-lived server-side stores)
+const store = new InMemoryStore({
+  autoCleanup: true,
+  cleanupIntervalMs: 60_000, // sweep every 60s (default: 30s)
+})
+
+// Always call destroy() when done to prevent timer leaks
+store.destroy()
+```
+
+`InMemoryStore` satisfies `SyncStateStore`. Use it with `execute()` directly for full control.
+
+### Async store (v1.1+)
+
+For external cache backends (Redis, Upstash, etc.), implement `AsyncStateStore`:
+
+```ts
+import type { AsyncStateStore } from 'actly'
+
+class RedisStore implements AsyncStateStore {
+  readonly _sync = false as const
+
+  async get<T>(key: string): Promise<T | undefined> { /* ... */ }
+  async set<T>(key: string, value: T, ttlMs?: number): Promise<void> { /* ... */ }
+  async delete(key: string): Promise<void> { /* ... */ }
+  async has(key: string): Promise<boolean> { /* ... */ }
+  async clear(): Promise<void> { /* ... */ }
+  async size(): Promise<number> { /* ... */ }
+}
+```
+
+> `AsyncStateStore` is compatible with `cache` only. Using it with `dedupe` is a TypeScript error and a runtime error — dedupe requires synchronous store access. See `SyncStateStore` docs for the reason.
+
+---
+
+## Store interfaces
+
+```ts
+interface SyncStateStore {
+  readonly _sync: true
+  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
+  size(): number
+}
+
+interface AsyncStateStore {
+  readonly _sync: false
+  get<T>(key: string): Promise<T | undefined>
+  set<T>(key: string, value: T, ttlMs?: number): Promise<void>
+  delete(key: string): Promise<void>
+  has(key: string): Promise<boolean>
+  clear(): Promise<void>
+  size(): Promise<number>
+}
+```
+
+The `_sync` discriminant is read at runtime by the executor to enforce the dedupe constraint. Set it as a `readonly` literal — `true as const` or `false as const`.
+
+---
+
+## Zero-throw contract
+
+`act()` always resolves. Under any condition — network error, thrown exception, timeout, total budget exhaustion — the result is an `ActFailure`, not a rejected promise. This contract holds across all versions.
+
+---
+
+## Philosophy
+
+One function. One return type. No exceptions in userland.
+
+The key is your responsibility. Make it stable and specific. `user:42` is good. `fetch` is not.
+
+Policies are composable but intentionally constrained. There is no builder API, no middleware system, no hooks. If you need something `act` doesn't do, write a wrapper around it — that's the right boundary.
+
+---
+
+## Changelog
+
+### v1.1.0 — 2026-06-01
+
+**New features**
+
+- **`AsyncStateStore` interface** — plug in any async key-value backend (Redis, Upstash, Cloudflare KV). Compatible with `cache` policy. Using with `dedupe` is a compile-time and runtime error by design.
+- **`SyncStateStore` interface** — the canonical public name for what was previously the internal store shape. `StateStore` is preserved as an alias with zero breakage for existing code.
+- **`InMemoryStore` is now a public export** — construct isolated stores for SSR request isolation, per-test control, or multi-tenant scenarios. Accepts `InMemoryStoreOptions`.
+- **`InMemoryStoreOptions`** — opt-in `autoCleanup` with configurable `cleanupIntervalMs`. Call `destroy()` to stop the background timer and prevent leaks.
+- **`TotalTimeoutError`** — new error class thrown when `totalTimeout` fires. Distinct from `TimeoutError` (per-attempt) so `instanceof` tells you which deadline fired.
+- **`totalTimeout` option** — hard wall-clock budget over the entire operation including all retry attempts and delays. Use alongside `timeout` to express both per-attempt and total constraints.
+- **`dedupe: true` shorthand** — equivalent to `dedupe: { enabled: true }`. Object form still valid for forward compatibility.
+- **`isSyncStore()` / `isAsyncStore()` type guards** — exported from `actly` for consumers building custom policy chains or store adapters.
+
+**Internal improvements**
+
+- Executor validates sync-store requirement at chain-build time — async store + `dedupePolicy` throws immediately with a clear message instead of producing silent correctness failures.
+- `dedupePolicy` tagged with `REQUIRES_SYNC_STORE` symbol — allows executor to detect the constraint without importing the policy module (avoids circular deps).
+- `cachePolicy` now branches sync/async paths — fast synchronous path for `InMemoryStore`, async-await path for external stores.
+
+**Non-breaking changes**
+
+- `StateStore` preserved as type alias for `SyncStateStore` — all v1.0 code compiles without changes.
+- All new exports are purely additive.
+
+---
+
+### v1.0.1
+
+- Initial stable release.
+- `act()`, `retry`, `timeout`, `totalTimeout`, `dedupe`, `cache`.
+- `TimeoutError` exported for `instanceof` checks.
+- Zero dependencies. ESM + CJS. Node 18+.
+
+---
+
+## License
+
+MIT

package/dist/core/act.cjs

@@ -6,11 +6,13 @@ 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 store_js_1 = require("../state/store.js");
+const memory_js_1 = require("../stores/memory.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 — it accepts any StateStore implementation.
-const defaultStore = new store_js_1.InMemoryStore();
+// call execute() directly with an explicit store.
+const defaultStore = new memory_js_1.InMemoryStore();
 /**
  * Execute fn with the given reliability policies.
  *

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;AAa7F;;;;;;;;;;;;;;;;;;;;;;;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,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"}

package/dist/core/act.js

@@ -3,10 +3,12 @@ import { retryPolicy } from '../policies/retry.js';
 import { timeoutPolicy, totalTimeoutPolicy } from '../policies/timeout.js';
 import { dedupePolicy } from '../policies/dedupe.js';
 import { cachePolicy } from '../policies/cache.js';
-import { InMemoryStore } from '../state/store.js';
+import { InMemoryStore } from '../stores/memory.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 — it accepts any StateStore implementation.
+// call execute() directly with an explicit store.
 const defaultStore = new InMemoryStore();
 /**
  * Execute fn with the given reliability policies.

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,mBAAmB,CAAA;AAElD,uEAAuE;AACvE,wEAAwE;AACxE,sEAAsE;AACtE,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":"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"}

package/dist/core/executor.cjs

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUIRES_SYNC_STORE = void 0;
 exports.execute = execute;
+const base_js_1 = require("../stores/base.js");
+// Symbol stamped onto PolicyApplier functions by dedupePolicy.
+// Lets execute() detect a dedupe policy without importing the policy module
+// (which would create a circular dep) or doing fragile name-sniffing.
+exports.REQUIRES_SYNC_STORE = Symbol('actly.requiresSyncStore');
 /**
  * Pure execution engine.
  *
@@ -9,6 +15,16 @@ exports.execute = execute;
  * Policy implementations live in /policies and are wired in core/act.ts.
  */
 async function execute(input) {
+    // Guard: if any policy in the chain requires a sync store, the provided
+    // store must be synchronous. An async store + dedupePolicy is a silent
+    // correctness failure, not just a performance issue — catch it here rather
+    // than letting it produce subtly wrong dedupe behaviour at runtime.
+    const needsSync = input.policies.some(p => p[exports.REQUIRES_SYNC_STORE]);
+    if (needsSync && !(0, base_js_1.isSyncStore)(input.store)) {
+        throw new Error('Actly: dedupePolicy requires a SyncStateStore (store._sync === true). ' +
+            'The provided store does not satisfy this constraint. ' +
+            'Either remove dedupe from the policy chain or use InMemoryStore.');
+    }
     const ctx = {
         key: input.key,
         store: input.store,

package/dist/core/executor.d.ts

@@ -1,4 +1,5 @@
-import type { ActFn, PolicyApplier, StateStore, RunMeta } from '../types/index.js';
+import type { ActFn, PolicyApplier, AnyStateStore, RunMeta } from '../types/index.js';
+export declare const REQUIRES_SYNC_STORE: unique symbol;
 export interface ExecutorInput<T> {
     key: string;
     fn: ActFn<T>;
@@ -6,14 +7,15 @@ export interface ExecutorInput<T> {
      * Policies ordered outermost -> innermost.
      * policies[0] intercepts first; policies[last] is closest to fn.
      *
-     * Canonical order: [cache, dedupe, retry, timeout]
-     *   cache   -> a hit skips everything below it
-     *   dedupe  -> collapses concurrent callers before retry fires
-     *   retry   -> owns the attempt loop
-     *   timeout -> each individual attempt races against the clock
+     * Canonical order: [totalTimeout, cache, dedupe, retry, timeout]
+     *   totalTimeout -> hard wall-clock budget over the entire operation
+     *   cache        -> a hit skips everything below it
+     *   dedupe       -> collapses concurrent callers before retry fires
+     *   retry        -> owns the attempt loop
+     *   timeout      -> each individual attempt races against the clock
      */
     policies: ReadonlyArray<PolicyApplier<T>>;
-    store: StateStore;
+    store: AnyStateStore;
     meta: RunMeta;
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/core/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,EACL,aAAa,EAEb,UAAU,EACV,OAAO,EACR,MAAM,mBAAmB,CAAA;AAE1B,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,GAAG,EAAO,MAAM,CAAA;IAChB,EAAE,EAAQ,KAAK,CAAC,CAAC,CAAC,CAAA;IAClB;;;;;;;;;OASG;IACH,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAA;IACzC,KAAK,EAAK,UAAU,CAAA;IACpB,IAAI,EAAM,OAAO,CAAA;CAClB;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAepE"}
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/core/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,EACL,aAAa,EAEb,aAAa,EACb,OAAO,EACR,MAAM,mBAAmB,CAAA;AAM1B,eAAO,MAAM,mBAAmB,eAAoC,CAAA;AAEpE,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,GAAG,EAAO,MAAM,CAAA;IAChB,EAAE,EAAQ,KAAK,CAAC,CAAC,CAAC,CAAA;IAClB;;;;;;;;;;OAUG;IACH,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAA;IACzC,KAAK,EAAK,aAAa,CAAA;IACvB,IAAI,EAAM,OAAO,CAAA;CAClB;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CA8BpE"}

package/dist/core/executor.js

@@ -1,3 +1,8 @@
+import { isSyncStore } from '../stores/base.js';
+// Symbol stamped onto PolicyApplier functions by dedupePolicy.
+// Lets execute() detect a dedupe policy without importing the policy module
+// (which would create a circular dep) or doing fragile name-sniffing.
+export const REQUIRES_SYNC_STORE = Symbol('actly.requiresSyncStore');
 /**
  * Pure execution engine.
  *
@@ -6,6 +11,16 @@
  * Policy implementations live in /policies and are wired in core/act.ts.
  */
 export async function execute(input) {
+    // Guard: if any policy in the chain requires a sync store, the provided
+    // store must be synchronous. An async store + dedupePolicy is a silent
+    // correctness failure, not just a performance issue — catch it here rather
+    // than letting it produce subtly wrong dedupe behaviour at runtime.
+    const needsSync = input.policies.some(p => p[REQUIRES_SYNC_STORE]);
+    if (needsSync && !isSyncStore(input.store)) {
+        throw new Error('Actly: dedupePolicy requires a SyncStateStore (store._sync === true). ' +
+            'The provided store does not satisfy this constraint. ' +
+            'Either remove dedupe from the policy chain or use InMemoryStore.');
+    }
     const ctx = {
         key: input.key,
         store: input.store,

package/dist/core/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/core/executor.ts"],"names":[],"mappings":"AA0BA;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAI,KAAuB;IACtD,MAAM,GAAG,GAAkB;QACzB,GAAG,EAAI,KAAK,CAAC,GAAG;QAChB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,IAAI,EAAG,KAAK,CAAC,IAAI;KAClB,CAAA;IAED,wCAAwC;IACxC,8EAA8E;IAC9E,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAC,WAAW,CACxC,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,GAAG,CAAC,EAC/C,KAAK,CAAC,EAAE,CACT,CAAA;IAED,OAAO,OAAO,EAAE,CAAA;AAClB,CAAC"}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/core/executor.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/C,+DAA+D;AAC/D,4EAA4E;AAC5E,sEAAsE;AACtE,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,yBAAyB,CAAC,CAAA;AAqBpE;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAI,KAAuB;IACtD,wEAAwE;IACxE,uEAAuE;IACvE,2EAA2E;IAC3E,oEAAoE;IACpE,MAAM,SAAS,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CACnC,CAAC,CAAC,EAAE,CAAE,CAA4D,CAAC,mBAAmB,CAAC,CACxF,CAAA;IACD,IAAI,SAAS,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CACb,wEAAwE;YACxE,uDAAuD;YACvD,kEAAkE,CACnE,CAAA;IACH,CAAC;IAED,MAAM,GAAG,GAAkB;QACzB,GAAG,EAAI,KAAK,CAAC,GAAG;QAChB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,IAAI,EAAG,KAAK,CAAC,IAAI;KAClB,CAAA;IAED,wCAAwC;IACxC,8EAA8E;IAC9E,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAC,WAAW,CACxC,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,GAAG,CAAC,EAC/C,KAAK,CAAC,EAAE,CACT,CAAA;IAED,OAAO,OAAO,EAAE,CAAA;AAClB,CAAC"}

package/dist/index.cjs

@@ -4,8 +4,8 @@ exports.TotalTimeoutError = exports.TimeoutError = exports.InMemoryStore = expor
 var act_js_1 = require("./core/act.js");
 Object.defineProperty(exports, "act", { enumerable: true, get: function () { return act_js_1.act; } });
 // Exported so consumers can build isolated stores (e.g. per-request in SSR)
-var store_js_1 = require("./state/store.js");
-Object.defineProperty(exports, "InMemoryStore", { enumerable: true, get: function () { return store_js_1.InMemoryStore; } });
+var memory_js_1 = require("./stores/memory.js");
+Object.defineProperty(exports, "InMemoryStore", { enumerable: true, get: function () { return memory_js_1.InMemoryStore; } });
 // Exported so callers can instanceof-check against timeout failures
 var timeout_js_1 = require("./policies/timeout.js");
 Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return timeout_js_1.TimeoutError; } });

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { act } from './core/act.js';
-export type { ActFn, ActResult, ActSuccess, ActFailure, ActSource, ActOptions, RetryOptions, TimeoutOptions, DedupeOptions, CacheOptions, StateStore, } from './types/index.js';
-export { InMemoryStore } from './state/store.js';
+export type { ActFn, ActResult, ActSuccess, ActFailure, ActSource, ActOptions, RetryOptions, TimeoutOptions, DedupeOptions, CacheOptions, StateStore, SyncStateStore, AsyncStateStore, } from './types/index.js';
+export { InMemoryStore } from './stores/memory.js';
+export type { InMemoryStoreOptions } from './stores/memory.js';
 export { TimeoutError, TotalTimeoutError } from './policies/timeout.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAA;AAEnC,YAAY,EACV,KAAK,EACL,SAAS,EACT,UAAU,EACV,UAAU,EACV,SAAS,EACT,UAAU,EACV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,YAAY,EACZ,UAAU,GACX,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAGhD,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAA;AAEnC,YAAY,EACV,KAAK,EACL,SAAS,EACT,UAAU,EACV,UAAU,EACV,SAAS,EACT,UAAU,EACV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,YAAY,EAEZ,UAAU,EAEV,cAAc,EACd,eAAe,GAChB,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAG9D,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/index.js

@@ -1,6 +1,6 @@
 export { act } from './core/act.js';
 // Exported so consumers can build isolated stores (e.g. per-request in SSR)
-export { InMemoryStore } from './state/store.js';
+export { InMemoryStore } from './stores/memory.js';
 // Exported so callers can instanceof-check against timeout failures
 export { TimeoutError, TotalTimeoutError } from './policies/timeout.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAA;AAgBnC,4EAA4E;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAEhD,oEAAoE;AACpE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAA;AAoBnC,4EAA4E;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAGlD,oEAAoE;AACpE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/policies/cache.cjs

@@ -1,23 +1,43 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cachePolicy = cachePolicy;
+const base_js_1 = require("../stores/base.js");
 const NS = 'cache:';
 /**
  * Short-circuits the entire downstream chain on a cache hit.
  * On a miss, runs fn and stores the result with TTL.
  *
  * Must be the OUTERMOST policy so a hit skips dedupe, timeout, and retry.
+ *
+ * Supports both SyncStateStore and AsyncStateStore. The async branch
+ * introduces two await points (get + set) but has no correctness
+ * requirement for same-tick execution — worst case is a cache stampede
+ * on a simultaneous miss, which is standard behaviour without locking.
  */
 function cachePolicy(opts) {
     return (fn, ctx) => async () => {
         const key = NS + ctx.key;
-        const hit = ctx.store.get(key);
-        if (hit) {
-            ctx.meta.source = 'cache';
-            return hit.value;
+        if ((0, base_js_1.isSyncStore)(ctx.store)) {
+            // Fast path — synchronous store, no await needed
+            const hit = ctx.store.get(key);
+            if (hit) {
+                ctx.meta.source = 'cache';
+                return hit.value;
+            }
+            const value = await fn();
+            ctx.store.set(key, { value }, opts.ttl);
+            return value;
+        }
+        else {
+            // Async store path
+            const hit = await ctx.store.get(key);
+            if (hit) {
+                ctx.meta.source = 'cache';
+                return hit.value;
+            }
+            const value = await fn();
+            await ctx.store.set(key, { value }, opts.ttl);
+            return value;
         }
-        const value = await fn();
-        ctx.store.set(key, { value }, opts.ttl);
-        return value;
     };
 }

package/dist/policies/cache.d.ts

@@ -4,6 +4,11 @@ import type { CacheOptions, PolicyApplier } from '../types/index.js';
  * On a miss, runs fn and stores the result with TTL.
  *
  * Must be the OUTERMOST policy so a hit skips dedupe, timeout, and retry.
+ *
+ * Supports both SyncStateStore and AsyncStateStore. The async branch
+ * introduces two await points (get + set) but has no correctness
+ * requirement for same-tick execution — worst case is a cache stampede
+ * on a simultaneous miss, which is standard behaviour without locking.
  */
 export declare function cachePolicy<T>(opts: CacheOptions): PolicyApplier<T>;
 //# sourceMappingURL=cache.d.ts.map

package/dist/policies/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/policies/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,YAAY,EAAE,aAAa,EAAiB,MAAM,mBAAmB,CAAA;AAS1F;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,CAAC,CAAC,CAenE"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/policies/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,YAAY,EAAE,aAAa,EAAiB,MAAM,mBAAmB,CAAA;AAU1F;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,CAAC,CAAC,CA6BnE"}