@zukhruf/async 0.8.23 → 0.8.25

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, `Backoff` gives a longer wait before each retry, and `ChangeWatcher` reads gauges 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, `Future` gives callers the value or the failure of work that ends once, `Lock` lets one caller at a time do a thing, `Semaphore` lets a number of callers at a time do it, `WaitGroup` waits until the work in flight is done, `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, `Backoff` gives a longer wait before each retry, 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
 
@@ -50,10 +50,125 @@ done.open('report');
50
50
  const value = await done.wait(); // 'report'
51
51
  ```
52
52
 
53
- A latch never rejects. It keeps its value in a box, so it never adopts a promise, whatever its type. Thus a class can keep a latch in a field: the latch cannot fail before somebody awaits it. A latch whose type names a promise refuses one at compile time, because a wait would adopt the promise and could then reject. To share the outcome of work that can fail, give the latch a value that tells how the work ended, for example the `PromiseSettledResult` of `Promise.allSettled`. Each caller then throws the error for itself. See [ADR 0002](./docs/adr/0002-a-latch-carries-a-value-never-a-failure.md).
53
+ A latch never rejects. It keeps its value in a box, so it never adopts a promise, whatever its type. Thus a class can keep a latch in a field: the latch cannot fail before somebody awaits it. A latch whose type names a promise refuses one at compile time, because a wait would adopt the promise and could then reject. To share the outcome of work that can fail, use a future. See [Give callers the outcome of work that can fail, with a future](#give-callers-the-outcome-of-work-that-can-fail-with-a-future) and [ADR 0002](./docs/adr/0002-a-latch-carries-a-value-never-a-failure.md).
54
54
 
55
55
  To stop a wait on a latch, cancel it: `untilAborted(latch.wait(), signal)`.
56
56
 
57
+ A latch always starts closed. Each latch that a caller opened at once was a lock or a wait group: it ran work in order, or it waited until a count of work was zero. To run work one at a time, see [Let one caller at a time do a thing, with a lock](#let-one-caller-at-a-time-do-a-thing-with-a-lock) (#4519). To wait until a count of work is zero, see [Wait until the work in flight is done, with a wait group](#wait-until-the-work-in-flight-is-done-with-a-wait-group) (#4527).
58
+
59
+ ## Give callers the outcome of work that can fail, with a future
60
+
61
+ A future holds the outcome of work that ends once: a value or a failure. `resolve` settles it with a value, and `reject` settles it with a failure. A wait on the future ends when it settles: it gets the value, or it rejects with the reason. A wait that starts after the future settled ends at once, with the same value or the same reason.
62
+
63
+ ```ts
64
+ import { Future } from '@zukhruf/async';
65
+
66
+ const report = new Future<string>();
67
+
68
+ report.resolve('done');
69
+ const value = await report.wait(); // 'done'
70
+
71
+ const failed = new Future<string>();
72
+ failed.reject(new Error('disk full'));
73
+ await failed.wait(); // Rejects with the error 'disk full'.
74
+ ```
75
+
76
+ `Future.run(work)` starts the work and gives a future that settles with its outcome:
77
+
78
+ ```ts
79
+ // Each caller that waits gets the same value, and the read runs once.
80
+ const config = Future.run(() => readFile('config.json', 'utf8'));
81
+ ```
82
+
83
+ - The first `resolve` or `reject` settles the future. A later `resolve` or `reject` changes nothing.
84
+ - A future keeps its failure as data, and only a wait rejects. Thus a failure that nobody waits for leaves no unhandled rejection, and a class can keep a future in a field.
85
+ - A future whose type names a promise refuses one at compile time in `resolve`, because a wait would adopt the promise.
86
+ - `run` turns a work that throws at once into a failure of the future, as a work that rejects. `run` itself never throws.
87
+ - To stop a wait on a future, cancel it: `untilAborted(future.wait(), signal)`. The work continues.
88
+
89
+ A future holds a latch that carries the outcome as a `PromiseSettledResult`. See [ADR 0014](./docs/adr/0014-a-future-keeps-its-failure-as-data-and-only-a-wait-rejects.md).
90
+
91
+ ## Let one caller at a time do a thing, with a lock
92
+
93
+ A lock lets one caller at a time hold it. The other callers wait in a line, and they get the lock in the order in which they came. `run` holds the lock while the work runs, and frees it when the work ends, also when the work fails.
94
+
95
+ ```ts
96
+ import { Lock } from '@zukhruf/async';
97
+
98
+ const writes = new Lock();
99
+
100
+ // Two writes of the state file never overlap, and they run in the order of the calls.
101
+ await writes.run(() => writeState(state), { signal });
102
+ ```
103
+
104
+ To hold the lock for more than one call, acquire it. Dispose the handle to free the lock: `using` frees it at the end of the block.
105
+
106
+ ```ts
107
+ {
108
+ using held = await writes.acquire({ signal });
109
+ const state = await readState();
110
+ await writeState({ ...state, count: state.count + 1 });
111
+ }
112
+ ```
113
+
114
+ - A failed work rejects `run` with its error, and the next caller then gets the lock. A failed write thus never stops the writes after it.
115
+ - When `signal` aborts while the caller waits, the caller leaves the line, and the call rejects with the reason of the signal. The work of a cancelled `run` never starts.
116
+ - When `signal` aborted before the call, the call rejects at once, and the caller takes nothing, also when the lock is free.
117
+ - `tryAcquire()` gives the handle only when the lock is free and nobody waits, else `undefined`. It never goes before a caller in the line.
118
+ - A second dispose of one handle frees nothing.
119
+ - A lock is not reentrant: a holder that acquires again waits for itself.
120
+ - To limit the wait, give the signal of a `timeout`. See [Stop a wait after a time](#stop-a-wait-after-a-time).
121
+
122
+ A lock is a semaphore of one permit. See [ADR 0013](./docs/adr/0013-a-lock-is-a-semaphore-of-one-that-grants-in-order-and-a-cancel-leaves-the-line.md).
123
+
124
+ ## Let a number of callers at a time do a thing, with a semaphore
125
+
126
+ A semaphore has a count of permits. A caller that finds a free permit holds it at once. A caller that finds no free permit waits in a line, and the permits go to the line in the order in which the callers came. Dispose the permit to give it back.
127
+
128
+ ```ts
129
+ import { Semaphore } from '@zukhruf/async';
130
+
131
+ // At most 4 downloads at the same time.
132
+ const downloads = new Semaphore(4);
133
+
134
+ async function download(url: string) {
135
+ using permit = await downloads.acquire({ signal });
136
+ return fetch(url, { signal });
137
+ }
138
+ ```
139
+
140
+ - A dispose gives the permit to the first caller in the line at once. Thus `tryAcquire()` gives `undefined` while callers wait, also just after a dispose.
141
+ - A cancel, a cancel before the call and a second dispose have the same rules as for a lock.
142
+ - When the turn of a caller comes in the same step as its cancel, the cancel wins, and the permit passes on to the next caller.
143
+ - The constructor throws a `RangeError` for a count of permits that is not a positive integer.
144
+
145
+ ## Wait until the work in flight is done, with a wait group
146
+
147
+ A wait group counts the work in flight. `add` gives a token, and the wait group counts the token until you dispose it. A wait ends when the count is zero. After zero, the count can go up again, as in a Go `sync.WaitGroup`.
148
+
149
+ ```ts
150
+ import { WaitGroup } from '@zukhruf/async';
151
+
152
+ const commands = new WaitGroup();
153
+
154
+ async function handle(command: Command) {
155
+ using _command = commands.add();
156
+ await run(command);
157
+ }
158
+
159
+ // At shutdown: stop new commands, then wait for the commands that run.
160
+ await commands.wait({ signal });
161
+ ```
162
+
163
+ - A wait on a count of zero ends at once.
164
+ - A wait on a count above zero ends when the count next reaches zero. Each wait that started before that zero ends, also when an `add` follows the zero in the same step. A wait that starts after that `add` waits for the new work.
165
+ - A second dispose of one token changes nothing.
166
+ - When `signal` aborts during the wait, the wait rejects with the reason of the signal, and its listener leaves the signal. The count does not change, and the work continues.
167
+ - When `signal` aborted before the call, the wait rejects at once, also when the count is zero.
168
+ - No listener stays on the signal after a wait ends, so a signal that lives long can serve many waits.
169
+
170
+ A wait group holds a latch, and puts a new latch in its place each time the count reaches zero. See [ADR 0015](./docs/adr/0015-a-wait-group-counts-disposable-tokens-and-may-count-up-again-after-zero.md).
171
+
57
172
  ## Poll an attempt until it gives a value
58
173
 
59
174
  An attempt tries to get a value now, and it does not wait. For example, it tries to take a lock that another process can hold. The attempt gives the value, or `undefined` when there is no value yet. `poll` calls the attempt. When the attempt gives `undefined`, `poll` waits `interval` milliseconds, and then it calls the attempt again. When the attempt gives a value, `poll` resolves with that value.
@@ -260,12 +375,12 @@ const state = await readState(container, { signal: limit.signal });
260
375
 
261
376
  - The signal aborts with a `DOMException` whose name is `TimeoutError`, as the signal of `AbortSignal.timeout` does.
262
377
  - A disposal stops the timer, and the signal then does not abort. `using` disposes the timeout at the end of the block.
263
- - The timer keeps the process alive until it fires or until the disposal. The timer of `AbortSignal.timeout` does not keep the process alive, but no call can stop it.
378
+ - The timer does not keep the process alive, as the timer of `AbortSignal.timeout` does not. The work that the timeout limits, such as a request, keeps the process alive. Give `ref: true` when the signal must abort also while no other work keeps the process alive: `timeout(ms, { clock, ref: true })`.
264
379
  - To stop a wait at the timeout or at the signal of the caller, give `AbortSignal.any([signal, limit.signal])`.
265
380
  - The time runs in ten parts, each on one timer of at most 2^31-1 ms, so a timeout can be longer than one timer can hold.
266
381
  - A part that ends late uses up only its own length. On macOS, a timer of Node.js counts the time of a system sleep, so a timer that was running when the computer slept fires at the wake. The timeout then still gives the wait the rest of its time: a timeout of 5 seconds that slept in its first half second aborts 4.5 seconds after the wake, not at the wake. A process that the system stopped gets the same.
267
382
 
268
- See [ADR 0006](./docs/adr/0006-a-timeout-is-a-signal-on-the-clock-that-the-caller-gives.md) and [ADR 0010](./docs/adr/0010-a-timeout-counts-its-time-in-parts.md).
383
+ See [ADR 0006](./docs/adr/0006-a-timeout-is-a-signal-on-the-clock-that-the-caller-gives.md), [ADR 0010](./docs/adr/0010-a-timeout-counts-its-time-in-parts.md) and [ADR 0012](./docs/adr/0012-a-timeout-keeps-the-process-alive-only-when-the-caller-says-so.md).
269
384
 
270
385
  ## Run a wait on a clock
271
386
 
@@ -1 +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"}
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;CA6D5D"}
@@ -52,8 +52,10 @@ export class ChangeWatcher {
52
52
  }
53
53
  }
54
54
  // One check. Its timer ends with the check, before the consumer gets it.
55
+ // The timer keeps the process alive, as the wait between checks does, so a
56
+ // read that never answers fails at the timeout and the watch goes on.
55
57
  async #check(watchStarted, last, signal) {
56
- using limit = timeout(this.#timeout, { clock: this.#clock });
58
+ using limit = timeout(this.#timeout, { clock: this.#clock, ref: true });
57
59
  const check = new Check(watchStarted, this.#clock.Date.now(), AbortSignal.any([signal, limit.signal]));
58
60
  // A read that ignores the signal still ends for this check at the timeout.
59
61
  const reads = await Promise.all(this.#gauges.map(async (gauge) => {
@@ -1 +1 @@
1
- {"version":3,"file":"change-watcher.js","sourceRoot":"","sources":["../src/change-watcher.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"change-watcher.js","sourceRoot":"","sources":["../src/change-watcher.ts"],"names":[],"mappings":"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"}
package/dist/delay.d.ts CHANGED
@@ -23,4 +23,6 @@ export declare const TIMER_MAX: number;
23
23
  * longer.
24
24
  */
25
25
  export declare function delay(ms: number, options: DelayOptions): Promise<void>;
26
+ /** Calls `unref()` on a timer of a clock, when the timer has one. */
27
+ export declare function unref(timer: unknown): void;
26
28
  //# sourceMappingURL=delay.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"delay.d.ts","sourceRoot":"","sources":["../src/delay.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,MAAM,WAAW,YAAY;IAC3B,2FAA2F;IAC3F,KAAK,EAAE,KAAK,CAAC;IACb,mFAAmF;IACnF,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC;;;;OAIG;IACH,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC3B;AAID,eAAO,MAAM,SAAS,QAAc,CAAC;AAErC;;;;;;;;;GASG;AACH,wBAAsB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ5E"}
1
+ {"version":3,"file":"delay.d.ts","sourceRoot":"","sources":["../src/delay.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,MAAM,WAAW,YAAY;IAC3B,2FAA2F;IAC3F,KAAK,EAAE,KAAK,CAAC;IACb,mFAAmF;IACnF,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC;;;;OAIG;IACH,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC3B;AAID,eAAO,MAAM,SAAS,QAAc,CAAC;AAErC;;;;;;;;;GASG;AACH,wBAAsB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ5E;AAeD,qEAAqE;AACrE,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAS1C"}
package/dist/delay.js CHANGED
@@ -34,7 +34,8 @@ function wait(ms, { clock, signal, ref }) {
34
34
  const listening = addAbortListener(signal, () => clock.clearTimeout(timer));
35
35
  return untilAborted(promise, signal).finally(() => listening[Symbol.dispose]());
36
36
  }
37
- function unref(timer) {
37
+ /** Calls `unref()` on a timer of a clock, when the timer has one. */
38
+ export function unref(timer) {
38
39
  if (typeof timer === 'object' &&
39
40
  timer !== null &&
40
41
  'unref' in timer &&
package/dist/delay.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"delay.js","sourceRoot":"","sources":["../src/delay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAelD,2EAA2E;AAC3E,mEAAmE;AACnE,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAErC;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,EAAU,EAAE,OAAqB;IAC3D,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;IACjD,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,OAAO,IAAI,GAAG,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC/B,IAAI,GAAG,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;IAC/C,CAAC;IACD,MAAM,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC5B,CAAC;AAED,aAAa;AACb,SAAS,IAAI,CAAC,EAAU,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAgB;IAC5D,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,aAAa,EAAQ,CAAC;IAC3D,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC5C,IAAI,GAAG,KAAK,KAAK;QAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM;QAAE,OAAO,OAAO,CAAC;IAC5B,qDAAqD;IACrD,MAAM,SAAS,GAAG,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5E,OAAO,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAChD,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAC5B,CAAC;AACJ,CAAC;AAED,SAAS,KAAK,CAAC,KAAc;IAC3B,IACE,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAO,IAAI,KAAK;QAChB,OAAO,KAAK,CAAC,KAAK,KAAK,UAAU,EACjC,CAAC;QACD,KAAK,CAAC,KAAK,EAAE,CAAC;IAChB,CAAC;AACH,CAAC"}
1
+ {"version":3,"file":"delay.js","sourceRoot":"","sources":["../src/delay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAelD,2EAA2E;AAC3E,mEAAmE;AACnE,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAErC;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,EAAU,EAAE,OAAqB;IAC3D,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;IACjD,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,OAAO,IAAI,GAAG,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC/B,IAAI,GAAG,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;IAC/C,CAAC;IACD,MAAM,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC5B,CAAC;AAED,aAAa;AACb,SAAS,IAAI,CAAC,EAAU,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAgB;IAC5D,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,aAAa,EAAQ,CAAC;IAC3D,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC5C,IAAI,GAAG,KAAK,KAAK;QAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM;QAAE,OAAO,OAAO,CAAC;IAC5B,qDAAqD;IACrD,MAAM,SAAS,GAAG,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5E,OAAO,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAChD,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAC5B,CAAC;AACJ,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,KAAK,CAAC,KAAc;IAClC,IACE,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAO,IAAI,KAAK;QAChB,OAAO,KAAK,CAAC,KAAK,KAAK,UAAU,EACjC,CAAC;QACD,KAAK,CAAC,KAAK,EAAE,CAAC;IAChB,CAAC;AACH,CAAC"}
@@ -0,0 +1,20 @@
1
+ /**
2
+ * The outcome of work that ends once: a value or a failure. The first resolve
3
+ * or reject settles it, and every wait, early or late, gets that value or
4
+ * rejects with that reason. It keeps the failure as data, so only a wait
5
+ * rejects, and a failure that nobody waits for leaves no unhandled rejection.
6
+ */
7
+ export declare class Future<T> {
8
+ #private;
9
+ /** Settles the future with the outcome of `work`. A work that throws at once fails as an async work does. */
10
+ static run<T>(work: () => Promise<T>): Future<T>;
11
+ /**
12
+ * A settled future ignores it. A type that names a promise is refused: the
13
+ * future would adopt the promise, and its value could then be a failure.
14
+ */
15
+ resolve(value: T extends PromiseLike<unknown> ? never : T): void;
16
+ /** A settled future ignores it. */
17
+ reject(reason: unknown): void;
18
+ wait(): Promise<T>;
19
+ }
20
+ //# sourceMappingURL=future.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"future.d.ts","sourceRoot":"","sources":["../src/future.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,qBAAa,MAAM,CAAC,CAAC;;IAGnB,6GAA6G;IAC7G,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IAQhD;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,CAAC,SAAS,WAAW,CAAC,OAAO,CAAC,GAAG,KAAK,GAAG,CAAC,GAAG,IAAI;IAIhE,mCAAmC;IACnC,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAIvB,IAAI,IAAI,OAAO,CAAC,CAAC,CAAC;CAKzB"}
package/dist/future.js ADDED
@@ -0,0 +1,34 @@
1
+ import { Latch } from "./latch.js";
2
+ /**
3
+ * The outcome of work that ends once: a value or a failure. The first resolve
4
+ * or reject settles it, and every wait, early or late, gets that value or
5
+ * rejects with that reason. It keeps the failure as data, so only a wait
6
+ * rejects, and a failure that nobody waits for leaves no unhandled rejection.
7
+ */
8
+ export class Future {
9
+ #outcome = new Latch();
10
+ /** Settles the future with the outcome of `work`. A work that throws at once fails as an async work does. */
11
+ static run(work) {
12
+ const future = new Future();
13
+ void Promise.allSettled([Promise.try(work)]).then(([outcome]) => future.#outcome.open(outcome));
14
+ return future;
15
+ }
16
+ /**
17
+ * A settled future ignores it. A type that names a promise is refused: the
18
+ * future would adopt the promise, and its value could then be a failure.
19
+ */
20
+ resolve(value) {
21
+ this.#outcome.open({ status: 'fulfilled', value });
22
+ }
23
+ /** A settled future ignores it. */
24
+ reject(reason) {
25
+ this.#outcome.open({ status: 'rejected', reason });
26
+ }
27
+ async wait() {
28
+ const outcome = await this.#outcome.wait();
29
+ if (outcome.status === 'rejected')
30
+ throw outcome.reason;
31
+ return outcome.value;
32
+ }
33
+ }
34
+ //# sourceMappingURL=future.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"future.js","sourceRoot":"","sources":["../src/future.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,OAAO,MAAM;IACR,QAAQ,GAAG,IAAI,KAAK,EAA2B,CAAC;IAEzD,6GAA6G;IAC7G,MAAM,CAAC,GAAG,CAAI,IAAsB;QAClC,MAAM,MAAM,GAAG,IAAI,MAAM,EAAK,CAAC;QAC/B,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,EAAE,CAC9D,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAC9B,CAAC;QACF,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,KAAiD;QACvD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;IACrD,CAAC;IAED,mCAAmC;IACnC,MAAM,CAAC,MAAe;QACpB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC3C,IAAI,OAAO,CAAC,MAAM,KAAK,UAAU;YAAE,MAAM,OAAO,CAAC,MAAM,CAAC;QACxD,OAAO,OAAO,CAAC,KAAK,CAAC;IACvB,CAAC;CACF"}
package/dist/index.d.ts CHANGED
@@ -1,10 +1,14 @@
1
1
  export { Backoff, type BackoffOptions, type Jitter } from './backoff.ts';
2
2
  export { type Clock, type WallClock } from './clock.ts';
3
3
  export { delay, type DelayOptions } from './delay.ts';
4
+ export { Future } from './future.ts';
4
5
  export { Latch } from './latch.ts';
6
+ export { Lock } from './lock.ts';
5
7
  export { poll, type PollOptions } from './poll.ts';
8
+ export { type AcquireOptions, Semaphore } from './semaphore.ts';
6
9
  export { timeout, type Timeout, type TimeoutOptions } from './timeout.ts';
7
10
  export { untilAborted } from './until-aborted.ts';
11
+ export { WaitGroup, type WaitOptions } from './wait-group.ts';
8
12
  export { type Check } from './check.ts';
9
13
  export { ChangeWatcher, type ChangeWatcherOptions, type Outcome, } from './change-watcher.ts';
10
14
  export { Collector, type Sample } from './collector.ts';
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AACzE,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"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AACzE,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,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,KAAK,cAAc,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9D,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
@@ -1,10 +1,14 @@
1
1
  export { Backoff } from "./backoff.js";
2
2
  export {} from "./clock.js";
3
3
  export { delay } from "./delay.js";
4
+ export { Future } from "./future.js";
4
5
  export { Latch } from "./latch.js";
6
+ export { Lock } from "./lock.js";
5
7
  export { poll } from "./poll.js";
8
+ export { Semaphore } from "./semaphore.js";
6
9
  export { timeout } from "./timeout.js";
7
10
  export { untilAborted } from "./until-aborted.js";
11
+ export { WaitGroup } from "./wait-group.js";
8
12
  export {} from "./check.js";
9
13
  export { ChangeWatcher, } from "./change-watcher.js";
10
14
  export { Collector } from "./collector.js";
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAoC,MAAM,cAAc,CAAC;AACzE,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"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAoC,MAAM,cAAc,CAAC;AACzE,OAAO,EAA8B,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,KAAK,EAAqB,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,IAAI,EAAoB,MAAM,WAAW,CAAC;AACnD,OAAO,EAAuB,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,OAAO,EAAqC,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAoB,MAAM,iBAAiB,CAAC;AAC9D,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"}
package/dist/lock.d.ts ADDED
@@ -0,0 +1,15 @@
1
+ import { type AcquireOptions } from './semaphore.ts';
2
+ /**
3
+ * Lets one caller at a time hold it: a semaphore of one permit. Callers that
4
+ * wait get the lock in the order in which they came.
5
+ */
6
+ export declare class Lock {
7
+ #private;
8
+ /** Waits in the line for the lock. Dispose the handle to free it: `using held = await lock.acquire(…)`. */
9
+ acquire(options: AcquireOptions): Promise<Disposable>;
10
+ /** Gives the lock only when it is free and nobody waits. */
11
+ tryAcquire(): Disposable | undefined;
12
+ /** Holds the lock while `work` runs, and frees it when the work ends, also when the work fails. */
13
+ run<T>(work: () => Promise<T>, options: AcquireOptions): Promise<T>;
14
+ }
15
+ //# sourceMappingURL=lock.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../src/lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAAa,MAAM,gBAAgB,CAAC;AAEhE;;;GAGG;AACH,qBAAa,IAAI;;IAGf,2GAA2G;IAC3G,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC;IAIrD,4DAA4D;IAC5D,UAAU,IAAI,UAAU,GAAG,SAAS;IAIpC,mGAAmG;IAC7F,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;CAI1E"}
package/dist/lock.js ADDED
@@ -0,0 +1,22 @@
1
+ import { Semaphore } from "./semaphore.js";
2
+ /**
3
+ * Lets one caller at a time hold it: a semaphore of one permit. Callers that
4
+ * wait get the lock in the order in which they came.
5
+ */
6
+ export class Lock {
7
+ #semaphore = new Semaphore(1);
8
+ /** Waits in the line for the lock. Dispose the handle to free it: `using held = await lock.acquire(…)`. */
9
+ acquire(options) {
10
+ return this.#semaphore.acquire(options);
11
+ }
12
+ /** Gives the lock only when it is free and nobody waits. */
13
+ tryAcquire() {
14
+ return this.#semaphore.tryAcquire();
15
+ }
16
+ /** Holds the lock while `work` runs, and frees it when the work ends, also when the work fails. */
17
+ async run(work, options) {
18
+ using _held = await this.acquire(options);
19
+ return await work();
20
+ }
21
+ }
22
+ //# sourceMappingURL=lock.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"lock.js","sourceRoot":"","sources":["../src/lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhE;;;GAGG;AACH,MAAM,OAAO,IAAI;IACN,UAAU,GAAG,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC;IAEvC,2GAA2G;IAC3G,OAAO,CAAC,OAAuB;QAC7B,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED,4DAA4D;IAC5D,UAAU;QACR,OAAO,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;IACtC,CAAC;IAED,mGAAmG;IACnG,KAAK,CAAC,GAAG,CAAI,IAAsB,EAAE,OAAuB;QAC1D,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC1C,OAAO,MAAM,IAAI,EAAE,CAAC;IACtB,CAAC;CACF"}
@@ -1 +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"}
1
+ {"version":3,"file":"once.d.ts","sourceRoot":"","sources":["../src/once.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAKxC,qBAAa,IAAI,CAAC,CAAC;;IAGjB,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAQrD"}
package/dist/once.js CHANGED
@@ -1,23 +1,15 @@
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.
1
+ import { Future } from "./future.js";
2
+ // The outcome of one read in each check. The future keeps a failed read as
3
+ // data (ADR 0014), so it rejects only for the callers that wait.
5
4
  export class Once {
6
5
  #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;
6
+ of(check, read) {
7
+ let outcome = this.#outcomes.get(check);
8
+ if (outcome === undefined) {
9
+ outcome = Future.run(read);
10
+ this.#outcomes.set(check, outcome);
11
+ }
12
+ return outcome.wait();
21
13
  }
22
14
  }
23
15
  //# sourceMappingURL=once.js.map
package/dist/once.js.map CHANGED
@@ -1 +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"}
1
+ {"version":3,"file":"once.js","sourceRoot":"","sources":["../src/once.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,2EAA2E;AAC3E,iEAAiE;AACjE,MAAM,OAAO,IAAI;IACN,SAAS,GAAG,IAAI,OAAO,EAAoB,CAAC;IAErD,EAAE,CAAC,KAAY,EAAE,IAAsB;QACrC,IAAI,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC3B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACrC,CAAC;QACD,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;IACxB,CAAC;CACF"}
@@ -0,0 +1,23 @@
1
+ export interface AcquireOptions {
2
+ /** Cancels the wait: the caller leaves the line, and the acquire rejects with `signal.reason`. */
3
+ signal: AbortSignal | undefined;
4
+ }
5
+ /**
6
+ * Lets at most `permits` callers hold a permit at the same time. A caller
7
+ * that finds no free permit waits in a line, and the permits go to the line
8
+ * in the order in which the callers came. A dispose of a permit gives it to
9
+ * the first waiter, so a later caller never takes it first.
10
+ */
11
+ export declare class Semaphore {
12
+ #private;
13
+ constructor(permits: number);
14
+ /**
15
+ * Gives a permit when one is free, or waits in the line for one. Dispose
16
+ * the permit to give it back: `using permit = await semaphore.acquire(…)`.
17
+ * When the signal aborts, also before the call, the caller takes no permit.
18
+ */
19
+ acquire({ signal }: AcquireOptions): Promise<Disposable>;
20
+ /** Gives a permit only when one is free, which is never while callers wait in the line. */
21
+ tryAcquire(): Disposable | undefined;
22
+ }
23
+ //# sourceMappingURL=semaphore.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"semaphore.d.ts","sourceRoot":"","sources":["../src/semaphore.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAC7B,kGAAkG;IAClG,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;CACjC;AAED;;;;;GAKG;AACH,qBAAa,SAAS;;gBAOR,OAAO,EAAE,MAAM;IAQ3B;;;;OAIG;IACG,OAAO,CAAC,EAAE,MAAM,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC;IAkB9D,2FAA2F;IAC3F,UAAU,IAAI,UAAU,GAAG,SAAS;CAqBrC"}
@@ -0,0 +1,70 @@
1
+ import { untilAborted } from "./until-aborted.js";
2
+ /**
3
+ * Lets at most `permits` callers hold a permit at the same time. A caller
4
+ * that finds no free permit waits in a line, and the permits go to the line
5
+ * in the order in which the callers came. A dispose of a permit gives it to
6
+ * the first waiter, so a later caller never takes it first.
7
+ */
8
+ export class Semaphore {
9
+ #free;
10
+ /** The turns of the waiters, first in line first. A dispose calls the first one. */
11
+ #line = [];
12
+ /** The permits that holders have not disposed yet, so a second dispose of one permit frees nothing. */
13
+ #held = new Set();
14
+ constructor(permits) {
15
+ if (!(Number.isInteger(permits) && permits > 0))
16
+ throw new RangeError(`permits must be a positive integer, not ${permits}`);
17
+ this.#free = permits;
18
+ }
19
+ /**
20
+ * Gives a permit when one is free, or waits in the line for one. Dispose
21
+ * the permit to give it back: `using permit = await semaphore.acquire(…)`.
22
+ * When the signal aborts, also before the call, the caller takes no permit.
23
+ */
24
+ async acquire({ signal }) {
25
+ signal?.throwIfAborted();
26
+ const free = this.tryAcquire();
27
+ if (free)
28
+ return free;
29
+ const turn = Promise.withResolvers();
30
+ this.#line.push(turn.resolve);
31
+ try {
32
+ await untilAborted(turn.promise, signal);
33
+ }
34
+ catch (error) {
35
+ const place = this.#line.indexOf(turn.resolve);
36
+ // The turn came in the same step as the cancel: the permit passes on.
37
+ if (place === -1)
38
+ this.#release();
39
+ else
40
+ this.#line.splice(place, 1);
41
+ throw error;
42
+ }
43
+ return this.#permit();
44
+ }
45
+ /** Gives a permit only when one is free, which is never while callers wait in the line. */
46
+ tryAcquire() {
47
+ if (this.#free === 0)
48
+ return undefined;
49
+ this.#free--;
50
+ return this.#permit();
51
+ }
52
+ #permit() {
53
+ const permit = {
54
+ [Symbol.dispose]: () => {
55
+ if (this.#held.delete(permit))
56
+ this.#release();
57
+ },
58
+ };
59
+ this.#held.add(permit);
60
+ return permit;
61
+ }
62
+ #release() {
63
+ const next = this.#line.shift();
64
+ if (next)
65
+ next();
66
+ else
67
+ this.#free++;
68
+ }
69
+ }
70
+ //# sourceMappingURL=semaphore.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"semaphore.js","sourceRoot":"","sources":["../src/semaphore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAOlD;;;;;GAKG;AACH,MAAM,OAAO,SAAS;IACpB,KAAK,CAAS;IACd,oFAAoF;IAC3E,KAAK,GAAmB,EAAE,CAAC;IACpC,uGAAuG;IAC9F,KAAK,GAAG,IAAI,GAAG,EAAc,CAAC;IAEvC,YAAY,OAAe;QACzB,IAAI,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC;YAC7C,MAAM,IAAI,UAAU,CAClB,2CAA2C,OAAO,EAAE,CACrD,CAAC;QACJ,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAkB;QACtC,MAAM,EAAE,cAAc,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QAC/B,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;QACtB,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,EAAQ,CAAC;QAC3C,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC9B,IAAI,CAAC;YACH,MAAM,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC3C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC/C,sEAAsE;YACtE,IAAI,KAAK,KAAK,CAAC,CAAC;gBAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;;gBAC7B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACjC,MAAM,KAAK,CAAC;QACd,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;IAED,2FAA2F;IAC3F,UAAU;QACR,IAAI,IAAI,CAAC,KAAK,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QACvC,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;IAED,OAAO;QACL,MAAM,MAAM,GAAe;YACzB,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE;gBACrB,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;oBAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACjD,CAAC;SACF,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACvB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,QAAQ;QACN,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QAChC,IAAI,IAAI;YAAE,IAAI,EAAE,CAAC;;YACZ,IAAI,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;CACF"}
package/dist/timeout.d.ts CHANGED
@@ -2,6 +2,15 @@ import type { Clock } from './clock.ts';
2
2
  export interface TimeoutOptions {
3
3
  /** The clock that the timer runs on: `globalThis` in production, a fake clock in a test. */
4
4
  clock: Clock;
5
+ /**
6
+ * With `true`, the timer keeps the process alive until the signal aborts or
7
+ * until the disposal. Without it, the timer does not keep the process
8
+ * alive, as the timer of `AbortSignal.timeout` does not: `timeout` calls
9
+ * `unref()` on each timer of the clock, when the timer has one. Give `true`
10
+ * when the abort must come also while no other work keeps the process alive
11
+ * (ADR 0012).
12
+ */
13
+ ref?: boolean | undefined;
5
14
  }
6
15
  /** A signal that aborts after a time on a clock. A disposal stops its timer. */
7
16
  export interface Timeout extends Disposable {
@@ -14,6 +23,7 @@ export interface Timeout extends Disposable {
14
23
  * wait ends: `using limit = timeout(ms, { clock })`. The time runs in parts
15
24
  * of at most one timer each, so a timeout longer than one timer can hold
16
25
  * lasts the full time, and the time of a system sleep does not use it up.
26
+ * Without `ref: true`, the timeout does not keep the process alive.
17
27
  */
18
- export declare function timeout(ms: number, { clock }: TimeoutOptions): Timeout;
28
+ export declare function timeout(ms: number, { clock, ref }: TimeoutOptions): Timeout;
19
29
  //# sourceMappingURL=timeout.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../src/timeout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,MAAM,WAAW,cAAc;IAC7B,4FAA4F;IAC5F,KAAK,EAAE,KAAK,CAAC;CACd;AAED,gFAAgF;AAChF,MAAM,WAAW,OAAQ,SAAQ,UAAU;IACzC,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAUD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,EAAE,cAAc,GAAG,OAAO,CA0BtE"}
1
+ {"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../src/timeout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,MAAM,WAAW,cAAc;IAC7B,4FAA4F;IAC5F,KAAK,EAAE,KAAK,CAAC;IACb;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC3B;AAED,gFAAgF;AAChF,MAAM,WAAW,OAAQ,SAAQ,UAAU;IACzC,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAUD;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,cAAc,GAAG,OAAO,CA2B3E"}
package/dist/timeout.js CHANGED
@@ -1,4 +1,4 @@
1
- import { TIMER_MAX } from "./delay.js";
1
+ import { TIMER_MAX, unref } from "./delay.js";
2
2
  // The number of parts in which a timeout counts its time. A timer of Node.js
3
3
  // on macOS counts the time of a system sleep, so a timer that was running
4
4
  // when the computer slept fires at the wake. Each part is one timer, and a
@@ -12,8 +12,9 @@ const PARTS = 10;
12
12
  * wait ends: `using limit = timeout(ms, { clock })`. The time runs in parts
13
13
  * of at most one timer each, so a timeout longer than one timer can hold
14
14
  * lasts the full time, and the time of a system sleep does not use it up.
15
+ * Without `ref: true`, the timeout does not keep the process alive.
15
16
  */
16
- export function timeout(ms, { clock }) {
17
+ export function timeout(ms, { clock, ref }) {
17
18
  const controller = new AbortController();
18
19
  const part = Math.min(Math.max(Math.ceil(ms / PARTS), 1), TIMER_MAX);
19
20
  let timer;
@@ -25,6 +26,8 @@ export function timeout(ms, { clock }) {
25
26
  }
26
27
  controller.abort(new DOMException('The operation was aborted due to timeout', 'TimeoutError'));
27
28
  }, Math.min(left, part));
29
+ if (ref !== true)
30
+ unref(timer);
28
31
  };
29
32
  count(ms);
30
33
  return {
@@ -1 +1 @@
1
- {"version":3,"file":"timeout.js","sourceRoot":"","sources":["../src/timeout.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAavC,6EAA6E;AAC7E,0EAA0E;AAC1E,2EAA2E;AAC3E,8EAA8E;AAC9E,4EAA4E;AAC5E,UAAU;AACV,MAAM,KAAK,GAAG,EAAE,CAAC;AAEjB;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,EAAU,EAAE,EAAE,KAAK,EAAkB;IAC3D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACrE,IAAI,KAAc,CAAC;IACnB,MAAM,KAAK,GAAG,CAAC,IAAY,EAAQ,EAAE;QACnC,KAAK,GAAG,KAAK,CAAC,UAAU,CACtB,GAAG,EAAE;YACH,IAAI,IAAI,GAAG,IAAI,EAAE,CAAC;gBAChB,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;gBACnB,OAAO;YACT,CAAC;YACD,UAAU,CAAC,KAAK,CACd,IAAI,YAAY,CACd,0CAA0C,EAC1C,cAAc,CACf,CACF,CAAC;QACJ,CAAC,EACD,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CACrB,CAAC;IACJ,CAAC,CAAC;IACF,KAAK,CAAC,EAAE,CAAC,CAAC;IACV,OAAO;QACL,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC;KAClD,CAAC;AACJ,CAAC"}
1
+ {"version":3,"file":"timeout.js","sourceRoot":"","sources":["../src/timeout.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAsB9C,6EAA6E;AAC7E,0EAA0E;AAC1E,2EAA2E;AAC3E,8EAA8E;AAC9E,4EAA4E;AAC5E,UAAU;AACV,MAAM,KAAK,GAAG,EAAE,CAAC;AAEjB;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CAAC,EAAU,EAAE,EAAE,KAAK,EAAE,GAAG,EAAkB;IAChE,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACrE,IAAI,KAAc,CAAC;IACnB,MAAM,KAAK,GAAG,CAAC,IAAY,EAAQ,EAAE;QACnC,KAAK,GAAG,KAAK,CAAC,UAAU,CACtB,GAAG,EAAE;YACH,IAAI,IAAI,GAAG,IAAI,EAAE,CAAC;gBAChB,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;gBACnB,OAAO;YACT,CAAC;YACD,UAAU,CAAC,KAAK,CACd,IAAI,YAAY,CACd,0CAA0C,EAC1C,cAAc,CACf,CACF,CAAC;QACJ,CAAC,EACD,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CACrB,CAAC;QACF,IAAI,GAAG,KAAK,IAAI;YAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC,CAAC;IACF,KAAK,CAAC,EAAE,CAAC,CAAC;IACV,OAAO;QACL,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC;KAClD,CAAC;AACJ,CAAC"}
@@ -0,0 +1,23 @@
1
+ export interface WaitOptions {
2
+ /** Cancels the wait: the wait rejects with `signal.reason`. The count does not change. */
3
+ signal: AbortSignal | undefined;
4
+ }
5
+ /**
6
+ * Counts the work in flight, and lets callers wait until the count is zero.
7
+ * Each `add` gives a token, and the group counts the token until a dispose.
8
+ * The count can go up again after zero, as a Go `sync.WaitGroup` can: each
9
+ * time the count reaches zero, each wait that started before that zero
10
+ * ends.
11
+ */
12
+ export declare class WaitGroup {
13
+ #private;
14
+ /** Counts one more work until the token is disposed: `using _work = group.add()`. */
15
+ add(): Disposable;
16
+ /**
17
+ * Ends at once when the count is zero, else when the count next reaches
18
+ * zero, also when an `add` follows in the same step. When the signal
19
+ * aborts, also before the call, the wait rejects with its reason.
20
+ */
21
+ wait({ signal }: WaitOptions): Promise<void>;
22
+ }
23
+ //# sourceMappingURL=wait-group.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"wait-group.d.ts","sourceRoot":"","sources":["../src/wait-group.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,WAAW;IAC1B,0FAA0F;IAC1F,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;CACjC;AAED;;;;;;GAMG;AACH,qBAAa,SAAS;;IAMpB,qFAAqF;IACrF,GAAG,IAAI,UAAU;IAajB;;;;OAIG;IACG,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAKnD"}
@@ -0,0 +1,40 @@
1
+ import { Latch } from "./latch.js";
2
+ import { untilAborted } from "./until-aborted.js";
3
+ /**
4
+ * Counts the work in flight, and lets callers wait until the count is zero.
5
+ * Each `add` gives a token, and the group counts the token until a dispose.
6
+ * The count can go up again after zero, as a Go `sync.WaitGroup` can: each
7
+ * time the count reaches zero, each wait that started before that zero
8
+ * ends.
9
+ */
10
+ export class WaitGroup {
11
+ /** The tokens that their holders have not disposed yet, so a second dispose of one token counts nothing. */
12
+ #tokens = new Set();
13
+ /** Opens when the count next reaches zero. A new latch then takes its place for the waits after that zero. */
14
+ #zero = new Latch();
15
+ /** Counts one more work until the token is disposed: `using _work = group.add()`. */
16
+ add() {
17
+ const token = {
18
+ [Symbol.dispose]: () => {
19
+ if (this.#tokens.delete(token) && this.#tokens.size === 0) {
20
+ this.#zero.open();
21
+ this.#zero = new Latch();
22
+ }
23
+ },
24
+ };
25
+ this.#tokens.add(token);
26
+ return token;
27
+ }
28
+ /**
29
+ * Ends at once when the count is zero, else when the count next reaches
30
+ * zero, also when an `add` follows in the same step. When the signal
31
+ * aborts, also before the call, the wait rejects with its reason.
32
+ */
33
+ async wait({ signal }) {
34
+ signal?.throwIfAborted();
35
+ if (this.#tokens.size === 0)
36
+ return;
37
+ await untilAborted(this.#zero.wait(), signal);
38
+ }
39
+ }
40
+ //# sourceMappingURL=wait-group.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"wait-group.js","sourceRoot":"","sources":["../src/wait-group.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAOlD;;;;;;GAMG;AACH,MAAM,OAAO,SAAS;IACpB,4GAA4G;IACnG,OAAO,GAAG,IAAI,GAAG,EAAc,CAAC;IACzC,8GAA8G;IAC9G,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC;IAEpB,qFAAqF;IACrF,GAAG;QACD,MAAM,KAAK,GAAe;YACxB,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE;gBACrB,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;oBAC1D,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;oBAClB,IAAI,CAAC,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC;gBAC3B,CAAC;YACH,CAAC;SACF,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACxB,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAe;QAChC,MAAM,EAAE,cAAc,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO;QACpC,MAAM,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC;IAChD,CAAC;CACF"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zukhruf/async",
3
- "version": "0.8.23",
3
+ "version": "0.8.25",
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": {