@zukhruf/async 0.6.16 → 0.7.0
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 +31 -11
- package/dist/clock.d.ts +11 -0
- package/dist/clock.d.ts.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/poll-changes.d.ts +7 -5
- package/dist/poll-changes.d.ts.map +1 -1
- package/dist/poll-changes.js +23 -18
- package/dist/poll-changes.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -118,13 +118,13 @@ See [ADR 0003](./docs/adr/0003-the-election-and-the-file-lock-stores-poll-throug
|
|
|
118
118
|
|
|
119
119
|
## Watch values for a change
|
|
120
120
|
|
|
121
|
-
A value can change while you are not looking, for example the `data_version` of a SQLite file. To see the changes, read the value again and again. `pollChanges` does this for you. Give it a
|
|
121
|
+
A value can change while you are not looking, for example the `data_version` of a SQLite file. To see the changes, read the value again and again. `pollChanges` does this for you. Give it a read: a function that gives a map from each key to its current value. Each check calls the read one time, and yields the set of the keys whose value changed since the previous check.
|
|
122
122
|
|
|
123
123
|
```ts
|
|
124
124
|
import { pollChanges } from '@zukhruf/async';
|
|
125
125
|
|
|
126
|
-
const
|
|
127
|
-
const watch = pollChanges(
|
|
126
|
+
const read = async () => new Map([['messages', version.current]]);
|
|
127
|
+
const watch = pollChanges(read, {
|
|
128
128
|
interval: 1_000,
|
|
129
129
|
signal,
|
|
130
130
|
clock: globalThis,
|
|
@@ -138,18 +138,20 @@ for await (const changed of watch) {
|
|
|
138
138
|
- After each check, `pollChanges` waits `interval` milliseconds after you ask for the next check. A slow loop body thus never gets two checks with no wait between them.
|
|
139
139
|
- A check that found no change yields an empty set. Skip it when you need only the changes. Use it when you must know that a check occurred, for example to record that a value is still current.
|
|
140
140
|
- `pollChanges` compares each value with `===` to its value at the previous check. Give values that `===` can compare, for example a version number or a string.
|
|
141
|
-
-
|
|
141
|
+
- A key that only one of two checks gave also changed: it was added or removed. For example, a table that was dropped since the previous check is in the set.
|
|
142
|
+
- An error from the read ends the loop with the same error.
|
|
142
143
|
|
|
143
144
|
### Watch many values in one loop
|
|
144
145
|
|
|
145
|
-
|
|
146
|
+
The map of a read can have many keys. The set names only the keys that changed. Thus one loop can watch many stores, and give the work only for the stores that changed. The read decides how it gets the values: one after the other, at the same time, or all from one query.
|
|
146
147
|
|
|
147
148
|
```ts
|
|
148
|
-
const
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
]
|
|
152
|
-
|
|
149
|
+
const read = async () =>
|
|
150
|
+
new Map([
|
|
151
|
+
['library', await library.version()],
|
|
152
|
+
['annotations', await annotations.version()],
|
|
153
|
+
]);
|
|
154
|
+
const watch = pollChanges(read, {
|
|
153
155
|
interval: 1_000,
|
|
154
156
|
signal,
|
|
155
157
|
clock: globalThis,
|
|
@@ -165,7 +167,9 @@ When `signal` aborts during the wait, `pollChanges` stops the timer, and the loo
|
|
|
165
167
|
|
|
166
168
|
To reject when the signal aborts, call `signal.throwIfAborted()` after the loop.
|
|
167
169
|
|
|
168
|
-
|
|
170
|
+
When one query gives the values of many keys, for example a count for each table of a database, the read runs the query one time and gives a map with all of them. Nothing of one check stays for the next check.
|
|
171
|
+
|
|
172
|
+
See [ADR 0004](./docs/adr/0004-a-change-watcher-yields-each-check-with-the-keys-that-changed.md) and [ADR 0007](./docs/adr/0007-a-check-is-one-read-that-gives-the-value-of-each-key.md).
|
|
169
173
|
|
|
170
174
|
## Wait a fixed time
|
|
171
175
|
|
|
@@ -237,4 +241,20 @@ test('a job that comes during the second wait', async (t) => {
|
|
|
237
241
|
- `createClock()` does not replace a global, so tests that run at the same time do not see each other's clock.
|
|
238
242
|
- 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.
|
|
239
243
|
|
|
244
|
+
### Read the wall time from the clock
|
|
245
|
+
|
|
246
|
+
A library that also reads the wall time, for example the date of a result, takes a `WallClock`. A `WallClock` is a `Clock` that also has `Date.now()`. `globalThis` and `createClock()` both have it. In a test, `clock.setSystemTime(time)` sets the wall time.
|
|
247
|
+
|
|
248
|
+
```ts
|
|
249
|
+
import type { WallClock } from '@zukhruf/async';
|
|
250
|
+
|
|
251
|
+
function stamp(result: string, clock: WallClock) {
|
|
252
|
+
return { result, date: new Date(clock.Date.now()).toISOString() };
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
stamp('passed', globalThis);
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
The wall time can jump, for example when the computer sleeps. `performance.now()` does not jump. Thus a deadline uses `performance.now()`, and never the wall time.
|
|
259
|
+
|
|
240
260
|
See [ADR 0005](./docs/adr/0005-a-wait-runs-on-the-clock-that-the-caller-gives.md).
|
package/dist/clock.d.ts
CHANGED
|
@@ -13,4 +13,15 @@ export interface Clock {
|
|
|
13
13
|
now(): number;
|
|
14
14
|
};
|
|
15
15
|
}
|
|
16
|
+
/**
|
|
17
|
+
* A clock that also gives the wall time, from `Date.now()`. Production gives
|
|
18
|
+
* `globalThis`; a test gives `createClock()` and sets the wall time with
|
|
19
|
+
* `clock.setSystemTime(time)`. The wall time can jump, so a deadline uses
|
|
20
|
+
* `performance.now()`.
|
|
21
|
+
*/
|
|
22
|
+
export interface WallClock extends Clock {
|
|
23
|
+
Date: {
|
|
24
|
+
now(): number;
|
|
25
|
+
};
|
|
26
|
+
}
|
|
16
27
|
//# sourceMappingURL=clock.d.ts.map
|
package/dist/clock.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,KAAK;IACpB,UAAU,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACtD,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,WAAW,EAAE;QAAE,GAAG,IAAI,MAAM,CAAA;KAAE,CAAC;CAChC"}
|
|
1
|
+
{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,KAAK;IACpB,UAAU,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACtD,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,WAAW,EAAE;QAAE,GAAG,IAAI,MAAM,CAAA;KAAE,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAU,SAAQ,KAAK;IACtC,IAAI,EAAE;QAAE,GAAG,IAAI,MAAM,CAAA;KAAE,CAAC;CACzB"}
|
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,MAAM,YAAY,CAAC;
|
|
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,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.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,
|
|
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,WAAW,EAA2B,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,OAAO,EAAqC,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
|
package/dist/poll-changes.d.ts
CHANGED
|
@@ -8,10 +8,12 @@ export interface PollChangesOptions {
|
|
|
8
8
|
clock: Clock;
|
|
9
9
|
}
|
|
10
10
|
/**
|
|
11
|
-
*
|
|
12
|
-
* `interval`,
|
|
13
|
-
*
|
|
14
|
-
*
|
|
11
|
+
* Calls `read` at once, and yields all the keys it gave. Then, after each
|
|
12
|
+
* `interval`, calls `read` again and yields the keys whose value is not `===`
|
|
13
|
+
* to the value of the previous check, and the keys that only one of the two
|
|
14
|
+
* checks gave: an empty set when nothing changed. One call of `read` gives
|
|
15
|
+
* the values of all keys of a check. An error from `read` rejects the
|
|
16
|
+
* iteration unchanged.
|
|
15
17
|
*/
|
|
16
|
-
export declare function pollChanges<K>(
|
|
18
|
+
export declare function pollChanges<K>(read: () => Promise<ReadonlyMap<K, unknown>>, { interval, signal, clock }: PollChangesOptions): AsyncGenerator<ReadonlySet<K>, void, undefined>;
|
|
17
19
|
//# sourceMappingURL=poll-changes.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"poll-changes.d.ts","sourceRoot":"","sources":["../src/poll-changes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,MAAM,WAAW,kBAAkB;IACjC,0FAA0F;IAC1F,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,MAAM,EAAE,WAAW,CAAC;IACpB,2FAA2F;IAC3F,KAAK,EAAE,KAAK,CAAC;CACd;AAED
|
|
1
|
+
{"version":3,"file":"poll-changes.d.ts","sourceRoot":"","sources":["../src/poll-changes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,MAAM,WAAW,kBAAkB;IACjC,0FAA0F;IAC1F,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,MAAM,EAAE,WAAW,CAAC;IACpB,2FAA2F;IAC3F,KAAK,EAAE,KAAK,CAAC;CACd;AAED;;;;;;;GAOG;AACH,wBAAuB,WAAW,CAAC,CAAC,EAClC,IAAI,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,EAC5C,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,kBAAkB,GAC9C,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,CAejD"}
|
package/dist/poll-changes.js
CHANGED
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
import { delay } from "./delay.js";
|
|
2
2
|
/**
|
|
3
|
-
*
|
|
4
|
-
* `interval`,
|
|
5
|
-
*
|
|
6
|
-
*
|
|
3
|
+
* Calls `read` at once, and yields all the keys it gave. Then, after each
|
|
4
|
+
* `interval`, calls `read` again and yields the keys whose value is not `===`
|
|
5
|
+
* to the value of the previous check, and the keys that only one of the two
|
|
6
|
+
* checks gave: an empty set when nothing changed. One call of `read` gives
|
|
7
|
+
* the values of all keys of a check. An error from `read` rejects the
|
|
8
|
+
* iteration unchanged.
|
|
7
9
|
*/
|
|
8
|
-
export async function* pollChanges(
|
|
10
|
+
export async function* pollChanges(read, { interval, signal, clock }) {
|
|
9
11
|
if (signal.aborted)
|
|
10
12
|
return;
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
seen.set(key, await read());
|
|
14
|
-
yield new Set(reads.keys());
|
|
13
|
+
let previous = await read();
|
|
14
|
+
yield new Set(previous.keys());
|
|
15
15
|
for (;;) {
|
|
16
16
|
try {
|
|
17
17
|
await delay(interval, { clock, signal });
|
|
@@ -21,15 +21,20 @@ export async function* pollChanges(reads, { interval, signal, clock }) {
|
|
|
21
21
|
return;
|
|
22
22
|
throw error;
|
|
23
23
|
}
|
|
24
|
-
const
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
if (value === seen.get(key))
|
|
28
|
-
continue;
|
|
29
|
-
seen.set(key, value);
|
|
30
|
-
changed.add(key);
|
|
31
|
-
}
|
|
32
|
-
yield changed;
|
|
24
|
+
const values = await read();
|
|
25
|
+
yield changedKeys(previous, values);
|
|
26
|
+
previous = values;
|
|
33
27
|
}
|
|
34
28
|
}
|
|
29
|
+
// The keys whose value differs between two checks, or that only one gave.
|
|
30
|
+
function changedKeys(previous, values) {
|
|
31
|
+
const changed = new Set();
|
|
32
|
+
for (const [key, value] of values)
|
|
33
|
+
if (!previous.has(key) || previous.get(key) !== value)
|
|
34
|
+
changed.add(key);
|
|
35
|
+
for (const key of previous.keys())
|
|
36
|
+
if (!values.has(key))
|
|
37
|
+
changed.add(key);
|
|
38
|
+
return changed;
|
|
39
|
+
}
|
|
35
40
|
//# sourceMappingURL=poll-changes.js.map
|
package/dist/poll-changes.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"poll-changes.js","sourceRoot":"","sources":["../src/poll-changes.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAWnC
|
|
1
|
+
{"version":3,"file":"poll-changes.js","sourceRoot":"","sources":["../src/poll-changes.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAWnC;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,WAAW,CAChC,IAA4C,EAC5C,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAsB;IAE/C,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO;IAC3B,IAAI,QAAQ,GAAG,MAAM,IAAI,EAAE,CAAC;IAC5B,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/B,SAAS,CAAC;QACR,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;QAC3C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,MAAM,CAAC,OAAO;gBAAE,OAAO;YAC3B,MAAM,KAAK,CAAC;QACd,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,IAAI,EAAE,CAAC;QAC5B,MAAM,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACpC,QAAQ,GAAG,MAAM,CAAC;IACpB,CAAC;AACH,CAAC;AAED,0EAA0E;AAC1E,SAAS,WAAW,CAClB,QAAiC,EACjC,MAA+B;IAE/B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAK,CAAC;IAC7B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM;QAC/B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK;YAAE,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC1E,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,IAAI,EAAE;QAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC1E,OAAO,OAAO,CAAC;AACjB,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zukhruf/async",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0",
|
|
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": {
|