actly 1.1.5 → 1.3.0

package/dist/core/executor.cjs

@@ -3,31 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.REQUIRES_SYNC_STORE = void 0;
 exports.execute = execute;
 const base_js_1 = require("../stores/base.js");
-/**
- * Symbol stamped onto `PolicyApplier` functions by `dedupePolicy`.
- *
- * Lets `execute()` detect a dedupe policy without importing the policy
- * module (which would create a circular dep) or doing fragile name-sniffing.
- */
 exports.REQUIRES_SYNC_STORE = Symbol('actly.requiresSyncStore');
-/**
- * Pure execution engine.
- *
- * 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 — 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). ' +
@@ -38,10 +15,8 @@ async function execute(input) {
         key: input.key,
         store: input.store,
         meta: input.meta,
+        observability: input.observability,
     };
-    // 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);
-    // Call the outermost wrapper with the root signal.
     return wrapped(input.signal);
 }

package/dist/core/executor.d.ts

@@ -1,49 +1,13 @@
-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.
- */
+import type { ActFn, PolicyApplier, AnyStateStore, RunMeta, ObservabilityContext } from '../types/index.js';
 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`.
-     *
-     * Canonical order: `[totalTimeout, cache, dedupe, retry, timeout]`
-     *   totalTimeout -> hard wall-clock budget over the entire operation
-     *   cache        -> a hit skips everything below it
-     *   dedupe       -> collapses concurrent callers before retry fires
-     *   retry        -> owns the attempt loop
-     *   timeout      -> each individual attempt races against the clock
-     */
     policies: ReadonlyArray<PolicyApplier<T>>;
     store: 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;
+    observability?: ObservabilityContext;
 }
-/**
- * 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`.
- *
- * # 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;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"}
+{"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,EACP,oBAAoB,EACrB,MAAM,mBAAmB,CAAA;AAQ1B,eAAO,MAAM,mBAAmB,eAAoC,CAAA;AAEpE,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,GAAG,EAAO,MAAM,CAAA;IAChB,EAAE,EAAQ,KAAK,CAAC,CAAC,CAAC,CAAA;IAYlB,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAA;IACzC,KAAK,EAAK,aAAa,CAAA;IACvB,IAAI,EAAM,OAAO,CAAA;IAOjB,MAAM,EAAI,WAAW,CAAA;IAKrB,aAAa,CAAC,EAAE,oBAAoB,CAAA;CACrC;AAWD,wBAAsB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CA+BpE"}

package/dist/core/executor.js

@@ -1,29 +1,6 @@
 import { isSyncStore } from '../stores/base.js';
-/**
- * Symbol stamped onto `PolicyApplier` functions by `dedupePolicy`.
- *
- * Lets `execute()` detect a dedupe policy without importing the policy
- * module (which would create a circular dep) or doing fragile name-sniffing.
- */
 export const REQUIRES_SYNC_STORE = Symbol('actly.requiresSyncStore');
-/**
- * Pure execution engine.
- *
- * 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 — 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). ' +
@@ -34,11 +11,8 @@ export async function execute(input) {
         key: input.key,
         store: input.store,
         meta: input.meta,
+        observability: input.observability,
     };
-    // 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);
-    // Call the outermost wrapper with the root signal.
     return wrapped(input.signal);
 }
-//# sourceMappingURL=executor.js.map

package/dist/core/health.cjs

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerStoreScope = registerStoreScope;
+exports.resolveStoreScope = resolveStoreScope;
+exports.registerInflight = registerInflight;
+exports.unregisterInflight = unregisterInflight;
+exports.enableWatchdog = enableWatchdog;
+exports.registerWatchdogHooks = registerWatchdogHooks;
+exports.unregisterWatchdogHooks = unregisterWatchdogHooks;
+exports.disableWatchdog = disableWatchdog;
+exports.recordError = recordError;
+exports.recordSuccess = recordSuccess;
+exports.createHealthCheck = createHealthCheck;
+const limits_js_1 = require("../utils/limits.js");
+const errors_js_1 = require("../errors.js");
+const safeCall_js_1 = require("../utils/safeCall.js");
+const storeScopes = new WeakMap();
+function registerStoreScope(store, scope) {
+    storeScopes.set(store, scope);
+}
+function resolveStoreScope(store) {
+    return storeScopes.get(store);
+}
+const healthStates = new Map();
+const startTime = Date.now();
+const INFLIGHT_LIMIT_DISABLED = process.env.ACTLY_NO_INFLIGHT_LIMIT === '1' ||
+    process.env.ACTLY_NO_INFLIGHT_LIMIT === 'true';
+const INFLIGHT_LIMIT = limits_js_1.LIMITS.MAX_GLOBAL_INFLIGHT;
+let globalInflightCount = 0;
+let inflightBusySince;
+let watchdogTimer;
+let watchdogThresholdMs = 60_000;
+const watchdogHooks = new Set();
+let watchdogFiredForBusySince;
+function noteInflightUp() {
+    if (inflightBusySince === undefined) {
+        inflightBusySince = Date.now();
+    }
+}
+function noteInflightDown() {
+    if (globalInflightCount === 0) {
+        inflightBusySince = undefined;
+        watchdogFiredForBusySince = undefined;
+    }
+}
+function getState(scope) {
+    let s = healthStates.get(scope);
+    if (!s) {
+        s = { inflight: 0 };
+        healthStates.set(scope, s);
+    }
+    return s;
+}
+function registerInflight(scope) {
+    if (!INFLIGHT_LIMIT_DISABLED && globalInflightCount >= INFLIGHT_LIMIT) {
+        throw new errors_js_1.ResourceExhaustedError(globalInflightCount, INFLIGHT_LIMIT);
+    }
+    globalInflightCount++;
+    noteInflightUp();
+    getState(scope).inflight++;
+}
+function unregisterInflight(scope) {
+    globalInflightCount = Math.max(0, globalInflightCount - 1);
+    noteInflightDown();
+    const s = getState(scope);
+    s.inflight = Math.max(0, s.inflight - 1);
+    if (s.inflight === 0 && s.lastError === undefined && scope !== 'default') {
+        healthStates.delete(scope);
+    }
+}
+function enableWatchdog(thresholdMs = 60_000, hooks) {
+    const prevThreshold = watchdogThresholdMs;
+    watchdogThresholdMs = thresholdMs;
+    if (hooks)
+        watchdogHooks.add(hooks);
+    if (watchdogTimer && thresholdMs === prevThreshold)
+        return;
+    if (watchdogTimer) {
+        clearInterval(watchdogTimer);
+        watchdogTimer = undefined;
+    }
+    const intervalMs = Math.max(50, Math.floor(thresholdMs / 4));
+    watchdogTimer = setInterval(() => {
+        if (globalInflightCount === 0)
+            return;
+        if (inflightBusySince === undefined)
+            return;
+        const elapsed = Date.now() - inflightBusySince;
+        if (elapsed < watchdogThresholdMs)
+            return;
+        if (watchdogFiredForBusySince === inflightBusySince)
+            return;
+        watchdogFiredForBusySince = inflightBusySince;
+        const event = {
+            type: 'watchdog',
+            key: '<unknown>',
+            traceId: '<watchdog>',
+            timestamp: Date.now(),
+            elapsedMs: elapsed,
+            scope: '<process>',
+        };
+        for (const h of watchdogHooks) {
+            (0, safeCall_js_1.safeCall)(h.onWatchdog, event);
+        }
+    }, intervalMs);
+    const t = watchdogTimer;
+    if (typeof t.unref === 'function')
+        t.unref();
+}
+function registerWatchdogHooks(hooks) {
+    watchdogHooks.add(hooks);
+}
+function unregisterWatchdogHooks(hooks) {
+    watchdogHooks.delete(hooks);
+}
+function disableWatchdog() {
+    if (watchdogTimer) {
+        clearInterval(watchdogTimer);
+        watchdogTimer = undefined;
+    }
+    watchdogHooks.clear();
+}
+function recordError(scope, code, message) {
+    const s = getState(scope);
+    s.lastError = { code, message, timestamp: Date.now() };
+}
+function recordSuccess(scope) {
+    getState(scope).lastSuccessAt = Date.now();
+}
+function createHealthCheck(store, options) {
+    const scope = options?.scope ?? resolveStoreScope(store) ?? 'default';
+    const probeIntervalMs = options?.probeIntervalMs;
+    let probeTimer;
+    if (probeIntervalMs && probeIntervalMs > 0) {
+        probeTimer = setInterval(() => {
+            const s = healthStates.get(scope);
+            if (s && s.inflight > 0) {
+                console.warn(`Actly: health probe detected ${s.inflight} in-flight calls in scope "${scope}" ` +
+                    `at ${new Date().toISOString()}. If this persists, a fn may be hung.`);
+            }
+        }, probeIntervalMs);
+        const t = probeTimer;
+        if (typeof t.unref === 'function')
+            t.unref();
+    }
+    const checkFn = () => {
+        const s = healthStates.get(scope);
+        return {
+            storeSize: store.size(),
+            pendingInflight: s?.inflight ?? 0,
+            uptimeMs: Date.now() - startTime,
+            lastError: s?.lastError,
+            lastSuccessAt: s?.lastSuccessAt,
+        };
+    };
+    checkFn.dispose = () => {
+        if (probeTimer !== undefined) {
+            clearInterval(probeTimer);
+            probeTimer = undefined;
+        }
+    };
+    return checkFn;
+}

package/dist/core/health.d.ts

@@ -0,0 +1,33 @@
+import type { InMemoryStore } from '../stores/memory.js';
+import type { AnyStateStore } from '../types/index.js';
+import type { ObservabilityHooks } from '../observability.js';
+export declare function registerStoreScope(store: AnyStateStore, scope: string): void;
+export declare function resolveStoreScope(store: AnyStateStore): string | undefined;
+export interface HealthStatus {
+    storeSize: number;
+    pendingInflight: number;
+    uptimeMs: number;
+    lastError?: {
+        code: string;
+        message: string;
+        timestamp: number;
+    };
+    lastSuccessAt?: number;
+}
+export declare function registerInflight(scope: string): void;
+export declare function unregisterInflight(scope: string): void;
+export declare function enableWatchdog(thresholdMs?: number, hooks?: ObservabilityHooks): void;
+export declare function registerWatchdogHooks(hooks: ObservabilityHooks): void;
+export declare function unregisterWatchdogHooks(hooks: ObservabilityHooks): void;
+export declare function disableWatchdog(): void;
+export declare function recordError(scope: string, code: string, message: string): void;
+export declare function recordSuccess(scope: string): void;
+export interface HealthCheckFn {
+    (): HealthStatus;
+    dispose(): void;
+}
+export declare function createHealthCheck(store: InMemoryStore, options?: {
+    scope?: string;
+    probeIntervalMs?: number;
+}): HealthCheckFn;
+//# sourceMappingURL=health.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/core/health.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAGtD,OAAO,KAAK,EAAE,kBAAkB,EAAiB,MAAM,qBAAqB,CAAA;AAkB5E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAE5E;AAMD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAE1E;AAOD,MAAM,WAAW,YAAY;IAE3B,SAAS,EAAE,MAAM,CAAA;IAEjB,eAAe,EAAE,MAAM,CAAA;IAEvB,QAAQ,EAAE,MAAM,CAAA;IAEhB,SAAS,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAEhE,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAwED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAUpD;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAYtD;AAgBD,wBAAgB,cAAc,CAC5B,WAAW,SAAS,EACpB,KAAK,CAAC,EAAE,kBAAkB,GACzB,IAAI,CAgDN;AAOD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAErE;AAUD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAEvE;AAMD,wBAAgB,eAAe,IAAI,IAAI,CAMtC;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAG9E;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEjD;AAMD,MAAM,WAAW,aAAa;IAC5B,IAAI,YAAY,CAAA;IAEhB,OAAO,IAAI,IAAI,CAAA;CAChB;AAmBD,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,aAAa,EACpB,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,GACrD,aAAa,CA2Cf"}

package/dist/core/health.js

@@ -0,0 +1,150 @@
+import { LIMITS } from '../utils/limits.js';
+import { ResourceExhaustedError } from '../errors.js';
+import { safeCall } from '../utils/safeCall.js';
+const storeScopes = new WeakMap();
+export function registerStoreScope(store, scope) {
+    storeScopes.set(store, scope);
+}
+export function resolveStoreScope(store) {
+    return storeScopes.get(store);
+}
+const healthStates = new Map();
+const startTime = Date.now();
+const INFLIGHT_LIMIT_DISABLED = process.env.ACTLY_NO_INFLIGHT_LIMIT === '1' ||
+    process.env.ACTLY_NO_INFLIGHT_LIMIT === 'true';
+const INFLIGHT_LIMIT = LIMITS.MAX_GLOBAL_INFLIGHT;
+let globalInflightCount = 0;
+let inflightBusySince;
+let watchdogTimer;
+let watchdogThresholdMs = 60_000;
+const watchdogHooks = new Set();
+let watchdogFiredForBusySince;
+function noteInflightUp() {
+    if (inflightBusySince === undefined) {
+        inflightBusySince = Date.now();
+    }
+}
+function noteInflightDown() {
+    if (globalInflightCount === 0) {
+        inflightBusySince = undefined;
+        watchdogFiredForBusySince = undefined;
+    }
+}
+function getState(scope) {
+    let s = healthStates.get(scope);
+    if (!s) {
+        s = { inflight: 0 };
+        healthStates.set(scope, s);
+    }
+    return s;
+}
+export function registerInflight(scope) {
+    if (!INFLIGHT_LIMIT_DISABLED && globalInflightCount >= INFLIGHT_LIMIT) {
+        throw new ResourceExhaustedError(globalInflightCount, INFLIGHT_LIMIT);
+    }
+    globalInflightCount++;
+    noteInflightUp();
+    getState(scope).inflight++;
+}
+export function unregisterInflight(scope) {
+    globalInflightCount = Math.max(0, globalInflightCount - 1);
+    noteInflightDown();
+    const s = getState(scope);
+    s.inflight = Math.max(0, s.inflight - 1);
+    if (s.inflight === 0 && s.lastError === undefined && scope !== 'default') {
+        healthStates.delete(scope);
+    }
+}
+export function enableWatchdog(thresholdMs = 60_000, hooks) {
+    const prevThreshold = watchdogThresholdMs;
+    watchdogThresholdMs = thresholdMs;
+    if (hooks)
+        watchdogHooks.add(hooks);
+    if (watchdogTimer && thresholdMs === prevThreshold)
+        return;
+    if (watchdogTimer) {
+        clearInterval(watchdogTimer);
+        watchdogTimer = undefined;
+    }
+    const intervalMs = Math.max(50, Math.floor(thresholdMs / 4));
+    watchdogTimer = setInterval(() => {
+        if (globalInflightCount === 0)
+            return;
+        if (inflightBusySince === undefined)
+            return;
+        const elapsed = Date.now() - inflightBusySince;
+        if (elapsed < watchdogThresholdMs)
+            return;
+        if (watchdogFiredForBusySince === inflightBusySince)
+            return;
+        watchdogFiredForBusySince = inflightBusySince;
+        const event = {
+            type: 'watchdog',
+            key: '<unknown>',
+            traceId: '<watchdog>',
+            timestamp: Date.now(),
+            elapsedMs: elapsed,
+            scope: '<process>',
+        };
+        for (const h of watchdogHooks) {
+            safeCall(h.onWatchdog, event);
+        }
+    }, intervalMs);
+    const t = watchdogTimer;
+    if (typeof t.unref === 'function')
+        t.unref();
+}
+export function registerWatchdogHooks(hooks) {
+    watchdogHooks.add(hooks);
+}
+export function unregisterWatchdogHooks(hooks) {
+    watchdogHooks.delete(hooks);
+}
+export function disableWatchdog() {
+    if (watchdogTimer) {
+        clearInterval(watchdogTimer);
+        watchdogTimer = undefined;
+    }
+    watchdogHooks.clear();
+}
+export function recordError(scope, code, message) {
+    const s = getState(scope);
+    s.lastError = { code, message, timestamp: Date.now() };
+}
+export function recordSuccess(scope) {
+    getState(scope).lastSuccessAt = Date.now();
+}
+export function createHealthCheck(store, options) {
+    const scope = options?.scope ?? resolveStoreScope(store) ?? 'default';
+    const probeIntervalMs = options?.probeIntervalMs;
+    let probeTimer;
+    if (probeIntervalMs && probeIntervalMs > 0) {
+        probeTimer = setInterval(() => {
+            const s = healthStates.get(scope);
+            if (s && s.inflight > 0) {
+                console.warn(`Actly: health probe detected ${s.inflight} in-flight calls in scope "${scope}" ` +
+                    `at ${new Date().toISOString()}. If this persists, a fn may be hung.`);
+            }
+        }, probeIntervalMs);
+        const t = probeTimer;
+        if (typeof t.unref === 'function')
+            t.unref();
+    }
+    const checkFn = () => {
+        const s = healthStates.get(scope);
+        return {
+            storeSize: store.size(),
+            pendingInflight: s?.inflight ?? 0,
+            uptimeMs: Date.now() - startTime,
+            lastError: s?.lastError,
+            lastSuccessAt: s?.lastSuccessAt,
+        };
+    };
+    checkFn.dispose = () => {
+        if (probeTimer !== undefined) {
+            clearInterval(probeTimer);
+            probeTimer = undefined;
+        }
+    };
+    return checkFn;
+}

package/dist/core/shutdown.cjs

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDrainable = registerDrainable;
+exports.unregisterDrainable = unregisterDrainable;
+exports.drain = drain;
+exports.drainAll = drainAll;
+const drainStates = new Map();
+function getState(scope) {
+    let s = drainStates.get(scope);
+    if (!s) {
+        s = { inflight: 0, resolvers: [] };
+        drainStates.set(scope, s);
+    }
+    return s;
+}
+function registerDrainable(scope = 'default') {
+    getState(scope).inflight++;
+}
+function unregisterDrainable(scope = 'default') {
+    const s = getState(scope);
+    s.inflight = Math.max(0, s.inflight - 1);
+    if (s.inflight === 0) {
+        for (const r of s.resolvers)
+            r();
+        s.resolvers = [];
+        if (scope !== 'default') {
+            drainStates.delete(scope);
+        }
+    }
+}
+async function drain(timeoutMs, scope = 'default') {
+    const s = drainStates.get(scope);
+    if (!s)
+        return true;
+    if (s.inflight === 0) {
+        if (scope !== 'default' && s.resolvers.length === 0) {
+            drainStates.delete(scope);
+        }
+        return true;
+    }
+    return new Promise((resolve) => {
+        let resolved = false;
+        const resolver = () => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timer);
+            const idx = s.resolvers.indexOf(resolver);
+            if (idx >= 0)
+                s.resolvers.splice(idx, 1);
+            resolve(true);
+        };
+        const timer = setTimeout(() => {
+            if (resolved)
+                return;
+            resolved = true;
+            const idx = s.resolvers.indexOf(resolver);
+            if (idx >= 0)
+                s.resolvers.splice(idx, 1);
+            resolve(false);
+        }, timeoutMs);
+        s.resolvers.push(resolver);
+    });
+}
+async function drainAll(timeoutMs) {
+    const scopes = Array.from(drainStates.keys());
+    if (scopes.length === 0)
+        return true;
+    const results = await Promise.all(scopes.map(scope => drain(timeoutMs, scope)));
+    return results.every(r => r === true);
+}

package/dist/core/shutdown.d.ts

@@ -0,0 +1,5 @@
+export declare function registerDrainable(scope?: string): void;
+export declare function unregisterDrainable(scope?: string): void;
+export declare function drain(timeoutMs: number, scope?: string): Promise<boolean>;
+export declare function drainAll(timeoutMs: number): Promise<boolean>;
+//# sourceMappingURL=shutdown.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../src/core/shutdown.ts"],"names":[],"mappings":"AAWA,wBAAgB,iBAAiB,CAAC,KAAK,SAAY,GAAG,IAAI,CAEzD;AAED,wBAAgB,mBAAmB,CAAC,KAAK,SAAY,GAAG,IAAI,CAgB3D;AAUD,wBAAsB,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,SAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAiClF;AAsBD,wBAAsB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAWlE"}

package/dist/core/shutdown.js

@@ -0,0 +1,65 @@
+const drainStates = new Map();
+function getState(scope) {
+    let s = drainStates.get(scope);
+    if (!s) {
+        s = { inflight: 0, resolvers: [] };
+        drainStates.set(scope, s);
+    }
+    return s;
+}
+export function registerDrainable(scope = 'default') {
+    getState(scope).inflight++;
+}
+export function unregisterDrainable(scope = 'default') {
+    const s = getState(scope);
+    s.inflight = Math.max(0, s.inflight - 1);
+    if (s.inflight === 0) {
+        for (const r of s.resolvers)
+            r();
+        s.resolvers = [];
+        if (scope !== 'default') {
+            drainStates.delete(scope);
+        }
+    }
+}
+export async function drain(timeoutMs, scope = 'default') {
+    const s = drainStates.get(scope);
+    if (!s)
+        return true;
+    if (s.inflight === 0) {
+        if (scope !== 'default' && s.resolvers.length === 0) {
+            drainStates.delete(scope);
+        }
+        return true;
+    }
+    return new Promise((resolve) => {
+        let resolved = false;
+        const resolver = () => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timer);
+            const idx = s.resolvers.indexOf(resolver);
+            if (idx >= 0)
+                s.resolvers.splice(idx, 1);
+            resolve(true);
+        };
+        const timer = setTimeout(() => {
+            if (resolved)
+                return;
+            resolved = true;
+            const idx = s.resolvers.indexOf(resolver);
+            if (idx >= 0)
+                s.resolvers.splice(idx, 1);
+            resolve(false);
+        }, timeoutMs);
+        s.resolvers.push(resolver);
+    });
+}
+export async function drainAll(timeoutMs) {
+    const scopes = Array.from(drainStates.keys());
+    if (scopes.length === 0)
+        return true;
+    const results = await Promise.all(scopes.map(scope => drain(timeoutMs, scope)));
+    return results.every(r => r === true);
+}