@zukhruf/async 0.8.17 → 0.8.19
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/README.md +38 -1
- package/dist/backoff.d.ts +46 -0
- package/dist/backoff.d.ts.map +1 -0
- package/dist/backoff.js +48 -0
- package/dist/backoff.js.map +1 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @zukhruf/async
|
|
2
2
|
|
|
3
|
-
Helpers for code that waits for promises: `untilAborted` cancels a wait, `Latch` holds callers until something happened, `delay` waits a fixed time on a clock, `timeout` stops a wait after a time on a clock, `poll` calls an attempt again until it gives a value, and `ChangeWatcher` reads gauges again and again and tells which values changed. `@zukhruf/mutex`, `@zukhruf/single-flight` and `@zukhruf/election` use them.
|
|
3
|
+
Helpers for code that waits for promises: `untilAborted` cancels a wait, `Latch` holds callers until something happened, `delay` waits a fixed time on a clock, `timeout` stops a wait after a time on a clock, `poll` calls an attempt again until it gives a value, `Backoff` gives a longer wait before each retry, and `ChangeWatcher` reads gauges again and again and tells which values changed. `@zukhruf/mutex`, `@zukhruf/single-flight` and `@zukhruf/election` use them.
|
|
4
4
|
|
|
5
5
|
The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
|
|
6
6
|
|
|
@@ -209,6 +209,43 @@ await delay(100, { clock: globalThis, signal });
|
|
|
209
209
|
|
|
210
210
|
See [ADR 0009](./docs/adr/0009-a-wait-longer-than-one-timer-runs-on-a-chain-of-timers.md).
|
|
211
211
|
|
|
212
|
+
## Wait longer before each retry
|
|
213
|
+
|
|
214
|
+
A caller tries an operation again after it failed: a retry. To give the other side time to recover, the caller waits longer before each retry, up to a limit. `Backoff` gives that wait. Configure it once, and give it the number of retries before this wait: 0 before the first retry. Then wait with `delay`.
|
|
215
|
+
|
|
216
|
+
```ts
|
|
217
|
+
import { Backoff, delay } from '@zukhruf/async';
|
|
218
|
+
|
|
219
|
+
const backoff = new Backoff({
|
|
220
|
+
initial: 25,
|
|
221
|
+
multiplier: 1.6,
|
|
222
|
+
max: 1_000,
|
|
223
|
+
jitter: { kind: 'ratio', ratio: 0.2 },
|
|
224
|
+
});
|
|
225
|
+
for (let retries = 0; !(await connect()); retries++) {
|
|
226
|
+
await delay(backoff.duration(retries), { clock: globalThis, signal });
|
|
227
|
+
}
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
- Without jitter, the wait is `min(max, initial · multiplier^retries)`: here 25, 40, 64, 102.4… ms, and 1,000 ms from the ninth wait.
|
|
231
|
+
- `Backoff` keeps no state. You keep the count of retries, and you decide when to stop, when to start again from 0, and which failures to try again.
|
|
232
|
+
- The wait is a number of milliseconds, so you can also store it, for example as the next start time of a job.
|
|
233
|
+
|
|
234
|
+
### Spread the retries of many callers
|
|
235
|
+
|
|
236
|
+
Many callers that failed at the same time retry at the same time, and they can fail again together. A jitter makes each wait random, so the retries spread. `random` gives a number in [0, 1), `Math.random` by default. Give a function that returns known numbers to get known waits in a test. `d` is the wait without jitter.
|
|
237
|
+
|
|
238
|
+
| `jitter` | Wait | From |
|
|
239
|
+
| ----------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------- |
|
|
240
|
+
| `{ kind: 'none' }` | `d` | |
|
|
241
|
+
| `{ kind: 'ratio', ratio: r }` | `d` ± `r · d`, for every wait, the first one too. A wait can be up to `(1 + r) · max` | cenkalti/backoff, gRPC connection backoff |
|
|
242
|
+
| `{ kind: 'full' }` | from 0 to `d` | AWS, full jitter |
|
|
243
|
+
| `{ kind: 'equal' }` | from `d / 2` to `d` | AWS, equal jitter |
|
|
244
|
+
|
|
245
|
+
The constructor throws a `RangeError` for an `initial` that is not a positive, finite number, a `multiplier` below 1, a `max` below `initial` or not finite, and a `ratio` that is not above 0 and at most 1. `duration` throws a `RangeError` for a count that is not an integer of 0 or more.
|
|
246
|
+
|
|
247
|
+
See [ADR 0011](./docs/adr/0011-a-back-off-gives-the-wait-before-a-retry-and-keeps-no-state.md).
|
|
248
|
+
|
|
212
249
|
## Stop a wait after a time
|
|
213
250
|
|
|
214
251
|
`timeout` gives a signal that aborts after a number of milliseconds on the clock that you give, as `AbortSignal.timeout` does on the real clock. Give the signal to a wait. Dispose the timeout when the wait ends.
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The random change to each wait, so that the retries of many callers spread.
|
|
3
|
+
* `d` is the wait without jitter: `min(max, initial · multiplier^retries)`.
|
|
4
|
+
*
|
|
5
|
+
* - `none`: `d`.
|
|
6
|
+
* - `ratio`: `d` ± `ratio · d`, after the cap, for every wait, the first one
|
|
7
|
+
* too, as cenkalti/backoff's RandomizationFactor and Kubernetes' Jitter do.
|
|
8
|
+
* - `full`: from 0 to `d` (AWS, full jitter).
|
|
9
|
+
* - `equal`: from `d / 2` to `d` (AWS, equal jitter).
|
|
10
|
+
*/
|
|
11
|
+
export type Jitter = {
|
|
12
|
+
kind: 'none';
|
|
13
|
+
} | {
|
|
14
|
+
kind: 'ratio';
|
|
15
|
+
ratio: number;
|
|
16
|
+
} | {
|
|
17
|
+
kind: 'full';
|
|
18
|
+
} | {
|
|
19
|
+
kind: 'equal';
|
|
20
|
+
};
|
|
21
|
+
export interface BackoffOptions {
|
|
22
|
+
/** The wait before the first retry, in milliseconds. */
|
|
23
|
+
initial: number;
|
|
24
|
+
/** The factor of each next wait: 2 doubles it. 1 or more. */
|
|
25
|
+
multiplier: number;
|
|
26
|
+
/** The longest wait without jitter, in milliseconds. `initial` or more. */
|
|
27
|
+
max: number;
|
|
28
|
+
jitter: Jitter;
|
|
29
|
+
/** Gives a number in [0, 1). The default is `Math.random`. */
|
|
30
|
+
random?: (() => number) | undefined;
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* A capped exponential back-off. It gives the wait before the next retry from
|
|
34
|
+
* the number of retries before it, and keeps no other state. The caller keeps
|
|
35
|
+
* the count and waits with `delay`.
|
|
36
|
+
*/
|
|
37
|
+
export declare class Backoff {
|
|
38
|
+
#private;
|
|
39
|
+
constructor(options: BackoffOptions);
|
|
40
|
+
/**
|
|
41
|
+
* The wait in milliseconds before the next retry. `retries` is the number
|
|
42
|
+
* of retries before this wait: 0 before the first retry.
|
|
43
|
+
*/
|
|
44
|
+
duration(retries: number): number;
|
|
45
|
+
}
|
|
46
|
+
//# sourceMappingURL=backoff.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../src/backoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,MAAM,GACd;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,MAAM,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CACrC;AAED;;;;GAIG;AACH,qBAAa,OAAO;;gBAON,OAAO,EAAE,cAAc;IAyBnC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;CAiBlC"}
|
package/dist/backoff.js
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A capped exponential back-off. It gives the wait before the next retry from
|
|
3
|
+
* the number of retries before it, and keeps no other state. The caller keeps
|
|
4
|
+
* the count and waits with `delay`.
|
|
5
|
+
*/
|
|
6
|
+
export class Backoff {
|
|
7
|
+
#initial;
|
|
8
|
+
#multiplier;
|
|
9
|
+
#max;
|
|
10
|
+
#jitter;
|
|
11
|
+
#random;
|
|
12
|
+
constructor(options) {
|
|
13
|
+
const { initial, multiplier, max, jitter } = options;
|
|
14
|
+
if (!(initial > 0))
|
|
15
|
+
throw new RangeError(`initial must be a positive number of milliseconds, not ${initial}`);
|
|
16
|
+
if (!(multiplier >= 1 && Number.isFinite(multiplier)))
|
|
17
|
+
throw new RangeError(`multiplier must be a finite number of 1 or more, not ${multiplier}`);
|
|
18
|
+
if (!(max >= initial && Number.isFinite(max)))
|
|
19
|
+
throw new RangeError(`max must be a finite number of initial (${initial}) or more, not ${max}`);
|
|
20
|
+
if (jitter.kind === 'ratio' && !(jitter.ratio > 0 && jitter.ratio <= 1))
|
|
21
|
+
throw new RangeError(`ratio must be above 0 and at most 1, not ${jitter.ratio}`);
|
|
22
|
+
this.#initial = initial;
|
|
23
|
+
this.#multiplier = multiplier;
|
|
24
|
+
this.#max = max;
|
|
25
|
+
this.#jitter = jitter;
|
|
26
|
+
this.#random = options.random ?? Math.random;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* The wait in milliseconds before the next retry. `retries` is the number
|
|
30
|
+
* of retries before this wait: 0 before the first retry.
|
|
31
|
+
*/
|
|
32
|
+
duration(retries) {
|
|
33
|
+
if (!(Number.isInteger(retries) && retries >= 0))
|
|
34
|
+
throw new RangeError(`retries must be an integer of 0 or more, not ${retries}`);
|
|
35
|
+
const d = Math.min(this.#max, this.#initial * this.#multiplier ** retries);
|
|
36
|
+
switch (this.#jitter.kind) {
|
|
37
|
+
case 'none':
|
|
38
|
+
return d;
|
|
39
|
+
case 'ratio':
|
|
40
|
+
return d + d * this.#jitter.ratio * (2 * this.#random() - 1);
|
|
41
|
+
case 'full':
|
|
42
|
+
return this.#random() * d;
|
|
43
|
+
case 'equal':
|
|
44
|
+
return d / 2 + (this.#random() * d) / 2;
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
//# sourceMappingURL=backoff.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../src/backoff.ts"],"names":[],"mappings":"AA4BA;;;;GAIG;AACH,MAAM,OAAO,OAAO;IACT,QAAQ,CAAS;IACjB,WAAW,CAAS;IACpB,IAAI,CAAS;IACb,OAAO,CAAS;IAChB,OAAO,CAAe;IAE/B,YAAY,OAAuB;QACjC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QACrD,IAAI,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC;YAChB,MAAM,IAAI,UAAU,CAClB,0DAA0D,OAAO,EAAE,CACpE,CAAC;QACJ,IAAI,CAAC,CAAC,UAAU,IAAI,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;YACnD,MAAM,IAAI,UAAU,CAClB,wDAAwD,UAAU,EAAE,CACrE,CAAC;QACJ,IAAI,CAAC,CAAC,GAAG,IAAI,OAAO,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC3C,MAAM,IAAI,UAAU,CAClB,2CAA2C,OAAO,kBAAkB,GAAG,EAAE,CAC1E,CAAC;QACJ,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,IAAI,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC;YACrE,MAAM,IAAI,UAAU,CAClB,4CAA4C,MAAM,CAAC,KAAK,EAAE,CAC3D,CAAC;QACJ,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;QAChB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC;IAC/C,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,OAAe;QACtB,IAAI,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,IAAI,CAAC,CAAC;YAC9C,MAAM,IAAI,UAAU,CAClB,gDAAgD,OAAO,EAAE,CAC1D,CAAC;QACJ,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,WAAW,IAAI,OAAO,CAAC,CAAC;QAC3E,QAAQ,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YAC1B,KAAK,MAAM;gBACT,OAAO,CAAC,CAAC;YACX,KAAK,OAAO;gBACV,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;YAC/D,KAAK,MAAM;gBACT,OAAO,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YAC5B,KAAK,OAAO;gBACV,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;CACF"}
|
package/dist/index.d.ts
CHANGED
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,OAAO,GACb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,KAAK,SAAS,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,OAAO,GACb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,KAAK,SAAS,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}
|
package/dist/index.js
CHANGED
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,KAAK,EAAqB,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAoB,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,OAAO,EAAqC,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAc,MAAM,YAAY,CAAC;AACxC,OAAO,EACL,aAAa,GAGd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAe,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,KAAK,EAA8B,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAoC,MAAM,cAAc,CAAC;AACzE,OAAO,EAA8B,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,KAAK,EAAqB,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAoB,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,OAAO,EAAqC,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAc,MAAM,YAAY,CAAC;AACxC,OAAO,EACL,aAAa,GAGd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAe,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,KAAK,EAA8B,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zukhruf/async",
|
|
3
|
-
"version": "0.8.
|
|
3
|
+
"version": "0.8.19",
|
|
4
4
|
"description": "Helpers for code that waits for promises: cancel a wait when an AbortSignal aborts, hold callers on a one-shot latch that never rejects, and poll an attempt until it gives a value.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|