@zukhruf/async 0.3.20 → 0.3.21

package/README.md

@@ -87,4 +87,19 @@ const job = await poll(() => queue.take(), {
 - 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`.
 
+### Let the process end during a poll
+
+A Node.js process ends when it has no more work. A timer is work. Thus the wait between two attempts keeps the process alive. Some polls run in the background, and their process must be able to end during the poll. For example, a server that does not keep its process alive must not watch a lock with a poll that does.
+
+For such a poll, give `ref: false`. Then the wait does not keep the process alive. The process can end while the poll is pending, and the poll then never resolves.
+
+```ts
+// The worker takes jobs, but it does not keep the process alive.
+poll(() => queue.take(), { interval: 100, signal, ref: false }).then(run);
+```
+
+- `ref` is the `ref` option of the Node.js timer (`setTimeout` of `node:timers/promises`). `poll` gives it to the timer unchanged.
+- Without `ref`, Node.js keeps its default: the wait keeps the process alive.
+- `ref` changes only the wait between two attempts. An attempt that runs can keep the process alive.
+
 See [ADR 0003](./docs/adr/0003-the-election-and-the-file-lock-stores-poll-through-one-function.md).

package/dist/poll.d.ts

@@ -8,6 +8,12 @@ export interface PollOptions {
      * resolves the poll with `undefined`. The first attempt always occurs.
      */
     deadline?: number | undefined;
+    /**
+     * The `ref` of the Node.js timer of the wait between two attempts. With
+     * `false`, the wait does not keep the process alive: the process can end
+     * while the poll is pending. Without it, Node.js keeps its default.
+     */
+    ref?: boolean;
 }
 /**
  * Calls `attempt` until it gives a value other than `undefined`, and waits

package/dist/poll.d.ts.map

@@ -1 +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"}
+{"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;IAC9B;;;;OAIG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;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

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

package/dist/poll.js.map

@@ -1 +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"}
+{"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;AAiClD,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,OAAqC,EACrC,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAe;IAEhD,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,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zukhruf/async",
-  "version": "0.3.20",
+  "version": "0.3.21",
   "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": {
@@ -23,7 +23,6 @@
     "polling"
   ],
   "type": "module",
-  "types": "./dist/index.d.ts",
   "exports": {
     "./package.json": "./package.json",
     ".": {