actly 1.1.0 → 1.2.0

package/dist/index.js

@@ -1,6 +1,26 @@
-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 { ActlyError, ActlyAbortError, TimeoutError, TotalTimeoutError, RetryExhaustedError, ValidationError, } from './errors.js';
+// ─── Utilities (for custom policy authors) ────────────────────────────────────
+export { anySignal, raceAbort, sleep, linkSignal, isAbortError, } from './utils/abort.js';
+export { sanitizeKey, } from './utils/key.js';
+export { computeDelay, } from './utils/backoff.js';
+export { LIMITS, } from './utils/limits.js';
+// ─── Hardening: new error classes ────────────────────────────────────────────
+export { CircuitBreakerOpenError, BulkheadOverflowError, RateLimitError, } from './errors.js';
+// ─── Hardening: health check & graceful shutdown ─────────────────────────────
+export { createHealthCheck, } from './core/health.js';
+export { drain, } from './core/shutdown.js';
+// ─── Hardening: tenant isolation ─────────────────────────────────────────────
+export { createTenantStore, createAsyncTenantStore, } from './core/tenant.js';
+// ─── Hardening: error sanitization ───────────────────────────────────────────
+export { sanitizeErrorMessage, sanitizeError, } from './utils/sanitize.js';
+// ─── Hardening: AbortController pool ─────────────────────────────────────────
+export { acquireController, releaseController, poolSize, } from './utils/abortPool.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,UAAU,EACV,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,GAChB,MAAM,aAAa,CAAA;AAgDpB,iFAAiF;AAEjF,OAAO,EACL,SAAS,EACT,SAAS,EACT,KAAK,EACL,UAAU,EACV,YAAY,GACb,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EACL,WAAW,GACZ,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EACL,YAAY,GACb,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EACL,MAAM,GACP,MAAM,mBAAmB,CAAA;AAI1B,gFAAgF;AAEhF,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,cAAc,GACf,MAAM,aAAa,CAAA;AAEpB,gFAAgF;AAEhF,OAAO,EACL,iBAAiB,GAClB,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EACL,KAAK,GACN,MAAM,oBAAoB,CAAA;AAE3B,gFAAgF;AAEhF,OAAO,EACL,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,kBAAkB,CAAA;AAGzB,gFAAgF;AAEhF,OAAO,EACL,oBAAoB,EACpB,aAAa,GACd,MAAM,qBAAqB,CAAA;AAE5B,gFAAgF;AAEhF,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,QAAQ,GACT,MAAM,sBAAsB,CAAA"}

package/dist/observability.cjs

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasObservers = hasObservers;
+/**
+ * Quick null-check helper. Policies call this once at decision points; if
+ * it returns false, no further observability work is done.
+ */
+function hasObservers(ctx) {
+    return ctx.observability != null;
+}

package/dist/observability.d.ts

@@ -0,0 +1,145 @@
+/**
+ * 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
+ */
+import type { ActSource } from './types/index.js';
+/** Stable discriminator for telemetry. */
+export type ActlyEventType = 'attempt' | 'retry' | 'cache-hit' | 'cache-miss' | 'dedupe-join' | 'timeout' | 'final-success' | 'final-failure';
+/** Common fields on every event. */
+export interface ActlyEventBase {
+    /** The `key` passed to `act()`. */
+    readonly key: string;
+    /** Auto-generated trace ID (or user-supplied via `options.traceId`). */
+    readonly traceId: string;
+    /** Event timestamp (ms since epoch). */
+    readonly timestamp: number;
+    /** Discriminator for switch statements. */
+    readonly type: ActlyEventType;
+}
+export interface AttemptEvent extends ActlyEventBase {
+    readonly type: 'attempt';
+    /** 1-based attempt number. */
+    readonly attempt: number;
+    /** Duration of this attempt in ms (set after attempt settles). */
+    readonly durationMs?: number;
+    /** Error from this attempt, if it failed. */
+    readonly error?: unknown;
+}
+export interface RetryEvent extends ActlyEventBase {
+    readonly type: 'retry';
+    /** The attempt that just failed. */
+    readonly attempt: number;
+    /** The delay (ms) before the next attempt. */
+    readonly delayMs: number;
+    /** Error that triggered the retry. */
+    readonly error: unknown;
+}
+export interface CacheHitEvent extends ActlyEventBase {
+    readonly type: 'cache-hit';
+    /** Age of the cached value in ms. */
+    readonly ageMs: number;
+}
+export interface CacheMissEvent extends ActlyEventBase {
+    readonly type: 'cache-miss';
+}
+export interface DedupeJoinEvent extends ActlyEventBase {
+    readonly type: 'dedupe-join';
+    /** This caller's position in the joiner queue (1 = first joiner). */
+    readonly joinerPosition: number;
+}
+export interface TimeoutEvent extends ActlyEventBase {
+    readonly type: 'timeout';
+    /** Which deadline fired. */
+    readonly kind: 'per-attempt' | 'total';
+    /** The configured ms. */
+    readonly ms: number;
+}
+export interface FinalSuccessEvent extends ActlyEventBase {
+    readonly type: 'final-success';
+    /** Where the value came from. */
+    readonly source: ActSource;
+    /** Total attempts made (0 for cache hit). */
+    readonly attempts: number;
+    /** Total wall-clock duration of the act() call. */
+    readonly durationMs: number;
+}
+export interface FinalFailureEvent extends ActlyEventBase {
+    readonly type: 'final-failure';
+    /** Total attempts made. */
+    readonly attempts: number;
+    /** Total wall-clock duration of the act() call. */
+    readonly durationMs: number;
+    /** Stable reason for failure — use for telemetry tags. */
+    readonly failedBy: 'abort' | 'timeout' | 'total-timeout' | 'retry-exhausted' | 'fn-error' | 'validation';
+    /** The final error. */
+    readonly error: unknown;
+}
+export type ActlyEvent = AttemptEvent | RetryEvent | CacheHitEvent | CacheMissEvent | DedupeJoinEvent | TimeoutEvent | FinalSuccessEvent | FinalFailureEvent;
+/**
+ * User-supplied observability hooks. All optional. When absent, zero
+ * overhead is incurred on the hot path.
+ */
+export interface ObservabilityHooks {
+    onAttempt?: (event: AttemptEvent) => void;
+    onRetry?: (event: RetryEvent) => void;
+    onCacheHit?: (event: CacheHitEvent) => void;
+    onCacheMiss?: (event: CacheMissEvent) => void;
+    onDedupeJoin?: (event: DedupeJoinEvent) => void;
+    onTimeout?: (event: TimeoutEvent) => void;
+    onFinalSuccess?: (event: FinalSuccessEvent) => void;
+    onFinalFailure?: (event: FinalFailureEvent) => void;
+}
+/**
+ * Internal: thread observability through the policy chain without changing
+ * every policy's signature. We attach it to `PolicyContext` as an optional
+ * field — policies that emit events check for its presence.
+ *
+ * `traceId` is also stored here so policies can include it in events.
+ */
+export interface ObservabilityContext {
+    traceId: string;
+    hooks: ObservabilityHooks;
+    /** Counter for dedupe joiner position. Per-key, but we approximate by call. */
+    joinerCounter: number;
+}
+/**
+ * Quick null-check helper. Policies call this once at decision points; if
+ * it returns false, no further observability work is done.
+ */
+export declare function hasObservers(ctx: {
+    observability?: ObservabilityContext;
+}): ctx is {
+    observability: ObservabilityContext;
+};
+//# sourceMappingURL=observability.d.ts.map

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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"}