@zukhruf/async 0.6.11 → 0.6.12

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.
Files changed (2) hide show
  1. package/README.md +70 -8
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -4,6 +4,8 @@ Helpers for code that waits for promises: `untilAborted` cancels a wait, `Latch`
4
4
 
5
5
  The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
6
6
 
7
+ > **Design for review.** The `clock` option of `poll` and `pollChanges` is not in the code yet ([ADR 0005](./docs/adr/0005-a-wait-runs-on-the-clock-that-the-caller-gives.md), backlog #3570). The released version does not take it.
8
+
7
9
  ## Cancel a wait
8
10
 
9
11
  A caller waits for a promise. The caller wants to stop the wait when a signal aborts, for example after a time limit, or when the user stops the program. `untilAborted` gives a promise that settles in the same way as the promise of the caller. When the signal aborts first, it rejects with the reason of the signal.
@@ -62,7 +64,11 @@ An attempt tries to get a value now, and it does not wait. For example, it tries
62
64
  import { poll } from '@zukhruf/async';
63
65
 
64
66
  // queue.take() gives the next job, or undefined when the queue is empty.
65
- const job = await poll(() => queue.take(), { interval: 100, signal });
67
+ const job = await poll(() => queue.take(), {
68
+ interval: 100,
69
+ signal,
70
+ clock: globalThis,
71
+ });
66
72
  ```
67
73
 
68
74
  - Only `undefined` means "no value yet". `null`, `0` and `false` are values.
@@ -71,19 +77,22 @@ const job = await poll(() => queue.take(), { interval: 100, signal });
71
77
 
72
78
  ### Stop at a deadline
73
79
 
74
- A deadline is a time from `performance.now()`, not a duration. After the deadline, an attempt that gives `undefined` resolves `poll` with `undefined`. An attempt that gives a value still resolves `poll` with the value.
80
+ A deadline is a time from `clock.performance.now()`, not a duration. Compute it from the clock that you give to `poll`. After the deadline, an attempt that gives `undefined` resolves `poll` with `undefined`. An attempt that gives a value still resolves `poll` with the value.
75
81
 
76
82
  ```ts
77
- const deadline = performance.now() + 5_000;
83
+ const clock = globalThis;
84
+ const deadline = clock.performance.now() + 5_000;
78
85
  const job = await poll(() => queue.take(), {
79
86
  interval: 100,
80
87
  signal: undefined,
88
+ clock,
81
89
  deadline,
82
90
  });
83
91
  // job is undefined when the queue stayed empty for 5 seconds.
84
92
  ```
85
93
 
86
- - The first attempt always occurs, also when the deadline is already in the past. Thus a deadline of `performance.now()` gives one attempt.
94
+ - The first attempt always occurs, also when the deadline is already in the past. Thus a deadline of `clock.performance.now()` gives one attempt.
95
+ - A deadline from another clock is wrong for the wait. The type can not find this mistake, because both are numbers.
87
96
  - One deadline can stop many polls. A campaign of `@zukhruf/election` uses one deadline for all its attempts.
88
97
  - Without a deadline, the type of the result has no `undefined`.
89
98
 
@@ -95,10 +104,15 @@ For such a poll, give `ref: false`. Then the wait does not keep the process aliv
95
104
 
96
105
  ```ts
97
106
  // The worker takes jobs, but it does not keep the process alive.
98
- poll(() => queue.take(), { interval: 100, signal, ref: false }).then(run);
107
+ poll(() => queue.take(), {
108
+ interval: 100,
109
+ signal,
110
+ clock: globalThis,
111
+ ref: false,
112
+ }).then(run);
99
113
  ```
100
114
 
101
- - `ref` is the `ref` option of the Node.js timer (`setTimeout` of `node:timers/promises`). `poll` gives it to the timer unchanged.
115
+ - With `ref: false`, `poll` calls `unref()` on the timer that `clock.setTimeout` gives.
102
116
  - Without `ref`, Node.js keeps its default: the wait keeps the process alive.
103
117
  - `ref` changes only the wait between two attempts. An attempt that runs can keep the process alive.
104
118
 
@@ -112,7 +126,12 @@ A value can change while you are not looking, for example the `data_version` of
112
126
  import { pollChanges } from '@zukhruf/async';
113
127
 
114
128
  const reads = new Map([['messages', async () => version.current]]);
115
- for await (const changed of pollChanges(reads, { interval: 1_000, signal })) {
129
+ const watch = pollChanges(reads, {
130
+ interval: 1_000,
131
+ signal,
132
+ clock: globalThis,
133
+ });
134
+ for await (const changed of watch) {
116
135
  if (changed.size > 0) await copyMessages();
117
136
  }
118
137
  ```
@@ -132,7 +151,12 @@ const reads = new Map([
132
151
  ['library', () => library.version()],
133
152
  ['annotations', () => annotations.version()],
134
153
  ]);
135
- for await (const changed of pollChanges(reads, { interval: 1_000, signal })) {
154
+ const watch = pollChanges(reads, {
155
+ interval: 1_000,
156
+ signal,
157
+ clock: globalThis,
158
+ });
159
+ for await (const changed of watch) {
136
160
  await copy(streams.filter((stream) => changed.has(stream.store)));
137
161
  }
138
162
  ```
@@ -144,3 +168,41 @@ When `signal` aborts during the wait, `pollChanges` stops the timer, and the loo
144
168
  To reject when the signal aborts, call `signal.throwIfAborted()` after the loop.
145
169
 
146
170
  See [ADR 0004](./docs/adr/0004-a-change-watcher-yields-each-check-with-the-keys-that-changed.md).
171
+
172
+ ## Run a wait on a clock
173
+
174
+ 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.
175
+
176
+ ```ts
177
+ import assert from 'node:assert/strict';
178
+ import { test } from 'node:test';
179
+
180
+ import { createClock } from '@sinonjs/fake-timers';
181
+
182
+ import { poll } from '@zukhruf/async';
183
+
184
+ test('a job that comes during the second wait', async (t) => {
185
+ const clock = createClock();
186
+ const jobs: string[] = [];
187
+ const job = poll(async () => jobs.shift(), {
188
+ interval: 1_000,
189
+ signal: undefined,
190
+ clock,
191
+ });
192
+
193
+ // The first attempt gave no job, so the poll waits on the clock.
194
+ await t.waitFor(() => assert.equal(clock.countTimers(), 1));
195
+ jobs.push('build');
196
+ await clock.tickAsync(1_000);
197
+
198
+ assert.equal(await job, 'build');
199
+ });
200
+ ```
201
+
202
+ - `await clock.tickAsync(ms)` moves the time, and fires each timer that is due, in the order of their times.
203
+ - `t.waitFor(() => assert.equal(clock.countTimers(), 1))` waits until the code waits on the clock again. Use it after work that is real, for example a read of a file, before you move the time.
204
+ - `clock.setSystemTime(time)` moves the wall clock and does not move `performance.now()`. A deadline does not move with the wall clock.
205
+ - `createClock()` does not replace a global, so tests that run at the same time do not see each other's clock.
206
+ - The type of the option is `Clock`. It has only the members that the wait calls: `setTimeout`, `clearTimeout` and `performance.now()`. `globalThis` and `createClock()` both have them.
207
+
208
+ See [ADR 0005](./docs/adr/0005-a-wait-runs-on-the-clock-that-the-caller-gives.md).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zukhruf/async",
3
- "version": "0.6.11",
3
+ "version": "0.6.12",
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": {