@zukhruf/async 0.6.15 → 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 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 map: each key has a read, a function that gives the current value of the key. Each check reads each value one time, and yields the set of the keys whose value changed since the previous check.
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 reads = new Map([['messages', async () => version.current]]);
127
- const watch = pollChanges(reads, {
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
- - An error from a read ends the loop with the same error.
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
- A map with more keys reads each value at each check, one after the other. 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.
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 reads = new Map([
149
- ['library', () => library.version()],
150
- ['annotations', () => annotations.version()],
151
- ]);
152
- const watch = pollChanges(reads, {
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
- See [ADR 0004](./docs/adr/0004-a-change-watcher-yields-each-check-with-the-keys-that-changed.md).
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
@@ -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
@@ -1,4 +1,4 @@
1
- export { type Clock } from './clock.ts';
1
+ export { type Clock, type WallClock } from './clock.ts';
2
2
  export { delay, type DelayOptions } from './delay.ts';
3
3
  export { Latch } from './latch.ts';
4
4
  export { poll, type PollOptions } from './poll.ts';
@@ -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,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC1E,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,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,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"}
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"}
@@ -8,10 +8,12 @@ export interface PollChangesOptions {
8
8
  clock: Clock;
9
9
  }
10
10
  /**
11
- * Reads the value of each key at once, and yields all keys. Then, after each
12
- * `interval`, reads each value again and yields the keys whose value is not
13
- * `===` to the value of the previous check: an empty set when nothing changed.
14
- * An error from a read rejects the iteration unchanged.
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>(reads: ReadonlyMap<K, () => Promise<unknown>>, { interval, signal, clock }: PollChangesOptions): AsyncGenerator<ReadonlySet<K>, void, undefined>;
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;;;;;GAKG;AACH,wBAAuB,WAAW,CAAC,CAAC,EAClC,KAAK,EAAE,WAAW,CAAC,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,EAC7C,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,kBAAkB,GAC9C,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,CAqBjD"}
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"}
@@ -1,17 +1,17 @@
1
1
  import { delay } from "./delay.js";
2
2
  /**
3
- * Reads the value of each key at once, and yields all keys. Then, after each
4
- * `interval`, reads each value again and yields the keys whose value is not
5
- * `===` to the value of the previous check: an empty set when nothing changed.
6
- * An error from a read rejects the iteration unchanged.
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(reads, { interval, signal, clock }) {
10
+ export async function* pollChanges(read, { interval, signal, clock }) {
9
11
  if (signal.aborted)
10
12
  return;
11
- const seen = new Map();
12
- for (const [key, read] of reads)
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 changed = new Set();
25
- for (const [key, read] of reads) {
26
- const value = await read();
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
@@ -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;;;;;GAKG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,WAAW,CAChC,KAA6C,EAC7C,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAsB;IAE/C,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO;IAC3B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAc,CAAC;IACnC,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,KAAK;QAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC;IAC7D,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5B,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,OAAO,GAAG,IAAI,GAAG,EAAK,CAAC;QAC7B,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC;YAChC,MAAM,KAAK,GAAG,MAAM,IAAI,EAAE,CAAC;YAC3B,IAAI,KAAK,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YACtC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACrB,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;QACD,MAAM,OAAO,CAAC;IAChB,CAAC;AACH,CAAC"}
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.6.15",
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": {