@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 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 `pollChanges` reads values again and again and tells which values changed. `@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, `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. `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.
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 { pollChanges } from '@zukhruf/async';
124
+ import { ChangeWatcher, Gauge } from '@zukhruf/async';
125
125
 
126
- const read = async () => new Map([['messages', version.current]]);
127
- const watch = pollChanges(read, {
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
- signal,
135
+ timeout: 1_000,
130
136
  clock: globalThis,
131
137
  });
132
- for await (const changed of watch) {
133
- if (changed.size > 0) await copyMessages();
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, and yields all keys: you have never seen the values.
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
- - 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
- - `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
- - 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.
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
- ### Watch many values in one loop
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
- 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.
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
- const read = async () =>
150
- new Map([
151
- ['library', await library.version()],
152
- ['annotations', await annotations.version()],
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, `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.
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
- 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).
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 `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.
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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"}
@@ -0,0 +1,7 @@
1
+ export declare class Check {
2
+ readonly watchStarted: number;
3
+ readonly now: number;
4
+ readonly signal: AbortSignal;
5
+ constructor(watchStarted: number, now: number, signal: AbortSignal);
6
+ }
7
+ //# sourceMappingURL=check.d.ts.map
@@ -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"}
@@ -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"}
@@ -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
@@ -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,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,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,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,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,2 @@
1
+ export declare function milliseconds(name: string, ms: number): number;
2
+ //# sourceMappingURL=milliseconds.d.ts.map
@@ -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,6 @@
1
+ import type { Check } from './check.ts';
2
+ export declare class Once<T> {
3
+ #private;
4
+ of(check: Check, read: () => Promise<T>): Promise<T>;
5
+ }
6
+ //# sourceMappingURL=once.d.ts.map
@@ -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
@@ -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"}
@@ -0,0 +1,8 @@
1
+ import type { Check } from './check.ts';
2
+ import { Gauge } from './gauge.ts';
3
+ export declare class Period extends Gauge<number> {
4
+ #private;
5
+ constructor(ms: number);
6
+ protected read(check: Check): Promise<number>;
7
+ }
8
+ //# sourceMappingURL=period.d.ts.map
@@ -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.7.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": {
@@ -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"}
@@ -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
@@ -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"}