@zukhruf/async 0.3.52 → 0.3.54

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, and `poll` calls an attempt again until it gives a value. `@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, `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
 
@@ -103,3 +103,44 @@ poll(() => queue.take(), { interval: 100, signal, ref: false }).then(run);
103
103
  - `ref` changes only the wait between two attempts. An attempt that runs can keep the process alive.
104
104
 
105
105
  See [ADR 0003](./docs/adr/0003-the-election-and-the-file-lock-stores-poll-through-one-function.md).
106
+
107
+ ## Watch values for a change
108
+
109
+ 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.
110
+
111
+ ```ts
112
+ import { pollChanges } from '@zukhruf/async';
113
+
114
+ const reads = new Map([['messages', async () => version.current]]);
115
+ for await (const changed of pollChanges(reads, { interval: 1_000, signal })) {
116
+ if (changed.size > 0) await copyMessages();
117
+ }
118
+ ```
119
+
120
+ - The first check reads at once, and yields all keys: you have never seen the values.
121
+ - 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.
122
+ - 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.
123
+ - `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.
124
+ - An error from a read ends the loop with the same error.
125
+
126
+ ### Watch many values in one loop
127
+
128
+ 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.
129
+
130
+ ```ts
131
+ const reads = new Map([
132
+ ['library', () => library.version()],
133
+ ['annotations', () => annotations.version()],
134
+ ]);
135
+ for await (const changed of pollChanges(reads, { interval: 1_000, signal })) {
136
+ await copy(streams.filter((stream) => changed.has(stream.store)));
137
+ }
138
+ ```
139
+
140
+ ### Stop the watch
141
+
142
+ When `signal` aborts during the wait, `pollChanges` stops the timer, and the loop ends with no error. When the signal aborted before the call, the loop ends before the first read. An abort does not stop a read that runs.
143
+
144
+ To reject when the signal aborts, call `signal.throwIfAborted()` after the loop.
145
+
146
+ See [ADR 0004](./docs/adr/0004-a-change-watcher-yields-each-check-with-the-keys-that-changed.md).
package/dist/index.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  export { Latch } from './latch.ts';
2
2
  export { poll, type PollOptions } from './poll.ts';
3
+ export { pollChanges, type PollChangesOptions } from './poll-changes.ts';
3
4
  export { untilAborted } from './until-aborted.ts';
4
5
  //# 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,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,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,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"}
package/dist/index.js CHANGED
@@ -1,4 +1,5 @@
1
1
  export { Latch } from "./latch.js";
2
2
  export { poll } from "./poll.js";
3
+ export { pollChanges } from "./poll-changes.js";
3
4
  export { untilAborted } from "./until-aborted.js";
4
5
  //# 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,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAoB,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,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"}
@@ -0,0 +1,14 @@
1
+ export interface PollChangesOptions {
2
+ /** Milliseconds to wait after a check, from when the consumer asks for the next check. */
3
+ interval: number;
4
+ /** Stops the wait between two checks. The iteration then ends with no error. */
5
+ signal: AbortSignal;
6
+ }
7
+ /**
8
+ * Reads the value of each key at once, and yields all keys. Then, after each
9
+ * `interval`, reads each value again and yields the keys whose value is not
10
+ * `===` to the value of the previous check: an empty set when nothing changed.
11
+ * An error from a read rejects the iteration unchanged.
12
+ */
13
+ export declare function pollChanges<K>(reads: ReadonlyMap<K, () => Promise<unknown>>, { interval, signal }: PollChangesOptions): AsyncGenerator<ReadonlySet<K>, void, undefined>;
14
+ //# sourceMappingURL=poll-changes.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"poll-changes.d.ts","sourceRoot":"","sources":["../src/poll-changes.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,kBAAkB;IACjC,0FAA0F;IAC1F,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,MAAM,EAAE,WAAW,CAAC;CACrB;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,EAAE,kBAAkB,GACvC,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,CAsBjD"}
@@ -0,0 +1,37 @@
1
+ import { setTimeout as delay } from 'node:timers/promises';
2
+ import { untilAborted } from "./until-aborted.js";
3
+ /**
4
+ * Reads the value of each key at once, and yields all keys. Then, after each
5
+ * `interval`, reads each value again and yields the keys whose value is not
6
+ * `===` to the value of the previous check: an empty set when nothing changed.
7
+ * An error from a read rejects the iteration unchanged.
8
+ */
9
+ export async function* pollChanges(reads, { interval, signal }) {
10
+ if (signal.aborted)
11
+ return;
12
+ const seen = new Map();
13
+ for (const [key, read] of reads)
14
+ seen.set(key, await read());
15
+ yield new Set(reads.keys());
16
+ for (;;) {
17
+ try {
18
+ // delay's signal frees the timer; untilAborted ends a stopped event too.
19
+ await untilAborted(delay(interval, undefined, { signal }), signal);
20
+ }
21
+ catch (error) {
22
+ if (signal.aborted)
23
+ return;
24
+ throw error;
25
+ }
26
+ const changed = new Set();
27
+ for (const [key, read] of reads) {
28
+ const value = await read();
29
+ if (value === seen.get(key))
30
+ continue;
31
+ seen.set(key, value);
32
+ changed.add(key);
33
+ }
34
+ yield changed;
35
+ }
36
+ }
37
+ //# sourceMappingURL=poll-changes.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"poll-changes.js","sourceRoot":"","sources":["../src/poll-changes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AASlD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,WAAW,CAChC,KAA6C,EAC7C,EAAE,QAAQ,EAAE,MAAM,EAAsB;IAExC,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,yEAAyE;YACzE,MAAM,YAAY,CAAC,KAAK,CAAC,QAAQ,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;QACrE,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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zukhruf/async",
3
- "version": "0.3.52",
3
+ "version": "0.3.54",
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": {