@zukhruf/async 0.8.4 → 0.8.6

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
@@ -205,6 +205,9 @@ await delay(100, { clock: globalThis, signal });
205
205
  - When `signal` aborts, also before the call, the timer stops and `delay` rejects with the reason of the signal.
206
206
  - No listener stays on the signal after `delay` settles, so a signal that lives long can serve many waits.
207
207
  - With `ref: false`, the timer does not keep the process alive.
208
+ - A wait can be longer than one timer can hold. A timer of Node.js holds at most 2^31-1 ms, about 24.8 days, and fires a longer delay after 1 ms. `delay` then waits on a chain of timers of at most 2^31-1 ms, so a wait of 30 days lasts 30 days. Thus `poll`, `timeout` and the `interval` and `timeout` of `ChangeWatcher` can also be that long.
209
+
210
+ See [ADR 0009](./docs/adr/0009-a-wait-longer-than-one-timer-runs-on-a-chain-of-timers.md).
208
211
 
209
212
  ## Stop a wait after a time
210
213
 
@@ -222,6 +225,7 @@ const state = await readState(container, { signal: limit.signal });
222
225
  - A disposal stops the timer, and the signal then does not abort. `using` disposes the timeout at the end of the block.
223
226
  - 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.
224
227
  - To stop a wait at the timeout or at the signal of the caller, give `AbortSignal.any([signal, limit.signal])`.
228
+ - The time runs on `delay`, so a timeout can be longer than one timer can hold.
225
229
 
226
230
  See [ADR 0006](./docs/adr/0006-a-timeout-is-a-signal-on-the-clock-that-the-caller-gives.md).
227
231
 
package/dist/delay.d.ts CHANGED
@@ -15,6 +15,11 @@ export interface DelayOptions {
15
15
  * Waits `ms` milliseconds on the clock. When the signal aborts, also before
16
16
  * the call, the timer stops and the delay rejects with the reason of the
17
17
  * signal. No listener stays on the signal after the delay settles.
18
+ *
19
+ * A wait longer than one timer can hold runs as a chain of timers of at most
20
+ * 2^31-1 ms, so it lasts the full time. Each next timer gets the time that is
21
+ * left on `clock.performance.now()`, so a late timer does not make the wait
22
+ * longer.
18
23
  */
19
- export declare function delay(ms: number, { clock, signal, ref }: DelayOptions): Promise<void>;
24
+ export declare function delay(ms: number, options: DelayOptions): Promise<void>;
20
25
  //# sourceMappingURL=delay.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"delay.d.ts","sourceRoot":"","sources":["../src/delay.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,MAAM,WAAW,YAAY;IAC3B,2FAA2F;IAC3F,KAAK,EAAE,KAAK,CAAC;IACb,mFAAmF;IACnF,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC;;;;OAIG;IACH,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CACnB,EAAE,EAAE,MAAM,EACV,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,YAAY,GACnC,OAAO,CAAC,IAAI,CAAC,CAUf"}
1
+ {"version":3,"file":"delay.d.ts","sourceRoot":"","sources":["../src/delay.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,MAAM,WAAW,YAAY;IAC3B,2FAA2F;IAC3F,KAAK,EAAE,KAAK,CAAC;IACb,mFAAmF;IACnF,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC;;;;OAIG;IACH,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC3B;AAMD;;;;;;;;;GASG;AACH,wBAAsB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ5E"}
package/dist/delay.js CHANGED
@@ -1,11 +1,29 @@
1
1
  import { addAbortListener } from 'node:events';
2
2
  import { untilAborted } from "./until-aborted.js";
3
+ // The longest delay that one timer holds, about 24.8 days. Node.js fires a
4
+ // timer with a longer delay after 1 ms, and so does createClock().
5
+ const TIMER_MAX = 2 ** 31 - 1;
3
6
  /**
4
7
  * Waits `ms` milliseconds on the clock. When the signal aborts, also before
5
8
  * the call, the timer stops and the delay rejects with the reason of the
6
9
  * signal. No listener stays on the signal after the delay settles.
10
+ *
11
+ * A wait longer than one timer can hold runs as a chain of timers of at most
12
+ * 2^31-1 ms, so it lasts the full time. Each next timer gets the time that is
13
+ * left on `clock.performance.now()`, so a late timer does not make the wait
14
+ * longer.
7
15
  */
8
- export function delay(ms, { clock, signal, ref }) {
16
+ export async function delay(ms, options) {
17
+ const end = options.clock.performance.now() + ms;
18
+ let left = ms;
19
+ while (left > TIMER_MAX) {
20
+ await wait(TIMER_MAX, options);
21
+ left = end - options.clock.performance.now();
22
+ }
23
+ await wait(left, options);
24
+ }
25
+ // One timer.
26
+ function wait(ms, { clock, signal, ref }) {
9
27
  const { promise, resolve } = Promise.withResolvers();
10
28
  const timer = clock.setTimeout(resolve, ms);
11
29
  if (ref === false)
package/dist/delay.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"delay.js","sourceRoot":"","sources":["../src/delay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAelD;;;;GAIG;AACH,MAAM,UAAU,KAAK,CACnB,EAAU,EACV,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAgB;IAEpC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,aAAa,EAAQ,CAAC;IAC3D,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC5C,IAAI,GAAG,KAAK,KAAK;QAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM;QAAE,OAAO,OAAO,CAAC;IAC5B,qDAAqD;IACrD,MAAM,SAAS,GAAG,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5E,OAAO,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAChD,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAC5B,CAAC;AACJ,CAAC;AAED,SAAS,KAAK,CAAC,KAAc;IAC3B,IACE,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAO,IAAI,KAAK;QAChB,OAAO,KAAK,CAAC,KAAK,KAAK,UAAU,EACjC,CAAC;QACD,KAAK,CAAC,KAAK,EAAE,CAAC;IAChB,CAAC;AACH,CAAC"}
1
+ {"version":3,"file":"delay.js","sourceRoot":"","sources":["../src/delay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAelD,2EAA2E;AAC3E,mEAAmE;AACnE,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAE9B;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,EAAU,EAAE,OAAqB;IAC3D,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;IACjD,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,OAAO,IAAI,GAAG,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC/B,IAAI,GAAG,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;IAC/C,CAAC;IACD,MAAM,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC5B,CAAC;AAED,aAAa;AACb,SAAS,IAAI,CAAC,EAAU,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAgB;IAC5D,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,aAAa,EAAQ,CAAC;IAC3D,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC5C,IAAI,GAAG,KAAK,KAAK;QAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM;QAAE,OAAO,OAAO,CAAC;IAC5B,qDAAqD;IACrD,MAAM,SAAS,GAAG,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5E,OAAO,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAChD,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAC5B,CAAC;AACJ,CAAC;AAED,SAAS,KAAK,CAAC,KAAc;IAC3B,IACE,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAO,IAAI,KAAK;QAChB,OAAO,KAAK,CAAC,KAAK,KAAK,UAAU,EACjC,CAAC;QACD,KAAK,CAAC,KAAK,EAAE,CAAC;IAChB,CAAC;AACH,CAAC"}
package/dist/timeout.d.ts CHANGED
@@ -11,7 +11,8 @@ export interface Timeout extends Disposable {
11
11
  /**
12
12
  * Gives a signal that aborts after `ms` milliseconds on the clock, as
13
13
  * `AbortSignal.timeout` does on the real clock. Dispose the timeout when the
14
- * wait ends: `using limit = timeout(ms, { clock })`.
14
+ * wait ends: `using limit = timeout(ms, { clock })`. The time runs on `delay`,
15
+ * so a timeout longer than one timer can hold lasts the full time.
15
16
  */
16
17
  export declare function timeout(ms: number, { clock }: TimeoutOptions): Timeout;
17
18
  //# sourceMappingURL=timeout.d.ts.map
@@ -1 +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"}
1
+ {"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../src/timeout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,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;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,EAAE,cAAc,GAAG,OAAO,CAkBtE"}
package/dist/timeout.js CHANGED
@@ -1,16 +1,19 @@
1
+ import { delay } from "./delay.js";
1
2
  /**
2
3
  * Gives a signal that aborts after `ms` milliseconds on the clock, as
3
4
  * `AbortSignal.timeout` does on the real clock. Dispose the timeout when the
4
- * wait ends: `using limit = timeout(ms, { clock })`.
5
+ * wait ends: `using limit = timeout(ms, { clock })`. The time runs on `delay`,
6
+ * so a timeout longer than one timer can hold lasts the full time.
5
7
  */
6
8
  export function timeout(ms, { clock }) {
7
9
  const controller = new AbortController();
8
- const timer = clock.setTimeout(() => {
9
- controller.abort(new DOMException('The operation was aborted due to timeout', 'TimeoutError'));
10
- }, ms);
10
+ const disposal = new AbortController();
11
+ delay(ms, { clock, signal: disposal.signal }).then(() => controller.abort(new DOMException('The operation was aborted due to timeout', 'TimeoutError')),
12
+ // The disposal stopped the wait: the signal never aborts.
13
+ () => { });
11
14
  return {
12
15
  signal: controller.signal,
13
- [Symbol.dispose]: () => clock.clearTimeout(timer),
16
+ [Symbol.dispose]: () => disposal.abort(),
14
17
  };
15
18
  }
16
19
  //# sourceMappingURL=timeout.js.map
@@ -1 +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"}
1
+ {"version":3,"file":"timeout.js","sourceRoot":"","sources":["../src/timeout.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAanC;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,EAAU,EAAE,EAAE,KAAK,EAAkB;IAC3D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,QAAQ,GAAG,IAAI,eAAe,EAAE,CAAC;IACvC,KAAK,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAChD,GAAG,EAAE,CACH,UAAU,CAAC,KAAK,CACd,IAAI,YAAY,CACd,0CAA0C,EAC1C,cAAc,CACf,CACF;IACH,0DAA0D;IAC1D,GAAG,EAAE,GAAE,CAAC,CACT,CAAC;IACF,OAAO;QACL,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE;KACzC,CAAC;AACJ,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zukhruf/async",
3
- "version": "0.8.4",
3
+ "version": "0.8.6",
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": {