@zukhruf/async 0.7.0 → 0.8.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 +53 -33
- package/dist/change-watcher.d.ts +33 -0
- package/dist/change-watcher.d.ts.map +1 -0
- package/dist/change-watcher.js +85 -0
- package/dist/change-watcher.js.map +1 -0
- package/dist/check.d.ts +7 -0
- package/dist/check.d.ts.map +1 -0
- package/dist/check.js +15 -0
- package/dist/check.js.map +1 -0
- package/dist/collector.d.ts +9 -0
- package/dist/collector.d.ts.map +1 -0
- package/dist/collector.js +28 -0
- package/dist/collector.js.map +1 -0
- package/dist/gauge.d.ts +9 -0
- package/dist/gauge.d.ts.map +1 -0
- package/dist/gauge.js +10 -0
- package/dist/gauge.js.map +1 -0
- package/dist/group.d.ts +8 -0
- package/dist/group.d.ts.map +1 -0
- package/dist/group.js +15 -0
- package/dist/group.js.map +1 -0
- package/dist/index.d.ts +6 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +6 -1
- package/dist/index.js.map +1 -1
- package/dist/milliseconds.d.ts +2 -0
- package/dist/milliseconds.d.ts.map +1 -0
- package/dist/milliseconds.js +9 -0
- package/dist/milliseconds.js.map +1 -0
- package/dist/once.d.ts +6 -0
- package/dist/once.d.ts.map +1 -0
- package/dist/once.js +23 -0
- package/dist/once.js.map +1 -0
- package/dist/period.d.ts +8 -0
- package/dist/period.d.ts.map +1 -0
- package/dist/period.js +16 -0
- package/dist/period.js.map +1 -0
- package/package.json +1 -1
- package/dist/poll-changes.d.ts +0 -19
- package/dist/poll-changes.d.ts.map +0 -1
- package/dist/poll-changes.js +0 -40
- package/dist/poll-changes.js.map +0 -1
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, `delay` waits a fixed time on a clock, `timeout` stops a wait after a time on a clock, `poll` calls an attempt again until it gives a value, and `
|
|
3
|
+
Helpers for code that waits for promises: `untilAborted` cancels a wait, `Latch` holds callers until something happened, `delay` waits a fixed time on a clock, `timeout` stops a wait after a time on a clock, `poll` calls an attempt again until it gives a value, and `ChangeWatcher` reads gauges 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
|
|
|
@@ -118,58 +118,78 @@ 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. `
|
|
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. `ChangeWatcher` does this for you. Give it gauges: a gauge is a value that the watcher reads at each check. Each check reads each gauge one time, all at the same time, and gives the outcome of each gauge: `changed`, `unchanged` or `failed`.
|
|
122
122
|
|
|
123
123
|
```ts
|
|
124
|
-
import {
|
|
124
|
+
import { ChangeWatcher, Gauge } from '@zukhruf/async';
|
|
125
125
|
|
|
126
|
-
|
|
127
|
-
|
|
126
|
+
class MessagesVersion extends Gauge<number> {
|
|
127
|
+
protected async read() {
|
|
128
|
+
return version.current;
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
const messages = new MessagesVersion();
|
|
133
|
+
const watcher = new ChangeWatcher([messages], {
|
|
128
134
|
interval: 1_000,
|
|
129
|
-
|
|
135
|
+
timeout: 1_000,
|
|
130
136
|
clock: globalThis,
|
|
131
137
|
});
|
|
132
|
-
for await (const
|
|
133
|
-
if (
|
|
138
|
+
for await (const outcomes of watcher.watch(signal)) {
|
|
139
|
+
if (outcomes.get(messages)?.state === 'changed') await copyMessages();
|
|
134
140
|
}
|
|
135
141
|
```
|
|
136
142
|
|
|
137
|
-
- The first check reads at once
|
|
138
|
-
- After each check,
|
|
139
|
-
- A check that found no change
|
|
140
|
-
- `
|
|
141
|
-
|
|
142
|
-
|
|
143
|
+
- The first check reads at once. Each gauge that it can read changed: you have never seen its value.
|
|
144
|
+
- After each check, the watcher waits `interval` milliseconds after you ask for the next check. A slow loop body thus never gets two checks with no wait between them.
|
|
145
|
+
- A check that found no change gives each gauge `unchanged`. Use it when you must know that a check occurred, for example to record that a value is still current.
|
|
146
|
+
- A value is a primitive (a string, a number, a bigint, a boolean, `null` or `undefined`) or a list of values. The watcher compares it with `Object.is` to its value at the previous check, member by member for a list. Thus `NaN` does not change at each check.
|
|
147
|
+
|
|
148
|
+
### A failed read fails only its gauge
|
|
149
|
+
|
|
150
|
+
When the read of a gauge fails, its outcome is `failed`, with the error. The other gauges of the check go on. A failed gauge keeps its last value: after it recovers, it changed only when its value differs from that last value. You decide what a failure means, for example to stop your loop.
|
|
143
151
|
|
|
144
|
-
|
|
152
|
+
The reads of one check have `timeout` milliseconds. A read that takes longer fails with a `TimeoutError`, also a read that never answers. Give `check.signal` to the I/O of a read, so that the read stops too.
|
|
145
153
|
|
|
146
|
-
|
|
154
|
+
### Watch many values
|
|
155
|
+
|
|
156
|
+
Give the watcher many gauges. It reads each one at each check, and gives an outcome for each.
|
|
157
|
+
|
|
158
|
+
When one read gives the values of many keys, for example one query that gives a count for each table, write a `Collector`. Its `collect` runs one time in each check, however many of its keys you watch. `collector.gauge(key)` gives the gauge of one key. Its value is `undefined` when the read did not give the key, so a key that appears or disappears changed.
|
|
147
159
|
|
|
148
160
|
```ts
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
]);
|
|
154
|
-
const watch = pollChanges(read, {
|
|
155
|
-
interval: 1_000,
|
|
156
|
-
signal,
|
|
157
|
-
clock: globalThis,
|
|
158
|
-
});
|
|
159
|
-
for await (const changed of watch) {
|
|
160
|
-
await copy(streams.filter((stream) => changed.has(stream.store)));
|
|
161
|
+
class RowCounts extends Collector<string> {
|
|
162
|
+
protected collect(check: Check) {
|
|
163
|
+
return session.rowCounts(check.signal);
|
|
164
|
+
}
|
|
161
165
|
}
|
|
166
|
+
|
|
167
|
+
const rows = new RowCounts();
|
|
168
|
+
const notes = rows.gauge('[dbo].[notes]');
|
|
169
|
+
const orders = rows.gauge('[dbo].[orders]');
|
|
170
|
+
const watcher = new ChangeWatcher([notes, orders], {
|
|
171
|
+
interval: 30_000,
|
|
172
|
+
timeout: 10_000,
|
|
173
|
+
clock,
|
|
174
|
+
});
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
A `Group` is a gauge made of gauges. It changed when one of its members changed, and it failed when one of its members failed. Watch one group for each thing that you refresh, for example one table and the gauges that see its changes.
|
|
178
|
+
|
|
179
|
+
A `Period` is the count of whole periods since the watch started. Put it in a group to read again on a schedule, also when no other gauge saw a change:
|
|
180
|
+
|
|
181
|
+
```ts
|
|
182
|
+
const hour = new Period(60 * 60_000);
|
|
183
|
+
const table = new Group([rows.gauge('[dbo].[notes]'), hour]);
|
|
162
184
|
```
|
|
163
185
|
|
|
164
186
|
### Stop the watch
|
|
165
187
|
|
|
166
|
-
When `signal` aborts during the wait,
|
|
188
|
+
When `signal` aborts, the loop ends with no error: during the wait, during the reads, and also while your loop body holds a check. The timer stops. When the signal aborted before the call, the loop ends before the first read. An abort does not stop a read that runs, but `check.signal` tells it.
|
|
167
189
|
|
|
168
190
|
To reject when the signal aborts, call `signal.throwIfAborted()` after the loop.
|
|
169
191
|
|
|
170
|
-
|
|
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).
|
|
192
|
+
See [ADR 0004](./docs/adr/0004-a-change-watcher-yields-each-check-with-the-keys-that-changed.md) and [ADR 0008](./docs/adr/0008-a-change-watcher-reads-gauges.md).
|
|
173
193
|
|
|
174
194
|
## Wait a fixed time
|
|
175
195
|
|
|
@@ -207,7 +227,7 @@ See [ADR 0006](./docs/adr/0006-a-timeout-is-a-signal-on-the-clock-that-the-calle
|
|
|
207
227
|
|
|
208
228
|
## Run a wait on a clock
|
|
209
229
|
|
|
210
|
-
Each wait of `poll` and `
|
|
230
|
+
Each wait of `poll` and `ChangeWatcher` 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.
|
|
211
231
|
|
|
212
232
|
```ts
|
|
213
233
|
import assert from 'node:assert/strict';
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import type { WallClock } from './clock.ts';
|
|
2
|
+
import type { Gauge } from './gauge.ts';
|
|
3
|
+
export type Outcome = {
|
|
4
|
+
readonly state: 'changed';
|
|
5
|
+
} | {
|
|
6
|
+
readonly state: 'unchanged';
|
|
7
|
+
} | {
|
|
8
|
+
readonly state: 'failed';
|
|
9
|
+
readonly error: unknown;
|
|
10
|
+
};
|
|
11
|
+
export interface ChangeWatcherOptions {
|
|
12
|
+
/** Milliseconds to wait after a check, from when the consumer asks for the next check. */
|
|
13
|
+
interval: number;
|
|
14
|
+
/** Milliseconds that the reads of one check can take. A read that takes longer fails for that check. */
|
|
15
|
+
timeout: number;
|
|
16
|
+
/** The clock that the watch runs on: `globalThis` in production, a fake clock in a test. */
|
|
17
|
+
clock: WallClock;
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Checks its gauges again and again. The first check reads at once; each
|
|
21
|
+
* later check waits `interval` from when the consumer asks for it. Each check
|
|
22
|
+
* reads each gauge one time, all at the same time, and yields the outcome of
|
|
23
|
+
* each gauge: changed, unchanged, or failed. At the first check, each gauge
|
|
24
|
+
* that it could read changed. A check with no change still yields. An abort
|
|
25
|
+
* ends the iteration with no error, also while the consumer holds a check or
|
|
26
|
+
* while the reads run.
|
|
27
|
+
*/
|
|
28
|
+
export declare class ChangeWatcher<G extends Gauge> {
|
|
29
|
+
#private;
|
|
30
|
+
constructor(gauges: Iterable<G>, options: ChangeWatcherOptions);
|
|
31
|
+
watch(signal: AbortSignal): AsyncGenerator<ReadonlyMap<G, Outcome>, void, undefined>;
|
|
32
|
+
}
|
|
33
|
+
//# sourceMappingURL=change-watcher.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"change-watcher.d.ts","sourceRoot":"","sources":["../src/change-watcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,KAAK,EAAE,KAAK,EAAS,MAAM,YAAY,CAAC;AAO/C,MAAM,MAAM,OAAO,GACf;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1D,MAAM,WAAW,oBAAoB;IACnC,0FAA0F;IAC1F,QAAQ,EAAE,MAAM,CAAC;IACjB,wGAAwG;IACxG,OAAO,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,KAAK,EAAE,SAAS,CAAC;CAClB;AAUD;;;;;;;;GAQG;AACH,qBAAa,aAAa,CAAC,CAAC,SAAS,KAAK;;gBAM5B,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,oBAAoB;IAOvD,KAAK,CACV,MAAM,EAAE,WAAW,GAClB,cAAc,CAAC,WAAW,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC;CA2D5D"}
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import { Check } from "./check.js";
|
|
2
|
+
import { delay } from "./delay.js";
|
|
3
|
+
import { milliseconds } from "./milliseconds.js";
|
|
4
|
+
import { timeout } from "./timeout.js";
|
|
5
|
+
import { untilAborted } from "./until-aborted.js";
|
|
6
|
+
// Two values are the same when Object.is says so, member by member for a
|
|
7
|
+
// list. Thus NaN is the same as NaN.
|
|
8
|
+
function same(a, b) {
|
|
9
|
+
if (Array.isArray(a) && Array.isArray(b))
|
|
10
|
+
return a.length === b.length && a.every((value, i) => same(value, b[i]));
|
|
11
|
+
return Object.is(a, b);
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Checks its gauges again and again. The first check reads at once; each
|
|
15
|
+
* later check waits `interval` from when the consumer asks for it. Each check
|
|
16
|
+
* reads each gauge one time, all at the same time, and yields the outcome of
|
|
17
|
+
* each gauge: changed, unchanged, or failed. At the first check, each gauge
|
|
18
|
+
* that it could read changed. A check with no change still yields. An abort
|
|
19
|
+
* ends the iteration with no error, also while the consumer holds a check or
|
|
20
|
+
* while the reads run.
|
|
21
|
+
*/
|
|
22
|
+
export class ChangeWatcher {
|
|
23
|
+
#gauges;
|
|
24
|
+
#interval;
|
|
25
|
+
#timeout;
|
|
26
|
+
#clock;
|
|
27
|
+
constructor(gauges, options) {
|
|
28
|
+
this.#gauges = [...gauges];
|
|
29
|
+
this.#interval = milliseconds('The interval', options.interval);
|
|
30
|
+
this.#timeout = milliseconds('The timeout', options.timeout);
|
|
31
|
+
this.#clock = options.clock;
|
|
32
|
+
}
|
|
33
|
+
async *watch(signal) {
|
|
34
|
+
const watchStarted = this.#clock.Date.now();
|
|
35
|
+
const last = new Map();
|
|
36
|
+
for (let first = true;; first = false) {
|
|
37
|
+
if (signal.aborted)
|
|
38
|
+
return;
|
|
39
|
+
if (!first)
|
|
40
|
+
try {
|
|
41
|
+
await delay(this.#interval, { clock: this.#clock, signal });
|
|
42
|
+
}
|
|
43
|
+
catch (error) {
|
|
44
|
+
if (signal.aborted)
|
|
45
|
+
return;
|
|
46
|
+
throw error;
|
|
47
|
+
}
|
|
48
|
+
const outcomes = await this.#check(watchStarted, last, signal);
|
|
49
|
+
if (signal.aborted)
|
|
50
|
+
return;
|
|
51
|
+
yield outcomes;
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
// One check. Its timer ends with the check, before the consumer gets it.
|
|
55
|
+
async #check(watchStarted, last, signal) {
|
|
56
|
+
using limit = timeout(this.#timeout, { clock: this.#clock });
|
|
57
|
+
const check = new Check(watchStarted, this.#clock.Date.now(), AbortSignal.any([signal, limit.signal]));
|
|
58
|
+
// A read that ignores the signal still ends for this check at the timeout.
|
|
59
|
+
const reads = await Promise.all(this.#gauges.map(async (gauge) => {
|
|
60
|
+
try {
|
|
61
|
+
const value = await untilAborted(gauge.value(check), check.signal);
|
|
62
|
+
return { gauge, read: true, value };
|
|
63
|
+
}
|
|
64
|
+
catch (error) {
|
|
65
|
+
return { gauge, read: false, error };
|
|
66
|
+
}
|
|
67
|
+
}));
|
|
68
|
+
const outcomes = new Map();
|
|
69
|
+
for (const result of reads) {
|
|
70
|
+
if (!result.read) {
|
|
71
|
+
outcomes.set(result.gauge, { state: 'failed', error: result.error });
|
|
72
|
+
continue;
|
|
73
|
+
}
|
|
74
|
+
if (last.has(result.gauge) &&
|
|
75
|
+
same(last.get(result.gauge), result.value)) {
|
|
76
|
+
outcomes.set(result.gauge, { state: 'unchanged' });
|
|
77
|
+
continue;
|
|
78
|
+
}
|
|
79
|
+
last.set(result.gauge, result.value);
|
|
80
|
+
outcomes.set(result.gauge, { state: 'changed' });
|
|
81
|
+
}
|
|
82
|
+
return outcomes;
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
//# sourceMappingURL=change-watcher.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"change-watcher.js","sourceRoot":"","sources":["../src/change-watcher.ts"],"names":[],"mappings":"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"}
|
package/dist/check.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAIA,qBAAa,KAAK;IAChB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;gBAEjB,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW;CAKnE"}
|
package/dist/check.js
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
// One round of a change watch: when the watch started and when the check
|
|
2
|
+
// began, on the clock of the watch, and a signal that aborts when the watch
|
|
3
|
+
// stops or the check passes its timeout. A read that waits gives the signal
|
|
4
|
+
// to its I/O.
|
|
5
|
+
export class Check {
|
|
6
|
+
watchStarted;
|
|
7
|
+
now;
|
|
8
|
+
signal;
|
|
9
|
+
constructor(watchStarted, now, signal) {
|
|
10
|
+
this.watchStarted = watchStarted;
|
|
11
|
+
this.now = now;
|
|
12
|
+
this.signal = signal;
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
//# sourceMappingURL=check.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"check.js","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,4EAA4E;AAC5E,4EAA4E;AAC5E,cAAc;AACd,MAAM,OAAO,KAAK;IACP,YAAY,CAAS;IACrB,GAAG,CAAS;IACZ,MAAM,CAAc;IAE7B,YAAY,YAAoB,EAAE,GAAW,EAAE,MAAmB;QAChE,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import type { Check } from './check.ts';
|
|
2
|
+
import { Gauge, type Primitive } from './gauge.ts';
|
|
3
|
+
export type Sample = Exclude<Primitive, undefined>;
|
|
4
|
+
export declare abstract class Collector<K> {
|
|
5
|
+
#private;
|
|
6
|
+
protected abstract collect(check: Check): Promise<ReadonlyMap<K, Sample>>;
|
|
7
|
+
gauge(key: K): Gauge<Primitive>;
|
|
8
|
+
}
|
|
9
|
+
//# sourceMappingURL=collector.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../src/collector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAKnD,MAAM,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AAKnD,8BAAsB,SAAS,CAAC,CAAC;;IAG/B,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAEzE,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC;CAwBhC"}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { Gauge } from "./gauge.js";
|
|
2
|
+
import { Once } from "./once.js";
|
|
3
|
+
// One read that gives the values of many keys, for example one query that
|
|
4
|
+
// gives a count for each table of a database. gauge(key) gives a new gauge of
|
|
5
|
+
// one key: keep the object that you watch, because two calls give two gauges.
|
|
6
|
+
export class Collector {
|
|
7
|
+
#once = new Once();
|
|
8
|
+
gauge(key) {
|
|
9
|
+
return new Collector.#Key(this, key);
|
|
10
|
+
}
|
|
11
|
+
// The value of one key, or undefined when the read did not give the key:
|
|
12
|
+
// a key that appears or disappears changes.
|
|
13
|
+
static #Key = class Key extends Gauge {
|
|
14
|
+
#collector;
|
|
15
|
+
#key;
|
|
16
|
+
constructor(collector, key) {
|
|
17
|
+
super();
|
|
18
|
+
this.#collector = collector;
|
|
19
|
+
this.#key = key;
|
|
20
|
+
}
|
|
21
|
+
async read(check) {
|
|
22
|
+
const collector = this.#collector;
|
|
23
|
+
const values = await collector.#once.of(check, () => collector.collect(check));
|
|
24
|
+
return values.get(this.#key);
|
|
25
|
+
}
|
|
26
|
+
};
|
|
27
|
+
}
|
|
28
|
+
//# sourceMappingURL=collector.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"collector.js","sourceRoot":"","sources":["../src/collector.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAkB,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAMjC,0EAA0E;AAC1E,8EAA8E;AAC9E,8EAA8E;AAC9E,MAAM,OAAgB,SAAS;IACpB,KAAK,GAAG,IAAI,IAAI,EAA0B,CAAC;IAIpD,KAAK,CAAC,GAAM;QACV,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACvC,CAAC;IAED,yEAAyE;IACzE,4CAA4C;IAC5C,MAAM,CAAC,IAAI,GAAG,MAAM,GAAO,SAAQ,KAAgB;QACxC,UAAU,CAAe;QACzB,IAAI,CAAI;QAEjB,YAAY,SAAuB,EAAE,GAAM;YACzC,KAAK,EAAE,CAAC;YACR,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;YAC5B,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;QAClB,CAAC;QAES,KAAK,CAAC,IAAI,CAAC,KAAY;YAC/B,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC;YAClC,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAClD,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CACzB,CAAC;YACF,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC;KACF,CAAC"}
|
package/dist/gauge.d.ts
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import type { Check } from './check.ts';
|
|
2
|
+
export type Primitive = string | number | bigint | boolean | null | undefined;
|
|
3
|
+
export type Value = Primitive | readonly Value[];
|
|
4
|
+
export declare abstract class Gauge<V extends Value = Value> {
|
|
5
|
+
#private;
|
|
6
|
+
value(check: Check): Promise<V>;
|
|
7
|
+
protected abstract read(check: Check): Promise<V>;
|
|
8
|
+
}
|
|
9
|
+
//# sourceMappingURL=gauge.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"gauge.d.ts","sourceRoot":"","sources":["../src/gauge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;AAI9E,MAAM,MAAM,KAAK,GAAG,SAAS,GAAG,SAAS,KAAK,EAAE,CAAC;AAIjD,8BAAsB,KAAK,CAAC,CAAC,SAAS,KAAK,GAAG,KAAK;;IAGjD,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC;IAI/B,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC;CAClD"}
|
package/dist/gauge.js
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { Once } from "./once.js";
|
|
2
|
+
// A value read at a moment, for example the data_version of a SQLite file.
|
|
3
|
+
// value(check) reads at most one time in a check; a subclass says how to read.
|
|
4
|
+
export class Gauge {
|
|
5
|
+
#once = new Once();
|
|
6
|
+
value(check) {
|
|
7
|
+
return this.#once.of(check, () => this.read(check));
|
|
8
|
+
}
|
|
9
|
+
}
|
|
10
|
+
//# sourceMappingURL=gauge.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"gauge.js","sourceRoot":"","sources":["../src/gauge.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAQjC,2EAA2E;AAC3E,+EAA+E;AAC/E,MAAM,OAAgB,KAAK;IAChB,KAAK,GAAG,IAAI,IAAI,EAAK,CAAC;IAE/B,KAAK,CAAC,KAAY;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACtD,CAAC;CAGF"}
|
package/dist/group.d.ts
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { Check } from './check.ts';
|
|
2
|
+
import { Gauge, type Value } from './gauge.ts';
|
|
3
|
+
export declare class Group extends Gauge<readonly Value[]> {
|
|
4
|
+
#private;
|
|
5
|
+
constructor(members: readonly Gauge[]);
|
|
6
|
+
protected read(check: Check): Promise<readonly Value[]>;
|
|
7
|
+
}
|
|
8
|
+
//# sourceMappingURL=group.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../src/group.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,KAAK,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAK/C,qBAAa,KAAM,SAAQ,KAAK,CAAC,SAAS,KAAK,EAAE,CAAC;;gBAGpC,OAAO,EAAE,SAAS,KAAK,EAAE;IAKrC,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,SAAS,KAAK,EAAE,CAAC;CAGxD"}
|
package/dist/group.js
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import { Gauge } from "./gauge.js";
|
|
2
|
+
// A gauge made of gauges: its value is the values of its members. It changes
|
|
3
|
+
// when one member changes, and fails when one member fails. It keeps a copy
|
|
4
|
+
// of the members, so it cannot contain itself.
|
|
5
|
+
export class Group extends Gauge {
|
|
6
|
+
#members;
|
|
7
|
+
constructor(members) {
|
|
8
|
+
super();
|
|
9
|
+
this.#members = [...members];
|
|
10
|
+
}
|
|
11
|
+
read(check) {
|
|
12
|
+
return Promise.all(this.#members.map((member) => member.value(check)));
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
//# sourceMappingURL=group.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"group.js","sourceRoot":"","sources":["../src/group.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAc,MAAM,YAAY,CAAC;AAE/C,6EAA6E;AAC7E,4EAA4E;AAC5E,+CAA+C;AAC/C,MAAM,OAAO,KAAM,SAAQ,KAAuB;IACvC,QAAQ,CAAmB;IAEpC,YAAY,OAAyB;QACnC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,QAAQ,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC;IAC/B,CAAC;IAES,IAAI,CAAC,KAAY;QACzB,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACzE,CAAC;CACF"}
|
package/dist/index.d.ts
CHANGED
|
@@ -2,7 +2,12 @@ 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';
|
|
5
|
-
export { pollChanges, type PollChangesOptions } from './poll-changes.ts';
|
|
6
5
|
export { timeout, type Timeout, type TimeoutOptions } from './timeout.ts';
|
|
7
6
|
export { untilAborted } from './until-aborted.ts';
|
|
7
|
+
export { type Check } from './check.ts';
|
|
8
|
+
export { ChangeWatcher, type ChangeWatcherOptions, type Outcome, } from './change-watcher.ts';
|
|
9
|
+
export { Collector, type Sample } from './collector.ts';
|
|
10
|
+
export { Gauge, type Primitive, type Value } from './gauge.ts';
|
|
11
|
+
export { Group } from './group.ts';
|
|
12
|
+
export { Period } from './period.ts';
|
|
8
13
|
//# sourceMappingURL=index.d.ts.map
|
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,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,
|
|
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,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,OAAO,GACb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,KAAK,SAAS,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -2,7 +2,12 @@ export {} from "./clock.js";
|
|
|
2
2
|
export { delay } from "./delay.js";
|
|
3
3
|
export { Latch } from "./latch.js";
|
|
4
4
|
export { poll } from "./poll.js";
|
|
5
|
-
export { pollChanges } from "./poll-changes.js";
|
|
6
5
|
export { timeout } from "./timeout.js";
|
|
7
6
|
export { untilAborted } from "./until-aborted.js";
|
|
7
|
+
export {} from "./check.js";
|
|
8
|
+
export { ChangeWatcher, } from "./change-watcher.js";
|
|
9
|
+
export { Collector } from "./collector.js";
|
|
10
|
+
export { Gauge } from "./gauge.js";
|
|
11
|
+
export { Group } from "./group.js";
|
|
12
|
+
export { Period } from "./period.js";
|
|
8
13
|
//# 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,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,
|
|
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,OAAO,EAAqC,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAc,MAAM,YAAY,CAAC;AACxC,OAAO,EACL,aAAa,GAGd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAe,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,KAAK,EAA8B,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"milliseconds.d.ts","sourceRoot":"","sources":["../src/milliseconds.ts"],"names":[],"mappings":"AAGA,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAM7D"}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
// A duration that a watch can wait: a positive, finite number of
|
|
2
|
+
// milliseconds. Zero or less would check with no wait, and no number would
|
|
3
|
+
// never check.
|
|
4
|
+
export function milliseconds(name, ms) {
|
|
5
|
+
if (!(ms > 0 && Number.isFinite(ms)))
|
|
6
|
+
throw new RangeError(`${name} must be a positive number of milliseconds, not ${ms}`);
|
|
7
|
+
return ms;
|
|
8
|
+
}
|
|
9
|
+
//# sourceMappingURL=milliseconds.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"milliseconds.js","sourceRoot":"","sources":["../src/milliseconds.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,2EAA2E;AAC3E,eAAe;AACf,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,EAAU;IACnD,IAAI,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAClC,MAAM,IAAI,UAAU,CAClB,GAAG,IAAI,mDAAmD,EAAE,EAAE,CAC/D,CAAC;IACJ,OAAO,EAAE,CAAC;AACZ,CAAC"}
|
package/dist/once.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"once.d.ts","sourceRoot":"","sources":["../src/once.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMxC,qBAAa,IAAI,CAAC,CAAC;;IAGX,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAgB3D"}
|
package/dist/once.js
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { Latch } from "./latch.js";
|
|
2
|
+
// The outcome of one read in each check. The latch keeps the outcome as data
|
|
3
|
+
// (ADR 0002), so a failed read rejects only for the callers that wait. A read
|
|
4
|
+
// that throws at once fails as an async read does.
|
|
5
|
+
export class Once {
|
|
6
|
+
#outcomes = new WeakMap();
|
|
7
|
+
async of(check, read) {
|
|
8
|
+
const outcome = await this.#latch(check, read).wait();
|
|
9
|
+
if (outcome.status === 'rejected')
|
|
10
|
+
throw outcome.reason;
|
|
11
|
+
return outcome.value;
|
|
12
|
+
}
|
|
13
|
+
#latch(check, read) {
|
|
14
|
+
const known = this.#outcomes.get(check);
|
|
15
|
+
if (known !== undefined)
|
|
16
|
+
return known;
|
|
17
|
+
const latch = new Latch();
|
|
18
|
+
this.#outcomes.set(check, latch);
|
|
19
|
+
void Promise.allSettled([Promise.try(read)]).then(([outcome]) => latch.open(outcome));
|
|
20
|
+
return latch;
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
//# sourceMappingURL=once.js.map
|
package/dist/once.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"once.js","sourceRoot":"","sources":["../src/once.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,6EAA6E;AAC7E,8EAA8E;AAC9E,mDAAmD;AACnD,MAAM,OAAO,IAAI;IACN,SAAS,GAAG,IAAI,OAAO,EAAyC,CAAC;IAE1E,KAAK,CAAC,EAAE,CAAC,KAAY,EAAE,IAAsB;QAC3C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;QACtD,IAAI,OAAO,CAAC,MAAM,KAAK,UAAU;YAAE,MAAM,OAAO,CAAC,MAAM,CAAC;QACxD,OAAO,OAAO,CAAC,KAAK,CAAC;IACvB,CAAC;IAED,MAAM,CAAC,KAAY,EAAE,IAAsB;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QACtC,MAAM,KAAK,GAAG,IAAI,KAAK,EAA2B,CAAC;QACnD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACjC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,EAAE,CAC9D,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CACpB,CAAC;QACF,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}
|
package/dist/period.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"period.d.ts","sourceRoot":"","sources":["../src/period.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMnC,qBAAa,MAAO,SAAQ,KAAK,CAAC,MAAM,CAAC;;gBAG3B,EAAE,EAAE,MAAM;cAKN,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC;CAGpD"}
|
package/dist/period.js
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { Gauge } from "./gauge.js";
|
|
2
|
+
import { milliseconds } from "./milliseconds.js";
|
|
3
|
+
// The count of whole periods since the watch started. It changes one time in
|
|
4
|
+
// each period, whatever else changed: a consumer reads again on a schedule,
|
|
5
|
+
// for example every hour, also when no other gauge saw a change.
|
|
6
|
+
export class Period extends Gauge {
|
|
7
|
+
#ms;
|
|
8
|
+
constructor(ms) {
|
|
9
|
+
super();
|
|
10
|
+
this.#ms = milliseconds('A period', ms);
|
|
11
|
+
}
|
|
12
|
+
async read(check) {
|
|
13
|
+
return Math.floor((check.now - check.watchStarted) / this.#ms);
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
//# sourceMappingURL=period.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"period.js","sourceRoot":"","sources":["../src/period.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,6EAA6E;AAC7E,4EAA4E;AAC5E,iEAAiE;AACjE,MAAM,OAAO,MAAO,SAAQ,KAAa;IAC9B,GAAG,CAAS;IAErB,YAAY,EAAU;QACpB,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,GAAG,GAAG,YAAY,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC1C,CAAC;IAES,KAAK,CAAC,IAAI,CAAC,KAAY;QAC/B,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACjE,CAAC;CACF"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zukhruf/async",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.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": {
|
package/dist/poll-changes.d.ts
DELETED
|
@@ -1,19 +0,0 @@
|
|
|
1
|
-
import type { Clock } from './clock.ts';
|
|
2
|
-
export interface PollChangesOptions {
|
|
3
|
-
/** Milliseconds to wait after a check, from when the consumer asks for the next check. */
|
|
4
|
-
interval: number;
|
|
5
|
-
/** Stops the wait between two checks. The iteration then ends with no error. */
|
|
6
|
-
signal: AbortSignal;
|
|
7
|
-
/** The clock that the wait runs on: `globalThis` in production, a fake clock in a test. */
|
|
8
|
-
clock: Clock;
|
|
9
|
-
}
|
|
10
|
-
/**
|
|
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.
|
|
17
|
-
*/
|
|
18
|
-
export declare function pollChanges<K>(read: () => Promise<ReadonlyMap<K, unknown>>, { interval, signal, clock }: PollChangesOptions): AsyncGenerator<ReadonlySet<K>, void, undefined>;
|
|
19
|
-
//# sourceMappingURL=poll-changes.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
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
DELETED
|
@@ -1,40 +0,0 @@
|
|
|
1
|
-
import { delay } from "./delay.js";
|
|
2
|
-
/**
|
|
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.
|
|
9
|
-
*/
|
|
10
|
-
export async function* pollChanges(read, { interval, signal, clock }) {
|
|
11
|
-
if (signal.aborted)
|
|
12
|
-
return;
|
|
13
|
-
let previous = await read();
|
|
14
|
-
yield new Set(previous.keys());
|
|
15
|
-
for (;;) {
|
|
16
|
-
try {
|
|
17
|
-
await delay(interval, { clock, signal });
|
|
18
|
-
}
|
|
19
|
-
catch (error) {
|
|
20
|
-
if (signal.aborted)
|
|
21
|
-
return;
|
|
22
|
-
throw error;
|
|
23
|
-
}
|
|
24
|
-
const values = await read();
|
|
25
|
-
yield changedKeys(previous, values);
|
|
26
|
-
previous = values;
|
|
27
|
-
}
|
|
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
|
-
}
|
|
40
|
-
//# sourceMappingURL=poll-changes.js.map
|
package/dist/poll-changes.js.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
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"}
|