@zukhruf/async 0.6.14 → 0.6.15

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 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
@@ -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"}
@@ -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.14",
3
+ "version": "0.6.15",
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": {