@zukhruf/async 0.6.14 → 0.6.16
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 +20 -1
- 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/dist/timeout.d.ts +17 -0
- package/dist/timeout.d.ts.map +1 -0
- package/dist/timeout.js +16 -0
- package/dist/timeout.js.map +1 -0
- 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, `poll` calls an attempt again until it gives a value, and `pollChanges` reads values 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, and `pollChanges` reads values 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
|
|
|
@@ -182,6 +182,25 @@ await delay(100, { clock: globalThis, signal });
|
|
|
182
182
|
- No listener stays on the signal after `delay` settles, so a signal that lives long can serve many waits.
|
|
183
183
|
- With `ref: false`, the timer does not keep the process alive.
|
|
184
184
|
|
|
185
|
+
## Stop a wait after a time
|
|
186
|
+
|
|
187
|
+
`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.
|
|
188
|
+
|
|
189
|
+
```ts
|
|
190
|
+
import { timeout } from '@zukhruf/async';
|
|
191
|
+
|
|
192
|
+
// Stop the read when the server does not answer in 5 seconds.
|
|
193
|
+
using limit = timeout(5_000, { clock: globalThis });
|
|
194
|
+
const state = await readState(container, { signal: limit.signal });
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
- The signal aborts with a `DOMException` whose name is `TimeoutError`, as the signal of `AbortSignal.timeout` does.
|
|
198
|
+
- A disposal stops the timer, and the signal then does not abort. `using` disposes the timeout at the end of the block.
|
|
199
|
+
- The timer keeps the process alive until it fires or until the disposal. The timer of `AbortSignal.timeout` does not keep the process alive, but no call can stop it.
|
|
200
|
+
- To stop a wait at the timeout or at the signal of the caller, give `AbortSignal.any([signal, limit.signal])`.
|
|
201
|
+
|
|
202
|
+
See [ADR 0006](./docs/adr/0006-a-timeout-is-a-signal-on-the-clock-that-the-caller-gives.md).
|
|
203
|
+
|
|
185
204
|
## Run a wait on a clock
|
|
186
205
|
|
|
187
206
|
Each wait of `poll` and `pollChanges` runs on the clock that you give. In production, give `globalThis`: the wait then uses the timers of Node.js. In a test, give a fake clock. The test then moves the time, and the wait takes no real time.
|
package/dist/index.d.ts
CHANGED
|
@@ -3,5 +3,6 @@ export { delay, type DelayOptions } from './delay.ts';
|
|
|
3
3
|
export { Latch } from './latch.ts';
|
|
4
4
|
export { poll, type PollOptions } from './poll.ts';
|
|
5
5
|
export { pollChanges, type PollChangesOptions } from './poll-changes.ts';
|
|
6
|
+
export { timeout, type Timeout, type TimeoutOptions } from './timeout.ts';
|
|
6
7
|
export { untilAborted } from './until-aborted.ts';
|
|
7
8
|
//# sourceMappingURL=index.d.ts.map
|
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,MAAM,YAAY,CAAC;AACxC,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,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,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,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -3,5 +3,6 @@ export { delay } from "./delay.js";
|
|
|
3
3
|
export { Latch } from "./latch.js";
|
|
4
4
|
export { poll } from "./poll.js";
|
|
5
5
|
export { pollChanges } from "./poll-changes.js";
|
|
6
|
+
export { timeout } from "./timeout.js";
|
|
6
7
|
export { untilAborted } from "./until-aborted.js";
|
|
7
8
|
//# sourceMappingURL=index.js.map
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,MAAM,YAAY,CAAC;AACxC,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,WAAW,EAA2B,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,MAAM,YAAY,CAAC;AACxC,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,WAAW,EAA2B,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,OAAO,EAAqC,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import type { Clock } from './clock.ts';
|
|
2
|
+
export interface TimeoutOptions {
|
|
3
|
+
/** The clock that the timer runs on: `globalThis` in production, a fake clock in a test. */
|
|
4
|
+
clock: Clock;
|
|
5
|
+
}
|
|
6
|
+
/** A signal that aborts after a time on a clock. A disposal stops its timer. */
|
|
7
|
+
export interface Timeout extends Disposable {
|
|
8
|
+
/** Aborts after the time, with a `DOMException` whose name is `TimeoutError`. */
|
|
9
|
+
readonly signal: AbortSignal;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Gives a signal that aborts after `ms` milliseconds on the clock, as
|
|
13
|
+
* `AbortSignal.timeout` does on the real clock. Dispose the timeout when the
|
|
14
|
+
* wait ends: `using limit = timeout(ms, { clock })`.
|
|
15
|
+
*/
|
|
16
|
+
export declare function timeout(ms: number, { clock }: TimeoutOptions): Timeout;
|
|
17
|
+
//# sourceMappingURL=timeout.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../src/timeout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,WAAW,cAAc;IAC7B,4FAA4F;IAC5F,KAAK,EAAE,KAAK,CAAC;CACd;AAED,gFAAgF;AAChF,MAAM,WAAW,OAAQ,SAAQ,UAAU;IACzC,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,EAAE,cAAc,GAAG,OAAO,CActE"}
|
package/dist/timeout.js
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Gives a signal that aborts after `ms` milliseconds on the clock, as
|
|
3
|
+
* `AbortSignal.timeout` does on the real clock. Dispose the timeout when the
|
|
4
|
+
* wait ends: `using limit = timeout(ms, { clock })`.
|
|
5
|
+
*/
|
|
6
|
+
export function timeout(ms, { clock }) {
|
|
7
|
+
const controller = new AbortController();
|
|
8
|
+
const timer = clock.setTimeout(() => {
|
|
9
|
+
controller.abort(new DOMException('The operation was aborted due to timeout', 'TimeoutError'));
|
|
10
|
+
}, ms);
|
|
11
|
+
return {
|
|
12
|
+
signal: controller.signal,
|
|
13
|
+
[Symbol.dispose]: () => clock.clearTimeout(timer),
|
|
14
|
+
};
|
|
15
|
+
}
|
|
16
|
+
//# sourceMappingURL=timeout.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"timeout.js","sourceRoot":"","sources":["../src/timeout.ts"],"names":[],"mappings":"AAaA;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,EAAU,EAAE,EAAE,KAAK,EAAkB;IAC3D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE;QAClC,UAAU,CAAC,KAAK,CACd,IAAI,YAAY,CACd,0CAA0C,EAC1C,cAAc,CACf,CACF,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC,CAAC;IACP,OAAO;QACL,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC;KAClD,CAAC;AACJ,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zukhruf/async",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.16",
|
|
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": {
|