@zukhruf/async 0.3.19 → 0.3.20

package/README.md

@@ -1,6 +1,6 @@
 # @zukhruf/async
 
-Helpers for code that waits for promises: `untilAborted` cancels a wait, and `Latch` holds callers until something happened. `@zukhruf/mutex` and `@zukhruf/single-flight` use them.
+Helpers for code that waits for promises: `untilAborted` cancels a wait, `Latch` holds callers until something happened, and `poll` calls an attempt again until it gives a value. `@zukhruf/mutex`, `@zukhruf/single-flight` and `@zukhruf/election` use them.
 
 The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
 
@@ -53,3 +53,38 @@ const value = await done.wait(); // 'report'
 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).
 
 To stop a wait on a latch, cancel it: `untilAborted(latch.wait(), signal)`.
+
+## Poll an attempt until it gives a value
+
+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.
+
+```ts
+import { poll } from '@zukhruf/async';
+
+// queue.take() gives the next job, or undefined when the queue is empty.
+const job = await poll(() => queue.take(), { interval: 100, signal });
+```
+
+- Only `undefined` means "no value yet". `null`, `0` and `false` are values.
+- An error from the attempt rejects `poll` with the same error. `poll` does not call the attempt again after an error. To try an operation again after an error, see `patiently` of `@zukhruf/fs`.
+- When `signal` aborts during a wait, `poll` stops the timer of the wait and rejects with the reason of the signal. A cancel does not stop an attempt that runs.
+
+### Stop at a deadline
+
+A deadline is a time from `performance.now()`, not a duration. After the deadline, an attempt that gives `undefined` resolves `poll` with `undefined`. An attempt that gives a value still resolves `poll` with the value.
+
+```ts
+const deadline = performance.now() + 5_000;
+const job = await poll(() => queue.take(), {
+  interval: 100,
+  signal: undefined,
+  deadline,
+});
+// job is undefined when the queue stayed empty for 5 seconds.
+```
+
+- The first attempt always occurs, also when the deadline is already in the past. Thus a deadline of `performance.now()` gives one attempt.
+- One deadline can stop many polls. A campaign of `@zukhruf/election` uses one deadline for all its attempts.
+- Without a deadline, the type of the result has no `undefined`.
+
+See [ADR 0003](./docs/adr/0003-the-election-and-the-file-lock-stores-poll-through-one-function.md).

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { Latch } from './latch.ts';
+export { poll, type PollOptions } from './poll.ts';
 export { untilAborted } from './until-aborted.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export { Latch } from "./latch.js";
+export { poll } from "./poll.js";
 export { untilAborted } from "./until-aborted.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAoB,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/poll.d.ts

@@ -0,0 +1,23 @@
+export interface PollOptions {
+    /** Milliseconds to wait after an attempt that gave nothing. */
+    interval: number;
+    /** Stops the wait between two attempts. The poll then rejects with `signal.reason`. */
+    signal: AbortSignal | undefined;
+    /**
+     * A `performance.now()` time. After it, an attempt that gives nothing
+     * resolves the poll with `undefined`. The first attempt always occurs.
+     */
+    deadline?: number | undefined;
+}
+/**
+ * Calls `attempt` until it gives a value other than `undefined`, and waits
+ * `interval` between two attempts. An error from `attempt` rejects the poll
+ * unchanged.
+ */
+export declare function poll<T>(attempt: () => Promise<T | undefined>, options: PollOptions & {
+    deadline: number;
+}): Promise<T | undefined>;
+export declare function poll<T>(attempt: () => Promise<T | undefined>, options: PollOptions & {
+    deadline?: undefined;
+}): Promise<T>;
+//# sourceMappingURL=poll.d.ts.map

package/dist/poll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poll.d.ts","sourceRoot":"","sources":["../src/poll.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACpB,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,EACrC,OAAO,EAAE,WAAW,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC1C,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;AAC1B,wBAAgB,IAAI,CAAC,CAAC,EACpB,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,EACrC,OAAO,EAAE,WAAW,GAAG;IAAE,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,GAC9C,OAAO,CAAC,CAAC,CAAC,CAAC"}

package/dist/poll.js

@@ -0,0 +1,15 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { untilAborted } from "./until-aborted.js";
+export async function poll(attempt, { interval, signal, deadline }) {
+    for (;;) {
+        const value = await attempt();
+        if (value !== undefined)
+            return value;
+        if (deadline !== undefined && performance.now() >= deadline) {
+            return undefined;
+        }
+        // delay's signal frees the timer; untilAborted rejects with the reason.
+        await untilAborted(delay(interval, undefined, { signal }), signal);
+    }
+}
+//# sourceMappingURL=poll.js.map

package/dist/poll.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"poll.js","sourceRoot":"","sources":["../src/poll.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AA2BlD,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,OAAqC,EACrC,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAe;IAE3C,SAAS,CAAC;QACR,MAAM,KAAK,GAAG,MAAM,OAAO,EAAE,CAAC;QAC9B,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QACtC,IAAI,QAAQ,KAAK,SAAS,IAAI,WAAW,CAAC,GAAG,EAAE,IAAI,QAAQ,EAAE,CAAC;YAC5D,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,wEAAwE;QACxE,MAAM,YAAY,CAAC,KAAK,CAAC,QAAQ,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IACrE,CAAC;AACH,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zukhruf/async",
-  "version": "0.3.19",
-  "description": "Helpers for code that waits for promises: cancel a wait when an AbortSignal aborts, and hold callers on a one-shot latch that never rejects.",
+  "version": "0.3.20",
+  "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.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,7 +18,9 @@
     "abortable",
     "promise",
     "async",
-    "latch"
+    "latch",
+    "poll",
+    "polling"
   ],
   "type": "module",
   "types": "./dist/index.d.ts",