actly 1.2.0 → 1.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +234 -0
- package/MIGRATION.md +141 -0
- package/README.md +326 -218
- package/SECURITY.md +56 -0
- package/dist/core/act.cjs +406 -220
- package/dist/core/act.d.ts +6 -84
- package/dist/core/act.d.ts.map +1 -1
- package/dist/core/act.js +405 -222
- package/dist/core/executor.cjs +0 -27
- package/dist/core/executor.d.ts +0 -41
- package/dist/core/executor.d.ts.map +1 -1
- package/dist/core/executor.js +0 -28
- package/dist/core/health.cjs +146 -17
- package/dist/core/health.d.ts +20 -5
- package/dist/core/health.d.ts.map +1 -1
- package/dist/core/health.js +140 -18
- package/dist/core/shutdown.cjs +19 -8
- package/dist/core/shutdown.d.ts +1 -4
- package/dist/core/shutdown.d.ts.map +1 -1
- package/dist/core/shutdown.js +18 -9
- package/dist/core/tenant.cjs +61 -19
- package/dist/core/tenant.d.ts +5 -10
- package/dist/core/tenant.d.ts.map +1 -1
- package/dist/core/tenant.js +61 -20
- package/dist/errors.cjs +70 -103
- package/dist/errors.d.ts +33 -90
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +66 -103
- package/dist/index.cjs +25 -22
- package/dist/index.d.ts +12 -8
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7 -15
- package/dist/observability.cjs +0 -39
- package/dist/observability.d.ts +19 -78
- package/dist/observability.d.ts.map +1 -1
- package/dist/observability.js +0 -40
- package/dist/policies/bulkhead.cjs +44 -4
- package/dist/policies/bulkhead.d.ts +0 -0
- package/dist/policies/bulkhead.d.ts.map +1 -1
- package/dist/policies/bulkhead.js +44 -5
- package/dist/policies/cache.cjs +22 -142
- package/dist/policies/cache.d.ts +0 -46
- package/dist/policies/cache.d.ts.map +1 -1
- package/dist/policies/cache.js +22 -143
- package/dist/policies/circuitBreaker.cjs +125 -31
- package/dist/policies/circuitBreaker.d.ts +0 -0
- package/dist/policies/circuitBreaker.d.ts.map +1 -1
- package/dist/policies/circuitBreaker.js +125 -32
- package/dist/policies/dedupe.cjs +19 -66
- package/dist/policies/dedupe.d.ts +0 -23
- package/dist/policies/dedupe.d.ts.map +1 -1
- package/dist/policies/dedupe.js +19 -67
- package/dist/policies/noop.cjs +6 -0
- package/dist/policies/noop.d.ts +3 -0
- package/dist/policies/noop.d.ts.map +1 -0
- package/dist/policies/noop.js +3 -0
- package/dist/policies/rateLimit.cjs +15 -5
- package/dist/policies/rateLimit.d.ts +0 -0
- package/dist/policies/rateLimit.d.ts.map +1 -1
- package/dist/policies/rateLimit.js +15 -6
- package/dist/policies/retry.cjs +100 -65
- package/dist/policies/retry.d.ts +0 -27
- package/dist/policies/retry.d.ts.map +1 -1
- package/dist/policies/retry.js +100 -66
- package/dist/policies/timeout.cjs +32 -60
- package/dist/policies/timeout.d.ts +0 -13
- package/dist/policies/timeout.d.ts.map +1 -1
- package/dist/policies/timeout.js +32 -71
- package/dist/stores/base.cjs +0 -10
- package/dist/stores/base.d.ts +4 -67
- package/dist/stores/base.d.ts.map +1 -1
- package/dist/stores/base.js +0 -11
- package/dist/stores/memory.cjs +75 -88
- package/dist/stores/memory.d.ts +7 -74
- package/dist/stores/memory.d.ts.map +1 -1
- package/dist/stores/memory.js +75 -89
- package/dist/testing/index.cjs +56 -0
- package/dist/testing/index.d.ts +6 -0
- package/dist/testing/index.d.ts.map +1 -0
- package/dist/testing/index.js +52 -0
- package/dist/types/index.cjs +0 -1
- package/dist/types/index.d.ts +17 -307
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/index.js +0 -2
- package/dist/utils/abort.cjs +14 -111
- package/dist/utils/abort.d.ts +3 -74
- package/dist/utils/abort.d.ts.map +1 -1
- package/dist/utils/abort.js +14 -112
- package/dist/utils/abortPool.cjs +1 -2
- package/dist/utils/abortPool.d.ts +0 -0
- package/dist/utils/abortPool.d.ts.map +1 -1
- package/dist/utils/abortPool.js +1 -3
- package/dist/utils/backoff.cjs +3 -21
- package/dist/utils/backoff.d.ts +0 -11
- package/dist/utils/backoff.d.ts.map +1 -1
- package/dist/utils/backoff.js +3 -22
- package/dist/utils/decorator.cjs +44 -0
- package/dist/utils/decorator.d.ts +3 -0
- package/dist/utils/decorator.d.ts.map +1 -0
- package/dist/utils/decorator.js +41 -0
- package/dist/utils/key.cjs +13 -45
- package/dist/utils/key.d.ts +0 -27
- package/dist/utils/key.d.ts.map +1 -1
- package/dist/utils/key.js +13 -46
- package/dist/utils/limits.cjs +9 -27
- package/dist/utils/limits.d.ts +9 -27
- package/dist/utils/limits.d.ts.map +1 -1
- package/dist/utils/limits.js +9 -28
- package/dist/utils/safeCall.cjs +28 -0
- package/dist/utils/safeCall.d.ts +2 -0
- package/dist/utils/safeCall.d.ts.map +1 -0
- package/dist/utils/safeCall.js +25 -0
- package/dist/utils/sanitize.cjs +22 -1
- package/dist/utils/sanitize.d.ts +0 -0
- package/dist/utils/sanitize.d.ts.map +1 -1
- package/dist/utils/sanitize.js +22 -2
- package/dist/utils/validate.cjs +81 -18
- package/dist/utils/validate.d.ts +6 -19
- package/dist/utils/validate.d.ts.map +1 -1
- package/dist/utils/validate.js +81 -19
- package/package.json +38 -4
- package/dist/core/act.js.map +0 -1
- package/dist/core/executor.js.map +0 -1
- package/dist/core/health.js.map +0 -1
- package/dist/core/shutdown.js.map +0 -1
- package/dist/core/tenant.js.map +0 -1
- package/dist/errors.js.map +0 -1
- package/dist/index.js.map +0 -1
- package/dist/observability.js.map +0 -1
- package/dist/policies/bulkhead.js.map +0 -1
- package/dist/policies/cache.js.map +0 -1
- package/dist/policies/circuitBreaker.js.map +0 -1
- package/dist/policies/dedupe.js.map +0 -1
- package/dist/policies/rateLimit.js.map +0 -1
- package/dist/policies/retry.js.map +0 -1
- package/dist/policies/timeout.js.map +0 -1
- package/dist/state/store.cjs +0 -14
- package/dist/state/store.d.ts +0 -11
- package/dist/state/store.d.ts.map +0 -1
- package/dist/state/store.js +0 -11
- package/dist/state/store.js.map +0 -1
- package/dist/stores/base.js.map +0 -1
- package/dist/stores/memory.js.map +0 -1
- package/dist/types/index.js.map +0 -1
- package/dist/utils/abort.js.map +0 -1
- package/dist/utils/abortPool.js.map +0 -1
- package/dist/utils/backoff.js.map +0 -1
- package/dist/utils/key.js.map +0 -1
- package/dist/utils/limits.js.map +0 -1
- package/dist/utils/sanitize.js.map +0 -1
- package/dist/utils/validate.js.map +0 -1
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.waitForObsHook = waitForObsHook;
|
|
4
|
+
exports.isActlyEventType = isActlyEventType;
|
|
5
|
+
function waitForObsHook(hooks, hookName, timeoutMs = 5000) {
|
|
6
|
+
let resolveFn;
|
|
7
|
+
let rejectFn;
|
|
8
|
+
const promise = new Promise((resolve, reject) => {
|
|
9
|
+
resolveFn = resolve;
|
|
10
|
+
rejectFn = reject;
|
|
11
|
+
});
|
|
12
|
+
let settled = false;
|
|
13
|
+
const timer = setTimeout(() => {
|
|
14
|
+
if (settled)
|
|
15
|
+
return;
|
|
16
|
+
settled = true;
|
|
17
|
+
hooks[hookName] = previousHook;
|
|
18
|
+
rejectFn(new Error(`Actly: waitForObsHook timed out after ${timeoutMs}ms waiting for "${String(hookName)}".`));
|
|
19
|
+
}, timeoutMs);
|
|
20
|
+
const unrefable = timer;
|
|
21
|
+
if (typeof unrefable.unref === 'function')
|
|
22
|
+
unrefable.unref();
|
|
23
|
+
const previousHook = hooks[hookName];
|
|
24
|
+
const cleanup = () => {
|
|
25
|
+
if (settled)
|
|
26
|
+
return;
|
|
27
|
+
settled = true;
|
|
28
|
+
clearTimeout(timer);
|
|
29
|
+
hooks[hookName] = previousHook;
|
|
30
|
+
};
|
|
31
|
+
hooks[hookName] = (event) => {
|
|
32
|
+
if (typeof previousHook === 'function') {
|
|
33
|
+
try {
|
|
34
|
+
previousHook(event);
|
|
35
|
+
}
|
|
36
|
+
catch { }
|
|
37
|
+
}
|
|
38
|
+
if (settled)
|
|
39
|
+
return;
|
|
40
|
+
cleanup();
|
|
41
|
+
resolveFn(event);
|
|
42
|
+
};
|
|
43
|
+
return Object.assign(promise, { cancel: cleanup });
|
|
44
|
+
}
|
|
45
|
+
function isActlyEventType(value) {
|
|
46
|
+
return (value === 'attempt' ||
|
|
47
|
+
value === 'retry' ||
|
|
48
|
+
value === 'cache-hit' ||
|
|
49
|
+
value === 'cache-miss' ||
|
|
50
|
+
value === 'dedupe-join' ||
|
|
51
|
+
value === 'timeout' ||
|
|
52
|
+
value === 'final-success' ||
|
|
53
|
+
value === 'final-failure' ||
|
|
54
|
+
value === 'backpressure' ||
|
|
55
|
+
value === 'watchdog');
|
|
56
|
+
}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { ObservabilityHooks, ActlyEventType } from '../observability.js';
|
|
2
|
+
export declare function waitForObsHook<K extends keyof ObservabilityHooks>(hooks: ObservabilityHooks, hookName: K, timeoutMs?: number): Promise<Parameters<NonNullable<ObservabilityHooks[K]>>[0]> & {
|
|
3
|
+
cancel: () => void;
|
|
4
|
+
};
|
|
5
|
+
export declare function isActlyEventType(value: unknown): value is ActlyEventType;
|
|
6
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAyB7E,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,kBAAkB,EAC/D,KAAK,EAAE,kBAAkB,EACzB,QAAQ,EAAE,CAAC,EACX,SAAS,SAAO,GACf,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG;IAAE,MAAM,EAAE,MAAM,IAAI,CAAA;CAAE,CA+CrF;AAMD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAaxE"}
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
export function waitForObsHook(hooks, hookName, timeoutMs = 5000) {
|
|
2
|
+
let resolveFn;
|
|
3
|
+
let rejectFn;
|
|
4
|
+
const promise = new Promise((resolve, reject) => {
|
|
5
|
+
resolveFn = resolve;
|
|
6
|
+
rejectFn = reject;
|
|
7
|
+
});
|
|
8
|
+
let settled = false;
|
|
9
|
+
const timer = setTimeout(() => {
|
|
10
|
+
if (settled)
|
|
11
|
+
return;
|
|
12
|
+
settled = true;
|
|
13
|
+
hooks[hookName] = previousHook;
|
|
14
|
+
rejectFn(new Error(`Actly: waitForObsHook timed out after ${timeoutMs}ms waiting for "${String(hookName)}".`));
|
|
15
|
+
}, timeoutMs);
|
|
16
|
+
const unrefable = timer;
|
|
17
|
+
if (typeof unrefable.unref === 'function')
|
|
18
|
+
unrefable.unref();
|
|
19
|
+
const previousHook = hooks[hookName];
|
|
20
|
+
const cleanup = () => {
|
|
21
|
+
if (settled)
|
|
22
|
+
return;
|
|
23
|
+
settled = true;
|
|
24
|
+
clearTimeout(timer);
|
|
25
|
+
hooks[hookName] = previousHook;
|
|
26
|
+
};
|
|
27
|
+
hooks[hookName] = (event) => {
|
|
28
|
+
if (typeof previousHook === 'function') {
|
|
29
|
+
try {
|
|
30
|
+
previousHook(event);
|
|
31
|
+
}
|
|
32
|
+
catch { }
|
|
33
|
+
}
|
|
34
|
+
if (settled)
|
|
35
|
+
return;
|
|
36
|
+
cleanup();
|
|
37
|
+
resolveFn(event);
|
|
38
|
+
};
|
|
39
|
+
return Object.assign(promise, { cancel: cleanup });
|
|
40
|
+
}
|
|
41
|
+
export function isActlyEventType(value) {
|
|
42
|
+
return (value === 'attempt' ||
|
|
43
|
+
value === 'retry' ||
|
|
44
|
+
value === 'cache-hit' ||
|
|
45
|
+
value === 'cache-miss' ||
|
|
46
|
+
value === 'dedupe-join' ||
|
|
47
|
+
value === 'timeout' ||
|
|
48
|
+
value === 'final-success' ||
|
|
49
|
+
value === 'final-failure' ||
|
|
50
|
+
value === 'backpressure' ||
|
|
51
|
+
value === 'watchdog');
|
|
52
|
+
}
|
package/dist/types/index.cjs
CHANGED
package/dist/types/index.d.ts
CHANGED
|
@@ -1,276 +1,86 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* The async function ACT wraps.
|
|
3
|
-
*
|
|
4
|
-
* Receives an {@link AbortSignal} that fires when:
|
|
5
|
-
* - the caller aborts via `options.signal`,
|
|
6
|
-
* - the per-attempt {@link TimeoutOptions} fires,
|
|
7
|
-
* - the operation-wide {@link ActOptions.totalTimeout} fires.
|
|
8
|
-
*
|
|
9
|
-
* Cooperative cancellation: pass `signal` through to `fetch`, `AbortController`,
|
|
10
|
-
* database drivers, or any primitive that accepts one. If you ignore it, ACT
|
|
11
|
-
* will still return promptly (the outer promise rejects), but the underlying
|
|
12
|
-
* work will keep running in the background — leaking resources until it
|
|
13
|
-
* settles on its own.
|
|
14
|
-
*
|
|
15
|
-
* Backwards compatible: `() => Promise<T>` is assignable to this type, so
|
|
16
|
-
* existing call sites continue to compile and run. They simply forgo
|
|
17
|
-
* cancellation.
|
|
18
|
-
*
|
|
19
|
-
* @example
|
|
20
|
-
* // Cooperative
|
|
21
|
-
* act('user:42', async (signal) => {
|
|
22
|
-
* return fetch(`/api/users/42`, { signal })
|
|
23
|
-
* }, { timeout: { ms: 5_000 } })
|
|
24
|
-
*
|
|
25
|
-
* @example
|
|
26
|
-
* // Legacy (still works, signal ignored)
|
|
27
|
-
* act('user:42', () => fetchUser(42))
|
|
28
|
-
*/
|
|
29
1
|
export type ActFn<T> = (signal: AbortSignal) => Promise<T> | T;
|
|
30
|
-
/** Where a successful result came from. */
|
|
31
2
|
export type ActSource = 'fresh' | 'cache';
|
|
32
3
|
export interface ActSuccess<T> {
|
|
33
4
|
ok: true;
|
|
34
5
|
value: T;
|
|
35
6
|
source: ActSource;
|
|
36
|
-
/**
|
|
37
|
-
* Number of attempts made before success.
|
|
38
|
-
*
|
|
39
|
-
* - Fresh success on first try: `1`
|
|
40
|
-
* - Fresh success after N retries: `N`
|
|
41
|
-
* - Cache hit: `0` (no work was performed)
|
|
42
|
-
* - Dedupe joiner: mirrors the originator's attempt count
|
|
43
|
-
*/
|
|
44
7
|
attempts: number;
|
|
45
|
-
/**
|
|
46
|
-
* Trace ID for correlation across logs/metrics. Present when
|
|
47
|
-
* `options.observability` or `options.traceId` is set; `undefined` otherwise.
|
|
48
|
-
*/
|
|
49
8
|
traceId?: string;
|
|
50
|
-
/** Wall-clock duration of this act() call in ms. */
|
|
51
9
|
durationMs?: number;
|
|
52
10
|
}
|
|
53
11
|
export interface ActFailure {
|
|
54
12
|
ok: false;
|
|
55
13
|
error: unknown;
|
|
56
|
-
/**
|
|
57
|
-
* Number of attempts made before final failure.
|
|
58
|
-
* For dedupe joiners: mirrors the originator's attempt count.
|
|
59
|
-
*/
|
|
60
14
|
attempts: number;
|
|
61
|
-
/**
|
|
62
|
-
* Trace ID for correlation across logs/metrics. Present when
|
|
63
|
-
* `options.observability` or `options.traceId` is set; `undefined` otherwise.
|
|
64
|
-
*/
|
|
65
15
|
traceId?: string;
|
|
66
|
-
/** Wall-clock duration of this act() call in ms. */
|
|
67
16
|
durationMs?: number;
|
|
68
17
|
}
|
|
69
18
|
export type ActResult<T> = ActSuccess<T> | ActFailure;
|
|
70
19
|
export interface RetryOptions {
|
|
71
|
-
/**
|
|
72
|
-
* Total number of attempts including the first call.
|
|
73
|
-
* Must be an integer >= 1.
|
|
74
|
-
*
|
|
75
|
-
* `attempts: 1` is a no-op (equivalent to omitting `retry`); the policy
|
|
76
|
-
* is not added to the chain. This is intentional — adding a policy that
|
|
77
|
-
* never retries is pure overhead.
|
|
78
|
-
*/
|
|
79
20
|
attempts: number;
|
|
80
|
-
/**
|
|
81
|
-
* Base delay between attempts in milliseconds. Defaults to 0 (no delay).
|
|
82
|
-
* Must be a non-negative finite number.
|
|
83
|
-
*/
|
|
84
21
|
delayMs?: number;
|
|
85
|
-
/**
|
|
86
|
-
* How the base delay grows per attempt:
|
|
87
|
-
* - `'none'` -> always `delayMs`
|
|
88
|
-
* - `'linear'` -> `delayMs * attempt`
|
|
89
|
-
* - `'exponential'` -> `delayMs * 2^(attempt-1)`
|
|
90
|
-
*
|
|
91
|
-
* The computed delay is then capped by {@link maxDelay} and jittered by
|
|
92
|
-
* {@link jitter} before being slept.
|
|
93
|
-
*
|
|
94
|
-
* Defaults to `'none'`.
|
|
95
|
-
*/
|
|
96
22
|
backoff?: 'none' | 'linear' | 'exponential';
|
|
97
|
-
|
|
98
|
-
* Hard cap on the computed delay. Defaults to `Infinity`.
|
|
99
|
-
*
|
|
100
|
-
* Without a cap, `exponential` backoff with `delayMs: 1000` and
|
|
101
|
-
* `attempts: 10` would sleep 8.5 minutes between attempts 9 and 10
|
|
102
|
-
* (256 seconds). Set `maxDelay` to something sane (e.g. 30_000) to
|
|
103
|
-
* bound worst-case latency.
|
|
104
|
-
*/
|
|
23
|
+
backoffFn?: (attempt: number, error: unknown, state: Record<string, unknown>) => number;
|
|
105
24
|
maxDelay?: number;
|
|
106
|
-
/**
|
|
107
|
-
* Jitter strategy applied to the (post-`maxDelay`) delay.
|
|
108
|
-
*
|
|
109
|
-
* - `'none'` -> no jitter, return delay as-is
|
|
110
|
-
* - `'full'` -> `random() * delay` (default; best for thundering-herd prevention)
|
|
111
|
-
* - `'equal'` -> `delay/2 + random() * delay/2`
|
|
112
|
-
* - `'decorrelated'` -> `base + random() * (delay - base)`
|
|
113
|
-
*
|
|
114
|
-
* Defaults to `'full'`. Jitter prevents synchronised retry storms when
|
|
115
|
-
* many callers fail at the same instant (e.g. after an upstream outage
|
|
116
|
-
* recovers) — without it, all callers retry on the same tick.
|
|
117
|
-
*/
|
|
118
25
|
jitter?: 'none' | 'full' | 'equal' | 'decorrelated';
|
|
119
|
-
/**
|
|
120
|
-
* Predicate called after each failure, before the next attempt.
|
|
121
|
-
* Return `false` to stop retrying immediately and surface the error.
|
|
122
|
-
*
|
|
123
|
-
* Called for every failure including the last attempt (so observers stay
|
|
124
|
-
* informed); the return value is only consulted when there are remaining
|
|
125
|
-
* attempts.
|
|
126
|
-
*
|
|
127
|
-
* Use this to skip retries for errors that are definitively non-recoverable
|
|
128
|
-
* (e.g. HTTP 4xx, AuthError, ValidationError).
|
|
129
|
-
*
|
|
130
|
-
* Default behaviour: retry on every error except `AbortError` (which
|
|
131
|
-
* indicates the caller or a timeout cancelled the operation).
|
|
132
|
-
*
|
|
133
|
-
* @param error The error thrown by the most recent attempt.
|
|
134
|
-
* @param attempt The 1-based number of the attempt that just failed.
|
|
135
|
-
*/
|
|
136
26
|
shouldRetry?: (error: unknown, attempt: number) => boolean;
|
|
27
|
+
shouldRetryResult?: <V>(value: V, attempt: number) => boolean;
|
|
28
|
+
dangerouslyUnref?: boolean;
|
|
137
29
|
}
|
|
138
30
|
export interface TimeoutOptions {
|
|
139
|
-
/**
|
|
140
|
-
* Abort after this many milliseconds.
|
|
141
|
-
* Must be a positive finite number.
|
|
142
|
-
*/
|
|
143
31
|
ms: number;
|
|
32
|
+
strategy?: 'race' | 'cooperative';
|
|
144
33
|
}
|
|
145
34
|
export interface DedupeOptions {
|
|
146
|
-
/**
|
|
147
|
-
* Collapse concurrent calls sharing the same key into one in-flight Promise.
|
|
148
|
-
* Opt-in: be explicit when you want this behaviour.
|
|
149
|
-
*/
|
|
150
35
|
enabled: boolean;
|
|
151
|
-
/**
|
|
152
|
-
* Safety-net TTL for the in-flight entry, in milliseconds.
|
|
153
|
-
*
|
|
154
|
-
* If the originator's promise does not settle within this window, the
|
|
155
|
-
* entry is removed from the store so subsequent callers can start fresh.
|
|
156
|
-
* Originator's promise continues in the background until it settles or
|
|
157
|
-
* an outer timeout fires.
|
|
158
|
-
*
|
|
159
|
-
* Default: `Infinity` (no safety net). Pair with `timeout` or
|
|
160
|
-
* `totalTimeout` for proper cancellation in production.
|
|
161
|
-
*/
|
|
162
36
|
inflightTtl?: number;
|
|
163
37
|
}
|
|
164
38
|
export interface CacheOptions {
|
|
165
|
-
/** Keep a successful result for this many milliseconds. Must be > 0. */
|
|
166
39
|
ttl: number;
|
|
167
40
|
}
|
|
168
41
|
export interface ActOptions<T = unknown> {
|
|
169
42
|
retry?: RetryOptions;
|
|
170
|
-
/** Per-attempt deadline. Each retry gets a fresh clock. */
|
|
171
43
|
timeout?: TimeoutOptions;
|
|
172
|
-
/**
|
|
173
|
-
* Collapse concurrent calls with the same key into one in-flight Promise.
|
|
174
|
-
*
|
|
175
|
-
* Shorthand: `dedupe: true`
|
|
176
|
-
* Full form: `dedupe: { enabled: true, inflightTtl: 30_000 }`
|
|
177
|
-
*/
|
|
178
44
|
dedupe?: boolean | DedupeOptions;
|
|
179
45
|
cache?: CacheOptions;
|
|
180
|
-
/**
|
|
181
|
-
* Hard budget over the ENTIRE operation — including all retry attempts,
|
|
182
|
-
* delays, and the per-attempt timeout.
|
|
183
|
-
*
|
|
184
|
-
* Distinct from `timeout`, which resets the clock on every attempt.
|
|
185
|
-
* Use both together to express: "each attempt may take at most X ms,
|
|
186
|
-
* but the whole thing must finish within Y ms."
|
|
187
|
-
*
|
|
188
|
-
* Rejects with {@link TotalTimeoutError} if the budget fires.
|
|
189
|
-
*/
|
|
190
46
|
totalTimeout?: TimeoutOptions;
|
|
191
|
-
/**
|
|
192
|
-
* Caller-provided cancellation signal.
|
|
193
|
-
*
|
|
194
|
-
* When this signal aborts:
|
|
195
|
-
* - if the operation has not yet started, it rejects immediately with
|
|
196
|
-
* the signal's `reason`,
|
|
197
|
-
* - if it is in progress, the inner {@link ActFn} receives an aborted
|
|
198
|
-
* signal (cooperative cancellation),
|
|
199
|
-
* - if it has already settled, the result is returned as normal.
|
|
200
|
-
*
|
|
201
|
-
* Combined with `timeout` / `totalTimeout`, this gives you full control
|
|
202
|
-
* over cancellation from outside `act()`.
|
|
203
|
-
*/
|
|
204
47
|
signal?: AbortSignal;
|
|
205
|
-
/**
|
|
206
|
-
* Observability hooks. All optional. When omitted entirely (the
|
|
207
|
-
* common case), zero overhead is incurred on the hot path — no event
|
|
208
|
-
* objects are allocated, no function calls are made.
|
|
209
|
-
*
|
|
210
|
-
* When hooks ARE registered, events are allocated lazily — only when
|
|
211
|
-
* the corresponding event actually fires.
|
|
212
|
-
*
|
|
213
|
-
* @example
|
|
214
|
-
* ```ts
|
|
215
|
-
* await act('user:42', fn, {
|
|
216
|
-
* retry: { attempts: 3 },
|
|
217
|
-
* observability: {
|
|
218
|
-
* onAttempt: (e) => metrics.increment('act.attempt', { key: e.key, attempt: e.attempt }),
|
|
219
|
-
* onFinalFailure: (e) => logger.error({ key: e.key, traceId: e.traceId, failedBy: e.failedBy }, 'act failed'),
|
|
220
|
-
* onFinalSuccess: (e) => metrics.histogram('act.duration', e.durationMs),
|
|
221
|
-
* },
|
|
222
|
-
* })
|
|
223
|
-
* ```
|
|
224
|
-
*/
|
|
225
48
|
observability?: ObservabilityHooks;
|
|
226
|
-
/**
|
|
227
|
-
* Trace ID for logs/metrics correlation. Auto-generated via crypto.randomUUID()
|
|
228
|
-
* when omitted. Appears on every observability event and on ActResult.traceId.
|
|
229
|
-
*/
|
|
230
49
|
traceId?: string;
|
|
231
|
-
/** Circuit breaker: trips open after N consecutive failures, blocks calls for a cooldown period. */
|
|
232
50
|
circuitBreaker?: CircuitBreakerOptions;
|
|
233
|
-
/** Bulkhead: limits concurrent in-flight calls per key. Excess callers queue or fail fast. */
|
|
234
51
|
bulkhead?: BulkheadOptions;
|
|
235
|
-
/** Rate limiter: limits calls per window per key. Excess callers fail with RateLimitError. */
|
|
236
52
|
rateLimit?: RateLimitOptions;
|
|
237
|
-
/** Hedge: sends a second fn call after delayMs if the first hasn't settled. Races them. */
|
|
238
53
|
hedge?: HedgeOptions;
|
|
239
|
-
/** Fallback: returns this value if all policies fail. Suppresses ActFailure. */
|
|
240
54
|
fallback?: FallbackOptions<T>;
|
|
241
|
-
/** Audit: logs every act() call with key, traceId, result, timestamp. */
|
|
242
55
|
audit?: AuditOptions;
|
|
243
56
|
}
|
|
244
57
|
export interface CircuitBreakerOptions {
|
|
245
|
-
/** Number of consecutive failures before the breaker opens. Must be >= 1. */
|
|
246
58
|
threshold: number;
|
|
247
|
-
/** How long to stay open before transitioning to half-open (ms). Must be > 0. */
|
|
248
59
|
cooldownMs: number;
|
|
249
|
-
/** Optional: reset failure count after this idle period (ms). Default: Infinity. */
|
|
250
60
|
resetTimeoutMs?: number;
|
|
61
|
+
strategy?: 'consecutive' | 'count';
|
|
62
|
+
countSize?: number;
|
|
63
|
+
countThreshold?: number;
|
|
64
|
+
countMinimumCalls?: number;
|
|
251
65
|
}
|
|
252
66
|
export interface BulkheadOptions {
|
|
253
|
-
/** Max concurrent in-flight calls per key. Must be >= 1. */
|
|
254
67
|
maxConcurrent: number;
|
|
255
|
-
/** How long to queue before rejecting with BulkheadOverflowError (ms). Default: 0 (fail fast). */
|
|
256
68
|
queueTimeoutMs?: number;
|
|
69
|
+
maxQueueSize?: number;
|
|
257
70
|
}
|
|
258
71
|
export interface RateLimitOptions {
|
|
259
|
-
/** Max calls per window per key. Must be >= 1. */
|
|
260
72
|
maxCalls: number;
|
|
261
|
-
/** Window size in ms. Must be > 0. */
|
|
262
73
|
windowMs: number;
|
|
263
74
|
}
|
|
264
75
|
export interface HedgeOptions {
|
|
265
|
-
/** Delay before sending the second (hedge) call (ms). Must be > 0. */
|
|
266
76
|
delayMs: number;
|
|
77
|
+
placement?: 'outside-retry' | 'inside-retry';
|
|
78
|
+
keepLoser?: boolean;
|
|
267
79
|
}
|
|
268
80
|
export interface FallbackOptions<T> {
|
|
269
|
-
/** Value to return if all retries/policies fail. */
|
|
270
81
|
value: T | (() => T | Promise<T>);
|
|
271
82
|
}
|
|
272
83
|
export interface AuditOptions {
|
|
273
|
-
/** Called with audit entry after every act() call (success or failure). */
|
|
274
84
|
log: (entry: AuditEntry) => void;
|
|
275
85
|
}
|
|
276
86
|
export interface AuditEntry {
|
|
@@ -280,127 +90,27 @@ export interface AuditEntry {
|
|
|
280
90
|
durationMs: number;
|
|
281
91
|
ok: boolean;
|
|
282
92
|
attempts: number;
|
|
283
|
-
failedBy?:
|
|
93
|
+
failedBy?: ActlyFailedBy;
|
|
284
94
|
error?: unknown;
|
|
285
95
|
}
|
|
286
|
-
|
|
287
|
-
* Mutable bag mutated in-place during execution.
|
|
288
|
-
* Policies annotate it; act() reads the final state to build ActResult.
|
|
289
|
-
*
|
|
290
|
-
* For dedupe joiners: the bag is copied from the originator's bag after the
|
|
291
|
-
* in-flight promise settles (success or failure), so `attempts` reflects
|
|
292
|
-
* the real effort, not the default `1`.
|
|
293
|
-
*/
|
|
96
|
+
export type ActlyFailedBy = 'abort' | 'timeout' | 'total-timeout' | 'retry-exhausted' | 'fn-error' | 'validation' | 'circuit-open' | 'bulkhead-full' | 'rate-limited' | 'resource-exhausted' | 'hedge-timeout';
|
|
294
97
|
export interface RunMeta {
|
|
295
98
|
attempts: number;
|
|
296
99
|
source: ActSource;
|
|
297
100
|
}
|
|
298
|
-
export
|
|
299
|
-
|
|
300
|
-
hooks: ObservabilityHooks;
|
|
301
|
-
joinerCounter: number;
|
|
302
|
-
}
|
|
303
|
-
/** User-supplied observability hooks. See `observability.ts` for full shape. */
|
|
304
|
-
export interface ObservabilityHooks {
|
|
305
|
-
onAttempt?: (event: {
|
|
306
|
-
readonly type: 'attempt';
|
|
307
|
-
readonly key: string;
|
|
308
|
-
readonly traceId: string;
|
|
309
|
-
readonly timestamp: number;
|
|
310
|
-
readonly attempt: number;
|
|
311
|
-
readonly durationMs?: number;
|
|
312
|
-
readonly error?: unknown;
|
|
313
|
-
}) => void;
|
|
314
|
-
onRetry?: (event: {
|
|
315
|
-
readonly type: 'retry';
|
|
316
|
-
readonly key: string;
|
|
317
|
-
readonly traceId: string;
|
|
318
|
-
readonly timestamp: number;
|
|
319
|
-
readonly attempt: number;
|
|
320
|
-
readonly delayMs: number;
|
|
321
|
-
readonly error: unknown;
|
|
322
|
-
}) => void;
|
|
323
|
-
onCacheHit?: (event: {
|
|
324
|
-
readonly type: 'cache-hit';
|
|
325
|
-
readonly key: string;
|
|
326
|
-
readonly traceId: string;
|
|
327
|
-
readonly timestamp: number;
|
|
328
|
-
readonly ageMs: number;
|
|
329
|
-
}) => void;
|
|
330
|
-
onCacheMiss?: (event: {
|
|
331
|
-
readonly type: 'cache-miss';
|
|
332
|
-
readonly key: string;
|
|
333
|
-
readonly traceId: string;
|
|
334
|
-
readonly timestamp: number;
|
|
335
|
-
}) => void;
|
|
336
|
-
onDedupeJoin?: (event: {
|
|
337
|
-
readonly type: 'dedupe-join';
|
|
338
|
-
readonly key: string;
|
|
339
|
-
readonly traceId: string;
|
|
340
|
-
readonly timestamp: number;
|
|
341
|
-
readonly joinerPosition: number;
|
|
342
|
-
}) => void;
|
|
343
|
-
onTimeout?: (event: {
|
|
344
|
-
readonly type: 'timeout';
|
|
345
|
-
readonly key: string;
|
|
346
|
-
readonly traceId: string;
|
|
347
|
-
readonly timestamp: number;
|
|
348
|
-
readonly kind: 'per-attempt' | 'total';
|
|
349
|
-
readonly ms: number;
|
|
350
|
-
}) => void;
|
|
351
|
-
onFinalSuccess?: (event: {
|
|
352
|
-
readonly type: 'final-success';
|
|
353
|
-
readonly key: string;
|
|
354
|
-
readonly traceId: string;
|
|
355
|
-
readonly timestamp: number;
|
|
356
|
-
readonly source: ActSource;
|
|
357
|
-
readonly attempts: number;
|
|
358
|
-
readonly durationMs: number;
|
|
359
|
-
}) => void;
|
|
360
|
-
onFinalFailure?: (event: {
|
|
361
|
-
readonly type: 'final-failure';
|
|
362
|
-
readonly key: string;
|
|
363
|
-
readonly traceId: string;
|
|
364
|
-
readonly timestamp: number;
|
|
365
|
-
readonly attempts: number;
|
|
366
|
-
readonly durationMs: number;
|
|
367
|
-
readonly failedBy: 'abort' | 'timeout' | 'total-timeout' | 'retry-exhausted' | 'fn-error' | 'validation';
|
|
368
|
-
readonly error: unknown;
|
|
369
|
-
}) => void;
|
|
370
|
-
}
|
|
371
|
-
/** Everything a policy receives about the current run. */
|
|
101
|
+
export type { ObservabilityContext } from '../observability.js';
|
|
102
|
+
import type { ObservabilityContext } from '../observability.js';
|
|
372
103
|
export interface PolicyContext {
|
|
373
104
|
key: string;
|
|
374
105
|
store: AnyStateStore;
|
|
375
106
|
meta: RunMeta;
|
|
376
|
-
/**
|
|
377
|
-
* Observability context. Present only when the caller supplied
|
|
378
|
-
* `options.observability` hooks. Policies check `ctx.observability != null`
|
|
379
|
-
* before allocating event objects — no overhead when absent.
|
|
380
|
-
*/
|
|
381
107
|
observability?: ObservabilityContext;
|
|
382
108
|
}
|
|
383
|
-
/**
|
|
384
|
-
* The ONLY shape the executor knows about policies.
|
|
385
|
-
*
|
|
386
|
-
* A policy wraps `ActFn<T>` and returns a new `ActFn<T>`. It may intercept
|
|
387
|
-
* before, after, or instead of the inner call. The executor never imports
|
|
388
|
-
* a concrete policy — only this type.
|
|
389
|
-
*/
|
|
390
109
|
export type PolicyApplier<T> = (fn: ActFn<T>, ctx: PolicyContext) => ActFn<T>;
|
|
391
110
|
import type { SyncStateStore, AsyncStateStore } from '../stores/base.js';
|
|
392
111
|
export type { SyncStateStore, AsyncStateStore };
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
*
|
|
396
|
-
* Kept for backwards compatibility — consumers typed against
|
|
397
|
-
* `StateStore` continues to compile without changes. A future major version
|
|
398
|
-
* may widen this to `SyncStateStore | AsyncStateStore`.
|
|
399
|
-
*/
|
|
112
|
+
import type { ObservabilityHooks as ObsHooks } from '../observability.js';
|
|
113
|
+
export type ObservabilityHooks = ObsHooks;
|
|
400
114
|
export type StateStore = SyncStateStore;
|
|
401
|
-
/**
|
|
402
|
-
* Union of sync and async stores. Used internally by `PolicyContext` and
|
|
403
|
-
* exported for consumers building custom policy chains or store adapters.
|
|
404
|
-
*/
|
|
405
115
|
export type AnyStateStore = SyncStateStore | AsyncStateStore;
|
|
406
116
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}
|
package/dist/types/index.js
CHANGED