actly 1.1.0 → 1.1.5

package/dist/core/executor.cjs

@@ -3,22 +3,31 @@ 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.
+/**
+ * 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.
  *
- * This file imports nothing from /policies.
- * It operates on PolicyApplier<T> — a type alias defined in /types.
- * Policy implementations live in /policies and are wired in core/act.ts.
+ * This file imports nothing from `/policies`. It operates on `PolicyApplier<T>`
+ * — a type alias defined in `/types`. Policy implementations live in
+ * `/policies` and are wired in `core/act.ts`.
+ *
+ * # Public API
+ *
+ * Exported so consumers can build custom policy chains with explicit stores
+ * (e.g. for SSR request isolation or multi-tenant scenarios where the
+ * module-level default store is wrong).
  */
 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.
+    // correctness failure — 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). ' +
@@ -33,5 +42,6 @@ async function execute(input) {
     // Build the call chain from inside out.
     // reduceRight ensures policies[0] becomes the outermost wrapper (runs first).
     const wrapped = input.policies.reduceRight((inner, applyPolicy) => applyPolicy(inner, ctx), input.fn);
-    return wrapped();
+    // Call the outermost wrapper with the root signal.
+    return wrapped(input.signal);
 }

package/dist/core/executor.d.ts

@@ -1,13 +1,19 @@
 import type { ActFn, PolicyApplier, AnyStateStore, RunMeta } from '../types/index.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 declare const REQUIRES_SYNC_STORE: unique symbol;
 export interface ExecutorInput<T> {
     key: string;
     fn: ActFn<T>;
     /**
      * Policies ordered outermost -> innermost.
-     * policies[0] intercepts first; policies[last] is closest to fn.
+     * `policies[0]` intercepts first; `policies[last]` is closest to `fn`.
      *
-     * Canonical order: [totalTimeout, cache, dedupe, retry, timeout]
+     * 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
@@ -17,13 +23,27 @@ export interface ExecutorInput<T> {
     policies: ReadonlyArray<PolicyApplier<T>>;
     store: AnyStateStore;
     meta: RunMeta;
+    /**
+     * Root AbortSignal for the operation. Propagated inward through the
+     * policy chain: each policy receives it as the `signal` argument to
+     * its wrapped `ActFn`. The outermost policy may layer its own signal
+     * (e.g. `totalTimeoutPolicy` arms a timer) and pass the composite
+     * inward.
+     */
+    signal: AbortSignal;
 }
 /**
  * Pure execution engine.
  *
- * This file imports nothing from /policies.
- * It operates on PolicyApplier<T> — a type alias defined in /types.
- * Policy implementations live in /policies and are wired in core/act.ts.
+ * This file imports nothing from `/policies`. It operates on `PolicyApplier<T>`
+ * — a type alias defined in `/types`. Policy implementations live in
+ * `/policies` and are wired in `core/act.ts`.
+ *
+ * # Public API
+ *
+ * Exported so consumers can build custom policy chains with explicit stores
+ * (e.g. for SSR request isolation or multi-tenant scenarios where the
+ * module-level default store is wrong).
  */
 export declare function execute<T>(input: ExecutorInput<T>): Promise<T>;
 //# sourceMappingURL=executor.d.ts.map

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,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"}
+{"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;AAG1B;;;;;GAKG;AACH,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;IACjB;;;;;;OAMG;IACH,MAAM,EAAI,WAAW,CAAA;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CA+BpE"}

package/dist/core/executor.js

@@ -1,20 +1,29 @@
 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.
+/**
+ * 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.
  *
- * This file imports nothing from /policies.
- * It operates on PolicyApplier<T> — a type alias defined in /types.
- * Policy implementations live in /policies and are wired in core/act.ts.
+ * This file imports nothing from `/policies`. It operates on `PolicyApplier<T>`
+ * — a type alias defined in `/types`. Policy implementations live in
+ * `/policies` and are wired in `core/act.ts`.
+ *
+ * # Public API
+ *
+ * Exported so consumers can build custom policy chains with explicit stores
+ * (e.g. for SSR request isolation or multi-tenant scenarios where the
+ * module-level default store is wrong).
  */
 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.
+    // correctness failure — 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). ' +
@@ -29,6 +38,7 @@ export async function execute(input) {
     // Build the call chain from inside out.
     // reduceRight ensures policies[0] becomes the outermost wrapper (runs first).
     const wrapped = input.policies.reduceRight((inner, applyPolicy) => applyPolicy(inner, ctx), input.fn);
-    return wrapped();
+    // Call the outermost wrapper with the root signal.
+    return wrapped(input.signal);
 }
 //# sourceMappingURL=executor.js.map

package/dist/core/executor.js.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/core/executor.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,yBAAyB,CAAC,CAAA;AA6BpE;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAI,KAAuB;IACtD,wEAAwE;IACxE,uEAAuE;IACvE,qEAAqE;IACrE,4CAA4C;IAC5C,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,mDAAmD;IACnD,OAAO,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;AAC9B,CAAC"}

package/dist/index.cjs

@@ -1,12 +1,22 @@
 "use strict";
+// ─── Primary API ──────────────────────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TotalTimeoutError = exports.TimeoutError = exports.InMemoryStore = exports.act = void 0;
+exports.TotalTimeoutError = exports.TimeoutError = exports.isAsyncStore = exports.isSyncStore = exports.InMemoryStore = exports.REQUIRES_SYNC_STORE = exports.execute = exports.withStore = exports.invalidate = exports.act = void 0;
 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)
+Object.defineProperty(exports, "invalidate", { enumerable: true, get: function () { return act_js_1.invalidate; } });
+Object.defineProperty(exports, "withStore", { enumerable: true, get: function () { return act_js_1.withStore; } });
+// ─── Execution engine (for custom policy chains) ──────────────────────────────
+var executor_js_1 = require("./core/executor.js");
+Object.defineProperty(exports, "execute", { enumerable: true, get: function () { return executor_js_1.execute; } });
+Object.defineProperty(exports, "REQUIRES_SYNC_STORE", { enumerable: true, get: function () { return executor_js_1.REQUIRES_SYNC_STORE; } });
+// ─── Stores ───────────────────────────────────────────────────────────────────
 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 base_js_1 = require("./stores/base.js");
+Object.defineProperty(exports, "isSyncStore", { enumerable: true, get: function () { return base_js_1.isSyncStore; } });
+Object.defineProperty(exports, "isAsyncStore", { enumerable: true, get: function () { return base_js_1.isAsyncStore; } });
+// ─── Error classes ────────────────────────────────────────────────────────────
 var timeout_js_1 = require("./policies/timeout.js");
 Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return timeout_js_1.TimeoutError; } });
 Object.defineProperty(exports, "TotalTimeoutError", { enumerable: true, get: function () { return timeout_js_1.TotalTimeoutError; } });

package/dist/index.d.ts

@@ -1,6 +1,10 @@
-export { act } from './core/act.js';
-export type { ActFn, ActResult, ActSuccess, ActFailure, ActSource, ActOptions, RetryOptions, TimeoutOptions, DedupeOptions, CacheOptions, StateStore, SyncStateStore, AsyncStateStore, } from './types/index.js';
+export { act, invalidate, withStore, } from './core/act.js';
+export type { ScopedActSync, ScopedActAsync, } from './core/act.js';
+export { execute, REQUIRES_SYNC_STORE, } from './core/executor.js';
 export { InMemoryStore } from './stores/memory.js';
 export type { InMemoryStoreOptions } from './stores/memory.js';
-export { TimeoutError, TotalTimeoutError } from './policies/timeout.js';
+export { isSyncStore, isAsyncStore, } from './stores/base.js';
+export { TimeoutError, TotalTimeoutError, } from './policies/timeout.js';
+export type { ActFn, ActResult, ActSuccess, ActFailure, ActSource, ActOptions, RetryOptions, TimeoutOptions, DedupeOptions, CacheOptions, PolicyApplier, PolicyContext, RunMeta, StateStore, // v1.0 alias for SyncStateStore (zero breakage)
+SyncStateStore, AsyncStateStore, AnyStateStore, } from './types/index.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,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,GAAG,EACH,UAAU,EACV,SAAS,GACV,MAAM,eAAe,CAAA;AAEtB,YAAY,EACV,aAAa,EACb,cAAc,GACf,MAAM,eAAe,CAAA;AAItB,OAAO,EACL,OAAO,EACP,mBAAmB,GACpB,MAAM,oBAAoB,CAAA;AAI3B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAE9D,OAAO,EACL,WAAW,EACX,YAAY,GACb,MAAM,kBAAkB,CAAA;AAIzB,OAAO,EACL,YAAY,EACZ,iBAAiB,GAClB,MAAM,uBAAuB,CAAA;AAI9B,YAAY,EAEV,KAAK,EACL,SAAS,EACT,UAAU,EACV,UAAU,EACV,SAAS,EACT,UAAU,EAGV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,YAAY,EAGZ,aAAa,EACb,aAAa,EACb,OAAO,EAGP,UAAU,EAAS,gDAAgD;AACnE,cAAc,EACd,eAAe,EACf,aAAa,GACd,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -1,6 +1,10 @@
-export { act } from './core/act.js';
-// Exported so consumers can build isolated stores (e.g. per-request in SSR)
+// ─── Primary API ──────────────────────────────────────────────────────────────
+export { act, invalidate, withStore, } from './core/act.js';
+// ─── Execution engine (for custom policy chains) ──────────────────────────────
+export { execute, REQUIRES_SYNC_STORE, } from './core/executor.js';
+// ─── Stores ───────────────────────────────────────────────────────────────────
 export { InMemoryStore } from './stores/memory.js';
-// Exported so callers can instanceof-check against timeout failures
-export { TimeoutError, TotalTimeoutError } from './policies/timeout.js';
+export { isSyncStore, isAsyncStore, } from './stores/base.js';
+// ─── Error classes ────────────────────────────────────────────────────────────
+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;AAoBnC,4EAA4E;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAGlD,oEAAoE;AACpE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAEjF,OAAO,EACL,GAAG,EACH,UAAU,EACV,SAAS,GACV,MAAM,eAAe,CAAA;AAOtB,iFAAiF;AAEjF,OAAO,EACL,OAAO,EACP,mBAAmB,GACpB,MAAM,oBAAoB,CAAA;AAE3B,iFAAiF;AAEjF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAGlD,OAAO,EACL,WAAW,EACX,YAAY,GACb,MAAM,kBAAkB,CAAA;AAEzB,iFAAiF;AAEjF,OAAO,EACL,YAAY,EACZ,iBAAiB,GAClB,MAAM,uBAAuB,CAAA"}

package/dist/policies/cache.cjs

@@ -3,41 +3,105 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.cachePolicy = cachePolicy;
 const base_js_1 = require("../stores/base.js");
 const NS = 'cache:';
+const INFLIGHT_NS = '__inflight:cache:';
 /**
- * Short-circuits the entire downstream chain on a cache hit.
- * On a miss, runs fn and stores the result with TTL.
+ * Short-circuit the entire downstream chain on a cache hit.
+ * On a miss, run `fn` and store the result with TTL.
  *
- * Must be the OUTERMOST policy so a hit skips dedupe, timeout, and retry.
+ * # Single-flight (fixes cache stampede)
  *
- * 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.
+ * On a sync store, the policy also stores the in-flight Promise under a
+ * separate `__inflight:cache:<key>` slot. Concurrent callers that miss the
+ * cache but find an in-flight Promise join it instead of launching duplicate
+ * work. This is the same mechanism `dedupePolicy` uses, applied internally
+ * to cache misses so users don't need to combine `cache` + `dedupe` to
+ * avoid stampedes.
+ *
+ * On an async store, single-flight is not possible (the same sync-store
+ * constraint as dedupe applies). Stampedes are a known limitation — document
+ * and pair with dedupe at a higher layer if you need single-flight semantics.
+ *
+ * # Fail-open writes
+ *
+ * If `store.set()` throws (e.g. Redis transient error), we swallow the error
+ * and return the value anyway. The caller gets their result; the next call
+ * will simply re-run `fn` and try to cache again. Caching is an optimisation,
+ * not a correctness requirement.
+ *
+ * # Cache hit semantics
+ *
+ * On a cache hit, `meta.source` is set to `'cache'` and `meta.attempts` is
+ * set to `0` — no work was performed. (v1.1.0 reported `attempts: 1` on
+ * cache hits, which was inconsistent with the documented meaning of
+ * `attempts`. v1.1.5 fixes this.)
+ *
+ * Failures are NEVER cached. Only successful values are stored.
  */
 function cachePolicy(opts) {
-    return (fn, ctx) => async () => {
+    return (fn, ctx) => async (signal) => {
         const key = NS + ctx.key;
+        const inflightKey = INFLIGHT_NS + ctx.key;
+        // ─── Sync store: fast path with single-flight ────────────────────────
         if ((0, base_js_1.isSyncStore)(ctx.store)) {
-            // Fast path — synchronous store, no await needed
+            // 1. Cache hit?
             const hit = ctx.store.get(key);
             if (hit) {
                 ctx.meta.source = 'cache';
+                ctx.meta.attempts = 0;
                 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;
+            // 2. In-flight single-flight hit? Join it.
+            const inflight = ctx.store.get(inflightKey);
+            if (inflight)
+                return inflight;
+            // 3. Originator: launch fn, cache on success (fail-open).
+            const promise = Promise.resolve(fn(signal)).then((value) => {
+                try {
+                    ctx.store.set(key, { value }, opts.ttl);
+                }
+                catch {
+                    // Fail-open: cache write failure should not surface to caller.
+                    // The value is still valid; next call will just re-run fn.
+                }
+                return value;
+            }, (err) => { throw err; });
+            // Try to publish the in-flight promise so concurrent callers can
+            // join (single-flight). If store.set throws, single-flight is
+            // disabled for this call — concurrent callers will all run fn.
+            // That's still correct, just less efficient.
+            try {
+                ctx.store.set(inflightKey, promise);
+                // Cleanup the in-flight slot on settle. The `.catch(() => {})`
+                // suppresses the unhandled-rejection warning that would otherwise
+                // fire on the `.finally()` chain — the original `promise` (with
+                // its rejection) is returned to the caller, which has its own
+                // try/catch via act().
+                promise.finally(() => {
+                    try {
+                        ctx.store.delete(inflightKey);
+                    }
+                    catch { /* ignore */ }
+                }).catch(() => { });
+            }
+            catch {
+                // Single-flight unavailable; proceed without publishing.
             }
-            const value = await fn();
+            return promise;
+        }
+        // ─── Async store: no single-flight (race window unavoidable) ─────────
+        const hit = await ctx.store.get(key);
+        if (hit) {
+            ctx.meta.source = 'cache';
+            ctx.meta.attempts = 0;
+            return hit.value;
+        }
+        const value = await fn(signal);
+        try {
             await ctx.store.set(key, { value }, opts.ttl);
-            return value;
         }
+        catch {
+            // Fail-open: see sync path comment.
+        }
+        return value;
     };
 }

package/dist/policies/cache.d.ts

@@ -1,14 +1,36 @@
 import type { CacheOptions, PolicyApplier } from '../types/index.js';
 /**
- * Short-circuits the entire downstream chain on a cache hit.
- * On a miss, runs fn and stores the result with TTL.
+ * Short-circuit the entire downstream chain on a cache hit.
+ * On a miss, run `fn` and store the result with TTL.
  *
- * Must be the OUTERMOST policy so a hit skips dedupe, timeout, and retry.
+ * # Single-flight (fixes cache stampede)
  *
- * 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.
+ * On a sync store, the policy also stores the in-flight Promise under a
+ * separate `__inflight:cache:<key>` slot. Concurrent callers that miss the
+ * cache but find an in-flight Promise join it instead of launching duplicate
+ * work. This is the same mechanism `dedupePolicy` uses, applied internally
+ * to cache misses so users don't need to combine `cache` + `dedupe` to
+ * avoid stampedes.
+ *
+ * On an async store, single-flight is not possible (the same sync-store
+ * constraint as dedupe applies). Stampedes are a known limitation — document
+ * and pair with dedupe at a higher layer if you need single-flight semantics.
+ *
+ * # Fail-open writes
+ *
+ * If `store.set()` throws (e.g. Redis transient error), we swallow the error
+ * and return the value anyway. The caller gets their result; the next call
+ * will simply re-run `fn` and try to cache again. Caching is an optimisation,
+ * not a correctness requirement.
+ *
+ * # Cache hit semantics
+ *
+ * On a cache hit, `meta.source` is set to `'cache'` and `meta.attempts` is
+ * set to `0` — no work was performed. (v1.1.0 reported `attempts: 1` on
+ * cache hits, which was inconsistent with the documented meaning of
+ * `attempts`. v1.1.5 fixes this.)
+ *
+ * Failures are NEVER cached. Only successful values are stored.
  */
 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;AAU1F;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,CAAC,CAAC,CA6BnE"}
+{"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;AAY1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,CAAC,CAAC,CAuEnE"}

package/dist/policies/cache.js

@@ -1,41 +1,105 @@
 import { isSyncStore } from '../stores/base.js';
 const NS = 'cache:';
+const INFLIGHT_NS = '__inflight:cache:';
 /**
- * Short-circuits the entire downstream chain on a cache hit.
- * On a miss, runs fn and stores the result with TTL.
+ * Short-circuit the entire downstream chain on a cache hit.
+ * On a miss, run `fn` and store the result with TTL.
  *
- * Must be the OUTERMOST policy so a hit skips dedupe, timeout, and retry.
+ * # Single-flight (fixes cache stampede)
  *
- * 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.
+ * On a sync store, the policy also stores the in-flight Promise under a
+ * separate `__inflight:cache:<key>` slot. Concurrent callers that miss the
+ * cache but find an in-flight Promise join it instead of launching duplicate
+ * work. This is the same mechanism `dedupePolicy` uses, applied internally
+ * to cache misses so users don't need to combine `cache` + `dedupe` to
+ * avoid stampedes.
+ *
+ * On an async store, single-flight is not possible (the same sync-store
+ * constraint as dedupe applies). Stampedes are a known limitation — document
+ * and pair with dedupe at a higher layer if you need single-flight semantics.
+ *
+ * # Fail-open writes
+ *
+ * If `store.set()` throws (e.g. Redis transient error), we swallow the error
+ * and return the value anyway. The caller gets their result; the next call
+ * will simply re-run `fn` and try to cache again. Caching is an optimisation,
+ * not a correctness requirement.
+ *
+ * # Cache hit semantics
+ *
+ * On a cache hit, `meta.source` is set to `'cache'` and `meta.attempts` is
+ * set to `0` — no work was performed. (v1.1.0 reported `attempts: 1` on
+ * cache hits, which was inconsistent with the documented meaning of
+ * `attempts`. v1.1.5 fixes this.)
+ *
+ * Failures are NEVER cached. Only successful values are stored.
  */
 export function cachePolicy(opts) {
-    return (fn, ctx) => async () => {
+    return (fn, ctx) => async (signal) => {
         const key = NS + ctx.key;
+        const inflightKey = INFLIGHT_NS + ctx.key;
+        // ─── Sync store: fast path with single-flight ────────────────────────
         if (isSyncStore(ctx.store)) {
-            // Fast path — synchronous store, no await needed
+            // 1. Cache hit?
             const hit = ctx.store.get(key);
             if (hit) {
                 ctx.meta.source = 'cache';
+                ctx.meta.attempts = 0;
                 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;
+            // 2. In-flight single-flight hit? Join it.
+            const inflight = ctx.store.get(inflightKey);
+            if (inflight)
+                return inflight;
+            // 3. Originator: launch fn, cache on success (fail-open).
+            const promise = Promise.resolve(fn(signal)).then((value) => {
+                try {
+                    ctx.store.set(key, { value }, opts.ttl);
+                }
+                catch {
+                    // Fail-open: cache write failure should not surface to caller.
+                    // The value is still valid; next call will just re-run fn.
+                }
+                return value;
+            }, (err) => { throw err; });
+            // Try to publish the in-flight promise so concurrent callers can
+            // join (single-flight). If store.set throws, single-flight is
+            // disabled for this call — concurrent callers will all run fn.
+            // That's still correct, just less efficient.
+            try {
+                ctx.store.set(inflightKey, promise);
+                // Cleanup the in-flight slot on settle. The `.catch(() => {})`
+                // suppresses the unhandled-rejection warning that would otherwise
+                // fire on the `.finally()` chain — the original `promise` (with
+                // its rejection) is returned to the caller, which has its own
+                // try/catch via act().
+                promise.finally(() => {
+                    try {
+                        ctx.store.delete(inflightKey);
+                    }
+                    catch { /* ignore */ }
+                }).catch(() => { });
+            }
+            catch {
+                // Single-flight unavailable; proceed without publishing.
             }
-            const value = await fn();
+            return promise;
+        }
+        // ─── Async store: no single-flight (race window unavoidable) ─────────
+        const hit = await ctx.store.get(key);
+        if (hit) {
+            ctx.meta.source = 'cache';
+            ctx.meta.attempts = 0;
+            return hit.value;
+        }
+        const value = await fn(signal);
+        try {
             await ctx.store.set(key, { value }, opts.ttl);
-            return value;
         }
+        catch {
+            // Fail-open: see sync path comment.
+        }
+        return value;
     };
 }
 //# sourceMappingURL=cache.js.map

package/dist/policies/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/policies/cache.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/C,MAAM,EAAE,GAAG,QAAQ,CAAA;AAOnB;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAI,IAAkB;IAC/C,OAAO,CAAC,EAAY,EAAE,GAAkB,EAAY,EAAE,CACpD,KAAK,IAAI,EAAE;QACT,MAAM,GAAG,GAAG,EAAE,GAAG,GAAG,CAAC,GAAG,CAAA;QAExB,IAAI,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,iDAAiD;YACjD,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAgB,GAAG,CAAC,CAAA;YAC7C,IAAI,GAAG,EAAE,CAAC;gBACR,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAA;gBACzB,OAAO,GAAG,CAAC,KAAK,CAAA;YAClB,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,EAAE,EAAE,CAAA;YACxB,GAAG,CAAC,KAAK,CAAC,GAAG,CAAgB,GAAG,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;YACtD,OAAO,KAAK,CAAA;QACd,CAAC;aAAM,CAAC;YACN,mBAAmB;YACnB,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,CAAgB,GAAG,CAAC,CAAA;YACnD,IAAI,GAAG,EAAE,CAAC;gBACR,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAA;gBACzB,OAAO,GAAG,CAAC,KAAK,CAAA;YAClB,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,EAAE,EAAE,CAAA;YACxB,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,CAAgB,GAAG,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;YAC5D,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC,CAAA;AACL,CAAC"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/policies/cache.ts"],"names":[],"mappings":"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"}