actly 1.2.0 → 1.3.0

package/dist/observability.d.ts

@@ -1,73 +1,25 @@
-/**
- * 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. */
+import type { ActSource, ActlyFailedBy } from './types/index.js';
+export type ActlyEventType = 'attempt' | 'retry' | 'cache-hit' | 'cache-miss' | 'dedupe-join' | 'timeout' | 'final-success' | 'final-failure' | 'backpressure' | 'watchdog';
 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 {
@@ -75,41 +27,40 @@ export interface CacheMissEvent extends ActlyEventBase {
 }
 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 failedBy: ActlyFailedBy;
     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 type ActlyEvent = AttemptEvent | RetryEvent | CacheHitEvent | CacheMissEvent | DedupeJoinEvent | TimeoutEvent | FinalSuccessEvent | FinalFailureEvent | BackpressureEvent | WatchdogEvent;
+export interface BackpressureEvent extends ActlyEventBase {
+    readonly type: 'backpressure';
+    readonly source: 'bulkhead';
+    readonly queueLength: number;
+    readonly maxConcurrent: number;
+    readonly maxQueueSize: number;
+    readonly utilization: number;
+}
+export interface WatchdogEvent extends ActlyEventBase {
+    readonly type: 'watchdog';
+    readonly elapsedMs: number;
+    readonly scope: string;
+}
 export interface ObservabilityHooks {
     onAttempt?: (event: AttemptEvent) => void;
     onRetry?: (event: RetryEvent) => void;
@@ -119,24 +70,14 @@ export interface ObservabilityHooks {
     onTimeout?: (event: TimeoutEvent) => void;
     onFinalSuccess?: (event: FinalSuccessEvent) => void;
     onFinalFailure?: (event: FinalFailureEvent) => void;
+    onBackpressure?: (event: BackpressureEvent) => void;
+    onWatchdog?: (event: WatchdogEvent) => 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 {

package/dist/observability.d.ts.map

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

package/dist/observability.js

@@ -1,43 +1,3 @@
-/**
- * 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/policies/bulkhead.cjs

@@ -3,6 +3,7 @@ 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 safeCall_js_1 = require("../utils/safeCall.js");
 const NS = 'bulk:';
 function getState(store, key) {
     return store.get(NS + key) ?? { active: 0, queue: [] };
@@ -13,12 +14,12 @@ function setState(store, key, state) {
 function bulkheadPolicy(opts) {
     const maxConcurrent = Math.max(1, Math.floor(opts.maxConcurrent));
     const queueTimeoutMs = opts.queueTimeoutMs ?? 0;
+    const maxQueueSize = opts.maxQueueSize ?? Number.POSITIVE_INFINITY;
     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);
@@ -30,14 +31,19 @@ function bulkheadPolicy(opts) {
                 if (queueTimeoutMs === 0) {
                     throw new errors_js_1.BulkheadOverflowError(key, maxConcurrent);
                 }
+                const currentState = getState(syncCtx.store, key);
+                if (currentState.queue.length >= maxQueueSize) {
+                    throw new errors_js_1.BulkheadOverflowError(key, maxConcurrent);
+                }
                 return new Promise((resolve, reject) => {
                     const state2 = getState(syncCtx.store, key);
                     const entry = {
                         resolve,
                         reject,
+                        timer: undefined,
+                        onAbort: undefined,
                         signal,
                     };
-                    // Remove entry from queue on signal abort
                     entry.onAbort = () => {
                         const s = getState(syncCtx.store, key);
                         const idx = s.queue.indexOf(entry);
@@ -62,6 +68,30 @@ function bulkheadPolicy(opts) {
                     }
                     signal.addEventListener('abort', entry.onAbort, { once: true });
                     state2.queue.push(entry);
+                    const obs = syncCtx.observability;
+                    if (obs && maxQueueSize !== Number.POSITIVE_INFINITY) {
+                        const utilization = state2.queue.length / maxQueueSize;
+                        const wasOver80 = state2.backpressureEmitted === true;
+                        if (utilization >= 0.8 && !wasOver80) {
+                            ;
+                            state2.backpressureEmitted = true;
+                            (0, safeCall_js_1.safeCall)(obs.hooks.onBackpressure, {
+                                type: 'backpressure',
+                                key: syncCtx.key,
+                                traceId: obs.traceId,
+                                timestamp: Date.now(),
+                                source: 'bulkhead',
+                                queueLength: state2.queue.length,
+                                maxConcurrent,
+                                maxQueueSize,
+                                utilization,
+                            });
+                        }
+                        else if (utilization < 0.8 && wasOver80) {
+                            ;
+                            state2.backpressureEmitted = false;
+                        }
+                    }
                     setState(syncCtx.store, key, state2);
                 });
             };
@@ -73,7 +103,6 @@ function bulkheadPolicy(opts) {
                     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);
                     }
@@ -81,7 +110,18 @@ function bulkheadPolicy(opts) {
                 }
                 if (state.active < 0)
                     state.active = 0;
-                setState(syncCtx.store, key, state);
+                if (maxQueueSize !== Number.POSITIVE_INFINITY && state.backpressureEmitted === true) {
+                    if (state.queue.length / maxQueueSize < 0.8) {
+                        ;
+                        state.backpressureEmitted = false;
+                    }
+                }
+                if (state.active === 0 && state.queue.length === 0) {
+                    syncCtx.store.delete(NS + key);
+                }
+                else {
+                    setState(syncCtx.store, key, state);
+                }
             };
             await acquireSlot();
             try {

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

@@ -1 +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"}
+{"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;AA2B7F,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,eAAe,GAAG,aAAa,CAAC,CAAC,CAAC,CAkJzE"}

package/dist/policies/bulkhead.js

@@ -1,5 +1,6 @@
 import { REQUIRES_SYNC_STORE } from '../core/executor.js';
 import { BulkheadOverflowError } from '../errors.js';
+import { safeCall } from '../utils/safeCall.js';
 const NS = 'bulk:';
 function getState(store, key) {
     return store.get(NS + key) ?? { active: 0, queue: [] };
@@ -10,12 +11,12 @@ function setState(store, key, state) {
 export function bulkheadPolicy(opts) {
     const maxConcurrent = Math.max(1, Math.floor(opts.maxConcurrent));
     const queueTimeoutMs = opts.queueTimeoutMs ?? 0;
+    const maxQueueSize = opts.maxQueueSize ?? Number.POSITIVE_INFINITY;
     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);
@@ -27,14 +28,19 @@ export function bulkheadPolicy(opts) {
                 if (queueTimeoutMs === 0) {
                     throw new BulkheadOverflowError(key, maxConcurrent);
                 }
+                const currentState = getState(syncCtx.store, key);
+                if (currentState.queue.length >= maxQueueSize) {
+                    throw new BulkheadOverflowError(key, maxConcurrent);
+                }
                 return new Promise((resolve, reject) => {
                     const state2 = getState(syncCtx.store, key);
                     const entry = {
                         resolve,
                         reject,
+                        timer: undefined,
+                        onAbort: undefined,
                         signal,
                     };
-                    // Remove entry from queue on signal abort
                     entry.onAbort = () => {
                         const s = getState(syncCtx.store, key);
                         const idx = s.queue.indexOf(entry);
@@ -59,6 +65,30 @@ export function bulkheadPolicy(opts) {
                     }
                     signal.addEventListener('abort', entry.onAbort, { once: true });
                     state2.queue.push(entry);
+                    const obs = syncCtx.observability;
+                    if (obs && maxQueueSize !== Number.POSITIVE_INFINITY) {
+                        const utilization = state2.queue.length / maxQueueSize;
+                        const wasOver80 = state2.backpressureEmitted === true;
+                        if (utilization >= 0.8 && !wasOver80) {
+                            ;
+                            state2.backpressureEmitted = true;
+                            safeCall(obs.hooks.onBackpressure, {
+                                type: 'backpressure',
+                                key: syncCtx.key,
+                                traceId: obs.traceId,
+                                timestamp: Date.now(),
+                                source: 'bulkhead',
+                                queueLength: state2.queue.length,
+                                maxConcurrent,
+                                maxQueueSize,
+                                utilization,
+                            });
+                        }
+                        else if (utilization < 0.8 && wasOver80) {
+                            ;
+                            state2.backpressureEmitted = false;
+                        }
+                    }
                     setState(syncCtx.store, key, state2);
                 });
             };
@@ -70,7 +100,6 @@ export function bulkheadPolicy(opts) {
                     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);
                     }
@@ -78,7 +107,18 @@ export function bulkheadPolicy(opts) {
                 }
                 if (state.active < 0)
                     state.active = 0;
-                setState(syncCtx.store, key, state);
+                if (maxQueueSize !== Number.POSITIVE_INFINITY && state.backpressureEmitted === true) {
+                    if (state.queue.length / maxQueueSize < 0.8) {
+                        ;
+                        state.backpressureEmitted = false;
+                    }
+                }
+                if (state.active === 0 && state.queue.length === 0) {
+                    syncCtx.store.delete(NS + key);
+                }
+                else {
+                    setState(syncCtx.store, key, state);
+                }
             };
             await acquireSlot();
             try {
@@ -92,4 +132,3 @@ export function bulkheadPolicy(opts) {
     applier[REQUIRES_SYNC_STORE] = true;
     return applier;
 }
-//# sourceMappingURL=bulkhead.js.map