actly 1.1.5 → 1.2.0

package/dist/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"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"}

package/dist/observability.js

@@ -0,0 +1,43 @@
+/**
+ * Observability hooks.
+ *
+ * Eight event types covering the entire lifecycle of an `act()` call.
+ *
+ * # Contract
+ *
+ * When `options.observability` is `null`/`undefined` (the common case),
+ * no event objects are allocated and no function calls are made. The
+ * hot path is a single null-check per policy decision.
+ *
+ * When hooks ARE registered, events are allocated lazily — only when the
+ * corresponding event actually fires. A cache hit doesn't allocate an
+ * `onRetry` event, for example.
+ *
+ * # Event shape
+ *
+ * Every event carries `key`, `traceId`, and `timestamp` for correlation.
+ * Event-specific fields are on the same object (no nesting) for flat
+ * destructuring in user code.
+ *
+ * # Ordering
+ *
+ * For a successful fresh call with retries:
+ *   onAttempt (1) → onAttempt (2) → onRetry (1→2) → onAttempt (3) → onFinalSuccess
+ *
+ * For a cache hit:
+ *   onCacheHit → onFinalSuccess
+ *
+ * For a dedupe joiner:
+ *   onDedupeJoin → onFinalSuccess (or onFinalFailure)
+ *
+ * For a timeout:
+ *   onAttempt → onTimeout → onFinalFailure
+ */
+/**
+ * Quick null-check helper. Policies call this once at decision points; if
+ * it returns false, no further observability work is done.
+ */
+export function hasObservers(ctx) {
+    return ctx.observability != null;
+}
+//# sourceMappingURL=observability.js.map

package/dist/observability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.js","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AA0IH;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,GAA6C;IACxE,OAAO,GAAG,CAAC,aAAa,IAAI,IAAI,CAAA;AAClC,CAAC"}

package/dist/policies/bulkhead.cjs

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bulkheadPolicy = bulkheadPolicy;
+const executor_js_1 = require("../core/executor.js");
+const errors_js_1 = require("../errors.js");
+const NS = 'bulk:';
+function getState(store, key) {
+    return store.get(NS + key) ?? { active: 0, queue: [] };
+}
+function setState(store, key, state) {
+    store.set(NS + key, state);
+}
+function bulkheadPolicy(opts) {
+    const maxConcurrent = Math.max(1, Math.floor(opts.maxConcurrent));
+    const queueTimeoutMs = opts.queueTimeoutMs ?? 0;
+    const applier = (fn, ctx) => {
+        const syncCtx = ctx;
+        return async (signal) => {
+            const key = syncCtx.key;
+            const acquireSlot = () => {
+                // If signal already aborted, reject immediately
+                if (signal.aborted)
+                    return Promise.reject(signal.reason);
+                const state = getState(syncCtx.store, key);
+                if (state.active < maxConcurrent) {
+                    state.active++;
+                    setState(syncCtx.store, key, state);
+                    return Promise.resolve();
+                }
+                if (queueTimeoutMs === 0) {
+                    throw new errors_js_1.BulkheadOverflowError(key, maxConcurrent);
+                }
+                return new Promise((resolve, reject) => {
+                    const state2 = getState(syncCtx.store, key);
+                    const entry = {
+                        resolve,
+                        reject,
+                        signal,
+                    };
+                    // Remove entry from queue on signal abort
+                    entry.onAbort = () => {
+                        const s = getState(syncCtx.store, key);
+                        const idx = s.queue.indexOf(entry);
+                        if (idx >= 0) {
+                            s.queue.splice(idx, 1);
+                            setState(syncCtx.store, key, s);
+                        }
+                        if (entry.timer)
+                            clearTimeout(entry.timer);
+                        reject(signal.reason);
+                    };
+                    if (queueTimeoutMs > 0) {
+                        entry.timer = setTimeout(() => {
+                            const s = getState(syncCtx.store, key);
+                            const idx = s.queue.indexOf(entry);
+                            if (idx >= 0)
+                                s.queue.splice(idx, 1);
+                            setState(syncCtx.store, key, s);
+                            signal.removeEventListener('abort', entry.onAbort);
+                            reject(new errors_js_1.BulkheadOverflowError(key, maxConcurrent));
+                        }, queueTimeoutMs);
+                    }
+                    signal.addEventListener('abort', entry.onAbort, { once: true });
+                    state2.queue.push(entry);
+                    setState(syncCtx.store, key, state2);
+                });
+            };
+            const releaseSlot = () => {
+                const state = getState(syncCtx.store, key);
+                state.active--;
+                if (state.queue.length > 0) {
+                    const next = state.queue.shift();
+                    state.active++;
+                    if (next.timer)
+                        clearTimeout(next.timer);
+                    // Remove abort listener from the QUEUED caller's signal (not releaser's)
+                    if (next.onAbort && next.signal) {
+                        next.signal.removeEventListener('abort', next.onAbort);
+                    }
+                    next.resolve();
+                }
+                if (state.active < 0)
+                    state.active = 0;
+                setState(syncCtx.store, key, state);
+            };
+            await acquireSlot();
+            try {
+                return await fn(signal);
+            }
+            finally {
+                releaseSlot();
+            }
+        };
+    };
+    applier[executor_js_1.REQUIRES_SYNC_STORE] = true;
+    return applier;
+}

package/dist/policies/bulkhead.d.ts

@@ -0,0 +1,3 @@
+import type { PolicyApplier, BulkheadOptions } from '../types/index.js';
+export declare function bulkheadPolicy<T>(opts: BulkheadOptions): PolicyApplier<T>;
+//# sourceMappingURL=bulkhead.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bulkhead.d.ts","sourceRoot":"","sources":["../../src/policies/bulkhead.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,eAAe,EAAE,MAAM,mBAAmB,CAAA;AA0B7F,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,eAAe,GAAG,aAAa,CAAC,CAAC,CAAC,CA0FzE"}

package/dist/policies/bulkhead.js

@@ -0,0 +1,95 @@
+import { REQUIRES_SYNC_STORE } from '../core/executor.js';
+import { BulkheadOverflowError } from '../errors.js';
+const NS = 'bulk:';
+function getState(store, key) {
+    return store.get(NS + key) ?? { active: 0, queue: [] };
+}
+function setState(store, key, state) {
+    store.set(NS + key, state);
+}
+export function bulkheadPolicy(opts) {
+    const maxConcurrent = Math.max(1, Math.floor(opts.maxConcurrent));
+    const queueTimeoutMs = opts.queueTimeoutMs ?? 0;
+    const applier = (fn, ctx) => {
+        const syncCtx = ctx;
+        return async (signal) => {
+            const key = syncCtx.key;
+            const acquireSlot = () => {
+                // If signal already aborted, reject immediately
+                if (signal.aborted)
+                    return Promise.reject(signal.reason);
+                const state = getState(syncCtx.store, key);
+                if (state.active < maxConcurrent) {
+                    state.active++;
+                    setState(syncCtx.store, key, state);
+                    return Promise.resolve();
+                }
+                if (queueTimeoutMs === 0) {
+                    throw new BulkheadOverflowError(key, maxConcurrent);
+                }
+                return new Promise((resolve, reject) => {
+                    const state2 = getState(syncCtx.store, key);
+                    const entry = {
+                        resolve,
+                        reject,
+                        signal,
+                    };
+                    // Remove entry from queue on signal abort
+                    entry.onAbort = () => {
+                        const s = getState(syncCtx.store, key);
+                        const idx = s.queue.indexOf(entry);
+                        if (idx >= 0) {
+                            s.queue.splice(idx, 1);
+                            setState(syncCtx.store, key, s);
+                        }
+                        if (entry.timer)
+                            clearTimeout(entry.timer);
+                        reject(signal.reason);
+                    };
+                    if (queueTimeoutMs > 0) {
+                        entry.timer = setTimeout(() => {
+                            const s = getState(syncCtx.store, key);
+                            const idx = s.queue.indexOf(entry);
+                            if (idx >= 0)
+                                s.queue.splice(idx, 1);
+                            setState(syncCtx.store, key, s);
+                            signal.removeEventListener('abort', entry.onAbort);
+                            reject(new BulkheadOverflowError(key, maxConcurrent));
+                        }, queueTimeoutMs);
+                    }
+                    signal.addEventListener('abort', entry.onAbort, { once: true });
+                    state2.queue.push(entry);
+                    setState(syncCtx.store, key, state2);
+                });
+            };
+            const releaseSlot = () => {
+                const state = getState(syncCtx.store, key);
+                state.active--;
+                if (state.queue.length > 0) {
+                    const next = state.queue.shift();
+                    state.active++;
+                    if (next.timer)
+                        clearTimeout(next.timer);
+                    // Remove abort listener from the QUEUED caller's signal (not releaser's)
+                    if (next.onAbort && next.signal) {
+                        next.signal.removeEventListener('abort', next.onAbort);
+                    }
+                    next.resolve();
+                }
+                if (state.active < 0)
+                    state.active = 0;
+                setState(syncCtx.store, key, state);
+            };
+            await acquireSlot();
+            try {
+                return await fn(signal);
+            }
+            finally {
+                releaseSlot();
+            }
+        };
+    };
+    applier[REQUIRES_SYNC_STORE] = true;
+    return applier;
+}
+//# sourceMappingURL=bulkhead.js.map

package/dist/policies/bulkhead.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulkhead.js","sourceRoot":"","sources":["../../src/policies/bulkhead.ts"],"names":[],"mappings":"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"}

package/dist/policies/cache.cjs

@@ -4,11 +4,31 @@ exports.cachePolicy = cachePolicy;
 const base_js_1 = require("../stores/base.js");
 const NS = 'cache:';
 const INFLIGHT_NS = '__inflight:cache:';
+let generationCounter = 0;
+function nextGeneration() {
+    generationCounter = (generationCounter + 1) % Number.MAX_SAFE_INTEGER;
+    return generationCounter;
+}
 /**
  * Short-circuit the entire downstream chain on a cache hit.
  * On a miss, run `fn` and store the result with TTL.
  *
- * # Single-flight (fixes cache stampede)
+ * # Properties
+ *
+ *  - **Single-flight originator isolation**: the stored in-flight promise is
+ *    the RAW `fn(signal)` — NOT raceAbort-wrapped. An originator's signal
+ *    abort no longer causes all cache-miss joiners to reject. Each caller
+ *    races against their OWN signal only.
+ *  - **Generation-safe inflight cleanup**: stale originators don't delete
+ *    newer entries (same pattern as dedupePolicy).
+ *  - **Signal-aware async store path**: between `await store.get()` and
+ *    `await store.set()`, we re-check `signal.aborted`. The previous
+ *    version would happily return a cached value even after the caller
+ *    aborted mid-Redis-latency.
+ *  - **Cache hit honours abort**: if `signal.aborted` is true at policy
+ *    entry, we reject immediately — consistent with `act()`'s contract.
+ *
+ * # Single-flight (cache stampede prevention)
  *
  * On a sync store, the policy also stores the in-flight Promise under a
  * separate `__inflight:cache:<key>` slot. Concurrent callers that miss the
@@ -31,73 +51,148 @@ const INFLIGHT_NS = '__inflight:cache:';
  * # 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.)
+ * set to `0` — no work was performed.
  *
  * Failures are NEVER cached. Only successful values are stored.
  */
 function cachePolicy(opts) {
     return (fn, ctx) => async (signal) => {
+        // Honour abort on cache hit too. Consistent with act()'s
+        // "reject immediately if signal aborted" contract.
+        if (signal.aborted)
+            return Promise.reject(signal.reason);
         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)) {
+            // Capture the narrowed sync store so closures (cleanup) keep the
+            // type information — TS doesn't carry `isSyncStore` narrowing
+            // into nested function bodies.
+            const store = ctx.store;
+            const obs = ctx.observability;
             // 1. Cache hit?
-            const hit = ctx.store.get(key);
+            const hit = store.get(key);
             if (hit) {
                 ctx.meta.source = 'cache';
                 ctx.meta.attempts = 0;
+                // Emit cache-hit event if hooks are registered.
+                // Compute actual age from the entry's insertion timestamp.
+                if (obs) {
+                    const ageMs = Date.now() - hit.insertedAt;
+                    obs.hooks.onCacheHit?.({
+                        type: 'cache-hit', key: ctx.key, traceId: obs.traceId,
+                        timestamp: Date.now(), ageMs: Math.max(0, ageMs),
+                    });
+                }
                 return hit.value;
             }
+            // Emit cache-miss event if hooks are registered.
+            if (obs) {
+                obs.hooks.onCacheMiss?.({
+                    type: 'cache-miss', key: ctx.key, traceId: obs.traceId,
+                    timestamp: Date.now(),
+                });
+            }
             // 2. In-flight single-flight hit? Join it.
-            const inflight = ctx.store.get(inflightKey);
-            if (inflight)
-                return inflight;
+            //
+            // The stored promise is RAW fn(signal). Joiners race it
+            // against their OWN signal only — originator abort doesn't
+            // propagate to joiners.
+            const inflight = store.get(inflightKey);
+            if (inflight) {
+                // Race the in-flight promise against OUR OWN signal. If we
+                // abort, we reject — but other joiners and the originator
+                // continue unaffected.
+                try {
+                    const value = await raceWithOwnSignal(inflight.promise, signal);
+                    // Mirror originator's meta so joiner's ActResult reflects
+                    // the real effort (attempts, source).
+                    ctx.meta.attempts = inflight.meta.attempts;
+                    ctx.meta.source = inflight.meta.source;
+                    return value;
+                }
+                catch (err) {
+                    // Copy meta on failure too (same as dedupe joiners)
+                    if (signal.aborted) {
+                        ctx.meta.attempts = 0;
+                    }
+                    else {
+                        ctx.meta.attempts = inflight.meta.attempts;
+                        ctx.meta.source = inflight.meta.source;
+                    }
+                    throw err;
+                }
+            }
             // 3. Originator: launch fn, cache on success (fail-open).
-            const promise = Promise.resolve(fn(signal)).then((value) => {
+            //
+            // The stored promise is the RAW fn(signal) — NOT raceAbort-wrapped.
+            // Originator's own await is wrapped in raceWithOwnSignal so they
+            // can bail on their signal without affecting joiners.
+            const generation = nextGeneration();
+            const rawPromise = Promise.resolve(fn(signal)).then((value) => {
                 try {
-                    ctx.store.set(key, { value }, opts.ttl);
+                    store.set(key, { value, insertedAt: Date.now() }, 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.
+            }, 
+            // Re-throw the error so joiners see it. Don't cache failures.
+            (err) => { throw err; });
+            // Publish the in-flight entry for single-flight. If store.set
+            // throws, single-flight is disabled for this call — concurrent
+            // callers will all run fn. 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(() => { });
+                store.set(inflightKey, { promise: rawPromise, generation, meta: ctx.meta });
             }
             catch {
                 // Single-flight unavailable; proceed without publishing.
+                // Originator still gets their value (or error).
             }
-            return promise;
+            // Cleanup the in-flight slot on settle — generation-safe.
+            const cleanup = () => {
+                const current = store.get(inflightKey);
+                if (current && current.generation === generation) {
+                    try {
+                        store.delete(inflightKey);
+                    }
+                    catch { /* ignore */ }
+                }
+            };
+            rawPromise.then(cleanup, cleanup);
+            // Originator races the raw promise against their OWN signal.
+            return raceWithOwnSignal(rawPromise, signal);
         }
-        // ─── Async store: no single-flight (race window unavoidable) ─────────
+        // Async store: no single-flight (race window unavoidable).
+        // Re-check signal.aborted between awaits.
+        const obs = ctx.observability;
         const hit = await ctx.store.get(key);
+        if (signal.aborted)
+            return Promise.reject(signal.reason);
         if (hit) {
             ctx.meta.source = 'cache';
             ctx.meta.attempts = 0;
+            if (obs) {
+                const ageMs = Date.now() - hit.insertedAt;
+                obs.hooks.onCacheHit?.({
+                    type: 'cache-hit', key: ctx.key, traceId: obs.traceId,
+                    timestamp: Date.now(), ageMs: Math.max(0, ageMs),
+                });
+            }
             return hit.value;
         }
+        if (obs) {
+            obs.hooks.onCacheMiss?.({
+                type: 'cache-miss', key: ctx.key, traceId: obs.traceId,
+                timestamp: Date.now(),
+            });
+        }
         const value = await fn(signal);
+        if (signal.aborted)
+            return Promise.reject(signal.reason);
         try {
-            await ctx.store.set(key, { value }, opts.ttl);
+            await ctx.store.set(key, { value, insertedAt: Date.now() }, opts.ttl);
         }
         catch {
             // Fail-open: see sync path comment.
@@ -105,3 +200,45 @@ function cachePolicy(opts) {
         return value;
     };
 }
+/**
+ * Race a promise against a signal — but if the signal aborts, mark the
+ * underlying promise as handled (so its eventual rejection doesn't surface
+ * as an unhandled rejection). The underlying promise keeps running for any
+ * other consumers (e.g. joiners in single-flight).
+ *
+ * This is `raceAbort` from `utils/abort.ts`, inlined here to avoid an import
+ * cycle (cache.ts already imports from stores, dedupe imports from abort —
+ * keeping cache independent of abort reduces the import graph depth).
+ *
+ * Internal — not exported.
+ */
+function raceWithOwnSignal(promise, signal) {
+    if (signal.aborted) {
+        promise.catch(() => { }); // mark as handled
+        return Promise.reject(signal.reason);
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const onAbort = () => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener('abort', onAbort);
+            reject(signal.reason);
+        };
+        signal.addEventListener('abort', onAbort);
+        promise.then((value) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (error) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener('abort', onAbort);
+            reject(error);
+        });
+    });
+}

package/dist/policies/cache.d.ts

@@ -3,7 +3,22 @@ import type { CacheOptions, PolicyApplier } from '../types/index.js';
  * Short-circuit the entire downstream chain on a cache hit.
  * On a miss, run `fn` and store the result with TTL.
  *
- * # Single-flight (fixes cache stampede)
+ * # Properties
+ *
+ *  - **Single-flight originator isolation**: the stored in-flight promise is
+ *    the RAW `fn(signal)` — NOT raceAbort-wrapped. An originator's signal
+ *    abort no longer causes all cache-miss joiners to reject. Each caller
+ *    races against their OWN signal only.
+ *  - **Generation-safe inflight cleanup**: stale originators don't delete
+ *    newer entries (same pattern as dedupePolicy).
+ *  - **Signal-aware async store path**: between `await store.get()` and
+ *    `await store.set()`, we re-check `signal.aborted`. The previous
+ *    version would happily return a cached value even after the caller
+ *    aborted mid-Redis-latency.
+ *  - **Cache hit honours abort**: if `signal.aborted` is true at policy
+ *    entry, we reject immediately — consistent with `act()`'s contract.
+ *
+ * # Single-flight (cache stampede prevention)
  *
  * On a sync store, the policy also stores the in-flight Promise under a
  * separate `__inflight:cache:<key>` slot. Concurrent callers that miss the
@@ -26,9 +41,7 @@ import type { CacheOptions, PolicyApplier } from '../types/index.js';
  * # 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.)
+ * set to `0` — no work was performed.
  *
  * Failures are NEVER cached. Only successful values are stored.
  */

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;AAY1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,CAAC,CAAC,CAuEnE"}
+{"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;AA8B1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,CAAC,CAAC,CAkJnE"}