@randajan/pulse 1.1.4 → 2.0.0

package/README.md

@@ -9,7 +9,7 @@
 
 ## Overview
 
-**@randajan/pulse** is a tiny, zero‑dependency scheduler that fires your callback at *wall‑clock‑aligned* intervals. It focuses on precision (no drift), clarity and graceful error handling, so you can drive heart‑beat logic, telemetry or background maintenance tasks with just a few lines of code.
+**@randajan/pulse** is a tiny, zero‑dependency scheduler that fires your callback on aligned or relative intervals. It focuses on precision, clarity and graceful error handling, so you can drive heart‑beat logic, telemetry or background maintenance tasks with just a few lines of code.
 
 The package ships dual builds—**ESM** *and* **CommonJS**—and works the same in Node.js and the browser.
 
@@ -32,10 +32,11 @@ import createPulse from "@randajan/pulse";
 
 const pulse = createPulse({
   interval: 1000,                // 1 second
-  onPulse: meta => {
+  align: true,                   // align to wall-clock time
+  onPulse: (pulse, meta) => {
     console.log("tick", meta.runtime, "ms");
   },
-  onError: err => console.error("Pulse error:", err),
+  onError: (pulse, meta) => console.error("Pulse error:", meta.error),
   autoStart: true               // start immediately
 });
 
@@ -43,12 +44,14 @@ const pulse = createPulse({
 setTimeout(() => pulse.stop(), 10_000);
 ```
 
-Every time **onPulse** runs it receives a fresh metadata object:
+Every time **onPulse** runs it receives the pulse instance and a fresh metadata object:
 
 ```ts
 interface PulseMeta {
+  readonly id:       number;
   readonly started:  Date;
   readonly runtime:  number;            // ms since started
+  readonly lateBy:   number;            // ms over interval runtime
   readonly warnings: string[];
   warn(w: string | Error): void;        // push warning
 }
@@ -61,17 +64,61 @@ interface PulseMeta {
 | Option      | Type       | Required | Default            | Description                                                        |
 | ----------- | ---------- | -------- | ------------------ | ------------------------------------------------------------------ |
 | `interval`  | `number`   | ✔︎       | —                  | Period in ms. Min **10 ms**, max **2 147 483 647 ms** (\~24 days). |
-| `offset`    | `number`   |          | `0`                | Fixed shift applied to every pulse (0 ≤ offset < interval).        |
+| `align`     | `boolean`  | ✔︎       | —                  | If `true`, pulse is aligned to wall-clock interval edges. If `false`, pulse runs relatively from start. |
+| `offset`    | `number`   |          | `0`                | Timing offset. Range and meaning depend on `align`; see below.     |
+| `maxRuns`   | `number`   |          | `0`                | Maximum number of pulses before automatic stop. `0` means unlimited. |
 | `getNow`    | `function` |          | `() => Date.now()` | Custom clock—handy for deterministic tests or time travel.         |
 | `autoStart` | `boolean`  |          | `false`            | If `true`, the scheduler starts right after construction.          |
-| `noMeta` | `boolean`  |          | `false`            | If `false`, the scheduler creates metadata `PuleMeta` at runtime        |
-| `onPulse`   | `function` | ✔︎       | —                  | Async/sync callback executed on each pulse. Receives `PulseMeta`.  |
-| `onError`   | `function` |          | `() => {}`         | Called when `onPulse` throws or rejects.                           |
+| `runOnStart` | `boolean` |          | `false`            | If `true`, the first pulse is scheduled immediately on start.      |
+| `noMeta` | `boolean`  |          | `false`            | If `true`, callbacks receive the numeric pulse id instead of `PulseMeta`. |
+| `onPulse`   | `function` | ✔︎       | —                  | Async/sync callback executed on each pulse. Receives `(pulse, meta)`.  |
+| `onError`   | `function` |          | `() => {}`         | Called when `onPulse` throws or rejects. Receives `(pulse, meta)`, or `(pulse, error, id)` with `noMeta: true`. |
 | `onStart`   | `function` |          | `() => {}`         | Called right before pulse starts.                          |
 | `onStop`   | `function` |          | `() => {}`         | Called right after pulse stops.                            |
-| `afterPulse`   | `function` |        | `() => {}`        | Async/sync callback executed after each pulse even if the onPulse raises an error. Receives `PulseMeta`.  |
+| `afterPulse`   | `function` |        | `() => {}`        | Async/sync callback executed after each pulse even if `onPulse` raises an error. Receives `(pulse, meta)`.  |
 
 
+### `align` and `offset`
+
+With `align: true`, pulses are scheduled on wall-clock interval edges shifted by `offset`. In this mode `offset` must be between `0` and `interval`.
+
+```js
+createPulse({
+  align: true,
+  interval: 60_000,
+  offset: 30_000,
+  onPulse: () => console.log("fires around every minute at :30")
+});
+```
+
+With `align: false`, the first pulse is delayed by `interval + offset`; every following pulse uses `interval`. In this mode `offset` can be negative down to `-interval`, or positive as long as `interval + offset` does not exceed the maximum JavaScript timer delay.
+
+```js
+createPulse({
+  align: false,
+  interval: 5_000,
+  offset: -4_000,
+  onPulse: () => console.log("first fire after 1s, then every 5s")
+});
+```
+
+In Node.js, Pulse calls `timeout.unref?.()` for its internal timers. A running pulse will not keep an otherwise idle Node process alive.
+
+### `runOnStart`
+
+With `runOnStart: true`, the first pulse is scheduled with a `0` ms delay when `start()` is called. The callback still runs asynchronously through the scheduler, not directly inside `start()`.
+
+```js
+createPulse({
+  align: false,
+  interval: 60_000,
+  runOnStart: true,
+  onPulse: () => console.log("runs now, then every minute")
+});
+```
+
+`runOnStart` only affects the initial plan after `start()`. After the first pulse completes, the next pulse is scheduled normally: aligned to the wall-clock grid when `align: true`, or after `interval` when `align: false`.
+
 ---
 
 ## API
@@ -85,17 +132,19 @@ interface PulseMeta {
 | `pulse.restart()`         | `boolean` | Call pulse.stop() and then pulse.start() |
 | `pulse.reset()`         | `boolean` | Resets nextId counter |
 | `pulse.state`          | `boolean` | `true` = running, `false` = stopped (read-only)                 |
-| `pulse.nextId`          | `number` | next pulse id (read-only).              |
+| `pulse.align`          | `boolean` | Alignment mode (read-only).                          |
 | `pulse.interval`       | `number`  | Interval in ms (read‑only).                          |
 | `pulse.offset`         | `number`  | Offset in ms (read‑only).                            |
-| `pulse.countdown`         | `number`  | number of ms that remains to the next pulse        |
-| `pulse.last`         | `number`  | if noMeta=true there will be last result, else there will be last metadata         |
+| `pulse.countdown`         | `number\|undefined`  | Real ms remaining to the currently scheduled pulse; `undefined` while stopped. |
+| `pulse.potential`         | `number`  | Real countdown while running, otherwise ms that would be used by the next `start()`; returns `0` when `runOnStart` applies. |
+| `pulse.nextAt`         | `number\|undefined`  | Timestamp of the next scheduled pulse while running. |
+| `pulse.last`         | `any\|PulseMeta`  | Last callback result with `noMeta: true`; otherwise last metadata. |
 
 ---
 
 ## Why not `setInterval`?
 
-`setInterval` drifts: extra work inside the callback pushes the next tick further, eventually desynchronising your schedule. **Pulse** recalculates the next edge *after* each run and keeps the loop tightly aligned to the original wall‑clock grid.
+`setInterval` drifts: extra work inside the callback pushes the next tick further, eventually desynchronising your schedule. With `align: true`, **Pulse** recalculates the next edge *after* each run and keeps the loop tightly aligned to the wall-clock grid. With `align: false`, it runs as a promise-friendly relative scheduler.
 
 ---
 
@@ -107,8 +156,9 @@ JavaScript timers accept at most **2 147 483 647 ms**. To wait longer, ch
 
 ```js
 createPulse({
+  align: false,
   interval: 2_147_483_647,
-  onPulse: async meta => {
+  onPulse: async (pulse, meta) => {
     if (stillWaiting()) return;   // keep sleeping…
     // …real logic here
   },
@@ -122,4 +172,3 @@ createPulse({
 ## License
 
 MIT © [randajan](https://github.com/randajan)
-

package/dist/cjs/index.cjs

@@ -27,7 +27,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/Pulse.js
-var import_props2 = require("@randajan/props");
+var import_props3 = require("@randajan/props");
 
 // src/const.js
 var _pulses = /* @__PURE__ */ new Map();
@@ -62,17 +62,172 @@ var validRange = (min, max, any, req = false, msg = "argument") => {
   return num;
 };
 
-// src/metadata.js
+// src/static/options.js
+var formatOptions = (options) => {
+  const o = {};
+  o.getNow = valid("function", options.getNow, false, "options.getNow") || ((_) => Date.now());
+  o.align = valid("boolean", options.align, true, "options.align");
+  const minInterval = 10;
+  const maxInterval = 2147483647;
+  o.interval = validRange(minInterval, maxInterval, options.interval, true, "options.interval");
+  o.runOnStart = valid("boolean", options.runOnStart, false, "options.runOnStart") || false;
+  const offsetMsg = `options.offset (align:${o.align})`;
+  if (o.align) {
+    o.offset = validRange(0, o.interval, options.offset, false, offsetMsg) ?? 0;
+  } else if (!o.runOnStart) {
+    o.offset = validRange(-o.interval, maxInterval - o.interval, options.offset, false, offsetMsg) ?? 0;
+  } else if (options.offset != null) {
+    throw new Error(`${offsetMsg} can't be set if runOnStart:true`);
+  } else {
+    o.offset = -o.interval;
+  }
+  o.maxRuns = validRange(0, Infinity, options.maxRuns, false, "options.maxRuns") ?? 0;
+  o.onPulse = valid("function", options.onPulse, true, "options.onPulse");
+  o.onStart = valid("function", options.onStart, false, "options.onStart") || blankFn;
+  o.onStop = valid("function", options.onStop, false, "options.onStop") || blankFn;
+  o.onError = valid("function", options.onError, false, "options.onError") || blankFn;
+  o.afterPulse = valid("function", options.afterPulse, false, "options.afterPulse") || blankFn;
+  o.autoStart = valid("boolean", options.autoStart, false, "options.autoStart") || false;
+  o.noMeta = valid("boolean", options.noMeta, false, "option.noMeta") || false;
+  return Object.freeze(o);
+};
+
+// src/static/PulsePrivate.js
+var import_props2 = require("@randajan/props");
+
+// src/static/metadata.js
 var import_props = require("@randajan/props");
-var createMetaData = (id, getNow) => {
-  const p = {};
+var createMetaData = (_p, id) => {
+  const md = {};
   const w = [];
-  (0, import_props.solid)(p, "id", id);
-  (0, import_props.solid)(p, "started", getNow());
-  (0, import_props.virtual)(p, "warnings", (_) => [...w]);
-  (0, import_props.virtual)(p, "runtime", (_) => (p.ended ? p.ended : getNow()) - p.started);
-  (0, import_props.solid)(p, "warn", (warning) => w.push(warning), false);
-  return p;
+  (0, import_props.solid)(md, "id", id);
+  (0, import_props.solid)(md, "started", _p.opt.getNow());
+  (0, import_props.virtual)(md, "warnings", (_) => [...w]);
+  (0, import_props.virtual)(md, "runtime", (_) => (md.ended ? md.ended : _p.opt.getNow()) - md.started);
+  (0, import_props.virtual)(md, "lateBy", (_) => Math.max(0, md.runtime - _p.opt.interval));
+  (0, import_props.solid)(md, "warn", (warning) => w.push(warning), false);
+  return md;
+};
+
+// src/static/PulsePrivate.js
+var PulsePrivate = class {
+  constructor(pulse, options) {
+    this.pulse = pulse;
+    this.state = false;
+    this.nextId = 0;
+    this.opt = formatOptions(options);
+    this.run = this.run.bind(this);
+  }
+  getCountdown() {
+    const { state, fireAt, opt: { getNow } } = this;
+    if (!state || fireAt == null) {
+      return;
+    }
+    return Math.max(0, fireAt - getNow());
+  }
+  getPotential(isInit = true) {
+    const { opt: { align, runOnStart, interval, offset, getNow } } = this;
+    if (isInit && runOnStart) {
+      return 0;
+    }
+    if (!align) {
+      return isInit ? interval + offset : interval;
+    }
+    const now = getNow() - offset;
+    const rest = (now % interval + interval) % interval;
+    return rest === 0 ? interval : interval - rest;
+  }
+  reset() {
+    this.nextId = 0;
+    return true;
+  }
+  start(reset = false) {
+    const { pulse, state, timeoutId, opt: { onStart } } = this;
+    if (state) {
+      return false;
+    }
+    onStart(pulse);
+    if (reset) {
+      this.reset();
+    }
+    this.state = true;
+    return this.plan(true);
+  }
+  stop(reset = false) {
+    const { pulse, state, timeoutId, opt: { onStop } } = this;
+    if (!state) {
+      return false;
+    }
+    clearTimeout(timeoutId);
+    this.state = false;
+    delete this.fireAt;
+    if (reset) {
+      this.reset();
+    }
+    onStop(pulse);
+    return true;
+  }
+  plan(isInit) {
+    const { state, metaData, nextId, opt: { maxRuns, getNow } } = this;
+    if (!state || metaData != null) {
+      return false;
+    }
+    if (maxRuns && maxRuns <= nextId) {
+      this.stop(true);
+      return false;
+    }
+    const fireIn = this.getPotential(isInit);
+    this.fireAt = getNow() + fireIn;
+    this.timeoutId = setTimeout(this.run, fireIn);
+    this.timeoutId.unref?.();
+    return true;
+  }
+  async run() {
+    const { pulse, state, metaData, opt: { noMeta, getNow, onPulse, onError, afterPulse } } = this;
+    if (!state || metaData) {
+      return;
+    }
+    const id = this.nextId++;
+    const md = this.metaData = noMeta ? id : createMetaData(this, id);
+    let errA, errB, result;
+    try {
+      result = await onPulse(pulse, md);
+      if (!noMeta) {
+        (0, import_props2.solid)(md, "result", result);
+      }
+    } catch (err) {
+      errA = err;
+      if (!noMeta) {
+        (0, import_props2.solid)(md, "error", errA);
+      }
+    }
+    if (!noMeta) {
+      (0, import_props2.solid)(md, "ended", getNow());
+    }
+    if (errA != null) {
+      if (noMeta) {
+        onError(pulse, errA, md);
+      } else {
+        onError(pulse, md);
+      }
+    }
+    try {
+      await afterPulse(pulse, md);
+    } catch (err) {
+      errB = err;
+    }
+    this.last = noMeta ? result : md;
+    delete this.metaData;
+    if (errB != null) {
+      this.stop();
+      throw errB;
+    }
+    this.plan(false);
+  }
+  restart(reset) {
+    this.stop(reset);
+    return this.start(reset);
+  }
 };
 
 // src/Pulse.js
@@ -82,78 +237,19 @@ var Pulse = class {
    * @param {PulseOptions} [options={}]  See {@link PulseOptions}.
    */
   constructor(options = {}) {
-    const _p = {
-      state: false,
-      nextId: 0
-    };
-    const getNow = valid("function", options.getNow, false, "options.getNow") || ((_) => Date.now());
-    const interval = validRange(10, 2147483647, options.interval, true, "options.interval");
-    const offset = validRange(0, interval, options.offset, false, "options.offset") || 0;
-    const onPulse = valid("function", options.onPulse, true, "options.onPulse");
-    _p.onStart = valid("function", options.onStart, false, "options.onStart") || blankFn;
-    _p.onStop = valid("function", options.onStop, false, "options.onStop") || blankFn;
-    const onError = valid("function", options.onError, false, "options.onError") || blankFn;
-    const afterPulse = valid("function", options.afterPulse, false, "options.afterPulse") || blankFn;
-    const autoStart = valid("boolean", options.autoStart, false, "options.autoStart") || false;
-    const noMeta = valid("boolean", options.noMeta, false, "option.noMeta") || false;
-    _p.reset = (_) => {
-      _p.nextId = 0;
-    };
-    _p.plan = (_) => {
-      if (!_p.state || _p.metaData != null) {
-        return;
-      }
-      _p.timeoutId = setTimeout(_p.run, this.countdown);
-    };
-    _p.run = async (_) => {
-      if (!_p.state || _p.metaData) {
-        return;
-      }
-      const id = _p.nextId++;
-      const md = _p.metaData = noMeta ? id : createMetaData(id, getNow);
-      let errA, errB, result;
-      try {
-        result = await onPulse(this, md);
-        if (!noMeta) {
-          (0, import_props2.solid)(md, "result", result);
-        }
-      } catch (err) {
-        errA = err;
-        if (!noMeta) {
-          (0, import_props2.solid)(md, "error", errA);
-        }
-      }
-      if (!noMeta) {
-        (0, import_props2.solid)(md, "ended", getNow());
-      }
-      if (errA != null) {
-        if (noMeta) {
-          onError(this, errA, md);
-        } else {
-          onError(this, md);
-        }
-      }
-      try {
-        await afterPulse(this, md);
-      } catch (err) {
-        errB = err;
-      }
-      _p.last = noMeta ? result : md;
-      delete _p.metaData;
-      if (errB != null) {
-        _p.state = false;
-        throw errB;
-      }
-      _p.plan();
-    };
-    (0, import_props2.virtuals)(this, {
+    const _p = new PulsePrivate(this, options);
+    const { getNow, align, interval, offset, autoStart } = _p.opt;
+    (0, import_props3.virtuals)(this, {
       state: (_) => _p.state,
       last: (_) => _p.last,
-      countdown: (_) => interval - getNow() % interval + offset
+      countdown: (_) => _p.getCountdown(),
+      potential: (_) => _p.getCountdown() ?? _p.getPotential(),
+      nextAt: (_) => _p.state ? this.potential + getNow() : void 0
     });
-    (0, import_props2.solids)(this, {
+    (0, import_props3.solids)(this, {
       interval,
-      offset
+      offset,
+      align
     });
     _pulses.set(this, _p);
     if (autoStart) {
@@ -165,55 +261,29 @@ var Pulse = class {
    * @returns {boolean} `true` if it started now, `false` if it was already running.
    */
   start(reset = false) {
-    const { state } = this;
-    if (state) {
-      return false;
-    }
-    const _p = _pulses.get(this);
-    _p.onStart(this);
-    if (reset) {
-      _p.reset();
-    }
-    _p.state = true;
-    _p.plan();
-    return true;
+    return _pulses.get(this).start(reset);
   }
   /**
    * Stop the pulse loop (no-op if already stopped).
    * @returns {boolean} `true` if it stopped now, `false` if it was already stopped.
    */
   stop(reset = false) {
-    const { state } = this;
-    if (!state) {
-      return false;
-    }
-    const _p = _pulses.get(this);
-    clearTimeout(_p.timeoutId);
-    _p.state = false;
-    if (reset) {
-      _p.reset();
-    }
-    _p.onStop(this);
-    return true;
-  }
-  reset() {
-    _pulses.get(this).reset();
-    return true;
+    return _pulses.get(this).stop(reset);
   }
   restart(reset = false) {
-    this.stop(reset);
-    return this.start(reset);
+    return _pulses.get(this).restart(reset);
+  }
+  reset() {
+    return _pulses.get(this).reset();
   }
 };
 
-// src/static.js
+// src/index.js
 var createPulse = (options = {}) => new Pulse(options);
 var stopAllPulses = () => {
   for (const [pulse, _pulse] of _pulses.entries()) {
     pulse.stop();
   }
 };
-
-// src/index.js
 var index_default = createPulse;
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../../src/index.js", "../../src/Pulse.js", "../../src/const.js", "../../src/tools.js", "../../src/metadata.js", "../../src/static.js"],
-  "sourcesContent": ["import { Pulse } from \"./Pulse\";\nimport { createPulse, stopAllPulses } from \"./static\";\n\nexport default createPulse;\n\nexport { createPulse, stopAllPulses, Pulse }\n", "import { solid, solids, virtuals } from \"@randajan/props\";\r\nimport { blankFn, _pulses } from \"./const\";\r\nimport { valid, validRange } from \"./tools\";\r\nimport { createMetaData } from \"./metadata\";\r\n\r\n/**\r\n * Periodic scheduler that aligns each callback to exact multiples\r\n * of the given interval (optionally shifted by `offset`).\r\n */\r\nexport class Pulse {\r\n\r\n    /**\r\n     * Create a new Pulse instance.\r\n     * @param {PulseOptions} [options={}]  See {@link PulseOptions}.\r\n     */\r\n    constructor(options = {}) {\r\n        const _p = {\r\n            state: false,\r\n            nextId:0\r\n        }\r\n\r\n        const getNow = valid(\"function\", options.getNow, false, \"options.getNow\") || (_ => Date.now());\r\n\r\n        const interval = validRange(10, 2_147_483_647, options.interval, true, \"options.interval\");\r\n        const offset = (validRange(0, interval, options.offset, false, \"options.offset\") || 0);\r\n\r\n        const onPulse = valid(\"function\", options.onPulse, true, \"options.onPulse\");\r\n        _p.onStart = valid(\"function\", options.onStart, false, \"options.onStart\") || blankFn;\r\n        _p.onStop = valid(\"function\", options.onStop, false, \"options.onStop\") || blankFn;\r\n        \r\n        const onError = valid(\"function\", options.onError, false, \"options.onError\") || blankFn;\r\n        \r\n        const afterPulse = valid(\"function\", options.afterPulse, false, \"options.afterPulse\") || blankFn;\r\n        const autoStart = valid(\"boolean\", options.autoStart, false, \"options.autoStart\") || false;\r\n        const noMeta = valid(\"boolean\", options.noMeta, false, \"option.noMeta\") || false;\r\n\r\n        _p.reset = _=>{\r\n            _p.nextId = 0;\r\n        }\r\n\r\n        _p.plan = _ => {\r\n            if (!_p.state || _p.metaData != null) { return; }\r\n            _p.timeoutId = setTimeout(_p.run, this.countdown);\r\n        }\r\n\r\n        _p.run = async _ => {\r\n            if (!_p.state || _p.metaData) { return; }\r\n\r\n            const id = _p.nextId++;\r\n            const md = _p.metaData = noMeta ? id : createMetaData(id, getNow);\r\n            let errA, errB, result;\r\n\r\n            try {\r\n                result = await onPulse(this, md);\r\n                if (!noMeta) { solid(md, \"result\", result); }\r\n            }\r\n            catch (err) {\r\n                errA = err;\r\n                if (!noMeta) { solid(md, \"error\", errA); }\r\n            }\r\n\r\n            if (!noMeta) { solid(md, \"ended\", getNow()); }\r\n\r\n            if (errA != null) {\r\n                if (noMeta) { onError(this, errA, md); }\r\n                else { onError(this, md); }\r\n            }\r\n\r\n            try { await afterPulse(this, md); }\r\n            catch(err) { errB = err; }\r\n\r\n            _p.last = noMeta ? result : md;\r\n            delete _p.metaData;\r\n\r\n            if (errB != null) {\r\n                _p.state = false;\r\n                throw errB;\r\n            }\r\n            \r\n            _p.plan();\r\n        }\r\n\r\n        virtuals(this, {\r\n            state:_=>_p.state,\r\n            last:_=>_p.last,\r\n            countdown:_=>((interval - getNow() % interval) + offset)\r\n        });\r\n\r\n        solids(this, {\r\n            interval,\r\n            offset\r\n        });\r\n\r\n        _pulses.set(this, _p);\r\n\r\n        if (autoStart) { this.start(); }\r\n    }\r\n\r\n    /**\r\n     * Start the pulse loop (no-op if already running).\r\n     * @returns {boolean} `true` if it started now, `false` if it was already running.\r\n     */\r\n    start(reset=false) {\r\n        const { state } = this;\r\n        if (state) { return false; }\r\n        const _p = _pulses.get(this);\r\n        _p.onStart(this);\r\n        if (reset) { _p.reset(); }\r\n        _p.state = true;\r\n        _p.plan();\r\n        return true;\r\n    }\r\n\r\n    /**\r\n     * Stop the pulse loop (no-op if already stopped).\r\n     * @returns {boolean} `true` if it stopped now, `false` if it was already stopped.\r\n     */\r\n    stop(reset=false) {\r\n        const { state } = this;\r\n        if (!state) { return false; }\r\n        const _p = _pulses.get(this);\r\n        clearTimeout(_p.timeoutId);\r\n        _p.state = false;\r\n        if (reset) { _p.reset(); }\r\n        _p.onStop(this);\r\n        return true;\r\n    }\r\n\r\n    reset() {\r\n        _pulses.get(this).reset();\r\n        return true;\r\n    }\r\n\r\n    restart(reset=false) {\r\n        this.stop(reset);\r\n        return this.start(reset);\r\n    }\r\n\r\n\r\n}", "\r\n\r\n\r\nexport const _pulses = new Map();\r\n\r\nexport const blankFn = ()=>{};", "\r\n\r\nexport const is = (type, any)=>typeof any === type;\r\n\r\nexport const valid = (type, any, req=false, msg=\"argument\")=>{\r\n    if (any == null) {\r\n        if (!req) { return; }\r\n        throw new Error(`${msg} require typeof '${type}'`);\r\n    }\r\n    if (is(type, any)) { return any; }\r\n    throw new Error(`${msg} is not typeof '${type}'`);\r\n}\r\n\r\nexport const validRange = (min, max, any, req=false, msg=\"argument\")=>{\r\n    const num = valid(\"number\", any, req, msg);\r\n    if (num == null) { return; }\r\n    if (num < min) { throw new Error(`${msg} must be greater than ${min}`); }\r\n    if (num > max) { throw new Error(`${msg} must be less than ${max}`); }\r\n    return num;\r\n}", "import { solid, virtual } from \"@randajan/props\";\r\n\r\n\r\n/**\r\n * Metadata object passed to every pulse callback.\r\n * @typedef {Object} PulseMeta\r\n * @property {Date}   started   Timestamp when this pulse began.\r\n * @property {string[]} warnings  Snapshot of all warnings collected so far.\r\n * @property {number} runtime   Milliseconds elapsed since `started`.\r\n * @property {(warning: string|Error) => void} warn  Push a warning into the internal list.\r\n */\r\nexport const createMetaData = (id, getNow) => {\r\n    const p = {};\r\n    const w = [];\r\n    solid(p, \"id\", id);\r\n    solid(p, \"started\", getNow());\r\n    virtual(p, \"warnings\", _ => [...w]);\r\n    virtual(p, \"runtime\", _ => (p.ended ? p.ended : getNow()) - p.started);\r\n    solid(p, \"warn\", warning => w.push(warning), false);\r\n    return p;\r\n}\r\n\r\n/**\r\n * Configuration object for {@link Pulse}.\r\n * @typedef {Object} PulseOptions\r\n * @property {(meta: PulseMeta) => (void|Promise<void>)} onPulse   **required** \u2013 user callback invoked on every pulse.\r\n * @property {number}  interval  **required** \u2013 period length in ms (50 \u2013 2 147 483 647).\r\n * @property {number} [offset=0]   Shift in ms applied to the start of each interval (0 \u2264 offset < interval).\r\n * @property {() => number} [getNow=() => Date.now()]  Custom time source, useful for tests or time travel.\r\n * @property {(err: unknown) => void} [onError=blankFn]  Error handler for exceptions or rejected `onPulse` promises.\r\n * @property {boolean} [autoStart=false]  If true, the loop starts immediately after construction.\r\n */", "import { _pulses } from \"./const\";\r\nimport { Pulse } from \"./Pulse.js\";\r\n\r\n\r\n/**\r\n * Factory helper \u2013 simply calls `new Pulse(options)`.\r\n * @param {PulseOptions} [options={}]  See {@link PulseOptions}.\r\n * @returns {Pulse}\r\n */\r\nexport const createPulse = (options = {}) => new Pulse(options);\r\n\r\n/**\r\n * Process exit helper \u2013 stops all pending pulses.\r\n */\r\n\r\nexport const stopAllPulses = ()=>{\r\n    for (const [pulse, _pulse] of _pulses.entries()) {\r\n        pulse.stop();\r\n    }\r\n}\r\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,IAAAA,gBAAwC;;;ACGjC,IAAM,UAAU,oBAAI,IAAI;AAExB,IAAM,UAAU,MAAI;AAAC;;;ACHrB,IAAM,KAAK,CAAC,MAAM,QAAM,OAAO,QAAQ;AAEvC,IAAM,QAAQ,CAAC,MAAM,KAAK,MAAI,OAAO,MAAI,eAAa;AACzD,MAAI,OAAO,MAAM;AACb,QAAI,CAAC,KAAK;AAAE;AAAA,IAAQ;AACpB,UAAM,IAAI,MAAM,GAAG,GAAG,oBAAoB,IAAI,GAAG;AAAA,EACrD;AACA,MAAI,GAAG,MAAM,GAAG,GAAG;AAAE,WAAO;AAAA,EAAK;AACjC,QAAM,IAAI,MAAM,GAAG,GAAG,mBAAmB,IAAI,GAAG;AACpD;AAEO,IAAM,aAAa,CAAC,KAAK,KAAK,KAAK,MAAI,OAAO,MAAI,eAAa;AAClE,QAAM,MAAM,MAAM,UAAU,KAAK,KAAK,GAAG;AACzC,MAAI,OAAO,MAAM;AAAE;AAAA,EAAQ;AAC3B,MAAI,MAAM,KAAK;AAAE,UAAM,IAAI,MAAM,GAAG,GAAG,yBAAyB,GAAG,EAAE;AAAA,EAAG;AACxE,MAAI,MAAM,KAAK;AAAE,UAAM,IAAI,MAAM,GAAG,GAAG,sBAAsB,GAAG,EAAE;AAAA,EAAG;AACrE,SAAO;AACX;;;ACnBA,mBAA+B;AAWxB,IAAM,iBAAiB,CAAC,IAAI,WAAW;AAC1C,QAAM,IAAI,CAAC;AACX,QAAM,IAAI,CAAC;AACX,0BAAM,GAAG,MAAM,EAAE;AACjB,0BAAM,GAAG,WAAW,OAAO,CAAC;AAC5B,4BAAQ,GAAG,YAAY,OAAK,CAAC,GAAG,CAAC,CAAC;AAClC,4BAAQ,GAAG,WAAW,QAAM,EAAE,QAAQ,EAAE,QAAQ,OAAO,KAAK,EAAE,OAAO;AACrE,0BAAM,GAAG,QAAQ,aAAW,EAAE,KAAK,OAAO,GAAG,KAAK;AAClD,SAAO;AACX;;;AHXO,IAAM,QAAN,MAAY;AAAA;AAAA;AAAA;AAAA;AAAA,EAMf,YAAY,UAAU,CAAC,GAAG;AACtB,UAAM,KAAK;AAAA,MACP,OAAO;AAAA,MACP,QAAO;AAAA,IACX;AAEA,UAAM,SAAS,MAAM,YAAY,QAAQ,QAAQ,OAAO,gBAAgB,MAAM,OAAK,KAAK,IAAI;AAE5F,UAAM,WAAW,WAAW,IAAI,YAAe,QAAQ,UAAU,MAAM,kBAAkB;AACzF,UAAM,SAAU,WAAW,GAAG,UAAU,QAAQ,QAAQ,OAAO,gBAAgB,KAAK;AAEpF,UAAM,UAAU,MAAM,YAAY,QAAQ,SAAS,MAAM,iBAAiB;AAC1E,OAAG,UAAU,MAAM,YAAY,QAAQ,SAAS,OAAO,iBAAiB,KAAK;AAC7E,OAAG,SAAS,MAAM,YAAY,QAAQ,QAAQ,OAAO,gBAAgB,KAAK;AAE1E,UAAM,UAAU,MAAM,YAAY,QAAQ,SAAS,OAAO,iBAAiB,KAAK;AAEhF,UAAM,aAAa,MAAM,YAAY,QAAQ,YAAY,OAAO,oBAAoB,KAAK;AACzF,UAAM,YAAY,MAAM,WAAW,QAAQ,WAAW,OAAO,mBAAmB,KAAK;AACrF,UAAM,SAAS,MAAM,WAAW,QAAQ,QAAQ,OAAO,eAAe,KAAK;AAE3E,OAAG,QAAQ,OAAG;AACV,SAAG,SAAS;AAAA,IAChB;AAEA,OAAG,OAAO,OAAK;AACX,UAAI,CAAC,GAAG,SAAS,GAAG,YAAY,MAAM;AAAE;AAAA,MAAQ;AAChD,SAAG,YAAY,WAAW,GAAG,KAAK,KAAK,SAAS;AAAA,IACpD;AAEA,OAAG,MAAM,OAAM,MAAK;AAChB,UAAI,CAAC,GAAG,SAAS,GAAG,UAAU;AAAE;AAAA,MAAQ;AAExC,YAAM,KAAK,GAAG;AACd,YAAM,KAAK,GAAG,WAAW,SAAS,KAAK,eAAe,IAAI,MAAM;AAChE,UAAI,MAAM,MAAM;AAEhB,UAAI;AACA,iBAAS,MAAM,QAAQ,MAAM,EAAE;AAC/B,YAAI,CAAC,QAAQ;AAAE,mCAAM,IAAI,UAAU,MAAM;AAAA,QAAG;AAAA,MAChD,SACO,KAAK;AACR,eAAO;AACP,YAAI,CAAC,QAAQ;AAAE,mCAAM,IAAI,SAAS,IAAI;AAAA,QAAG;AAAA,MAC7C;AAEA,UAAI,CAAC,QAAQ;AAAE,iCAAM,IAAI,SAAS,OAAO,CAAC;AAAA,MAAG;AAE7C,UAAI,QAAQ,MAAM;AACd,YAAI,QAAQ;AAAE,kBAAQ,MAAM,MAAM,EAAE;AAAA,QAAG,OAClC;AAAE,kBAAQ,MAAM,EAAE;AAAA,QAAG;AAAA,MAC9B;AAEA,UAAI;AAAE,cAAM,WAAW,MAAM,EAAE;AAAA,MAAG,SAC5B,KAAK;AAAE,eAAO;AAAA,MAAK;AAEzB,SAAG,OAAO,SAAS,SAAS;AAC5B,aAAO,GAAG;AAEV,UAAI,QAAQ,MAAM;AACd,WAAG,QAAQ;AACX,cAAM;AAAA,MACV;AAEA,SAAG,KAAK;AAAA,IACZ;AAEA,gCAAS,MAAM;AAAA,MACX,OAAM,OAAG,GAAG;AAAA,MACZ,MAAK,OAAG,GAAG;AAAA,MACX,WAAU,OAAK,WAAW,OAAO,IAAI,WAAY;AAAA,IACrD,CAAC;AAED,8BAAO,MAAM;AAAA,MACT;AAAA,MACA;AAAA,IACJ,CAAC;AAED,YAAQ,IAAI,MAAM,EAAE;AAEpB,QAAI,WAAW;AAAE,WAAK,MAAM;AAAA,IAAG;AAAA,EACnC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,QAAM,OAAO;AACf,UAAM,EAAE,MAAM,IAAI;AAClB,QAAI,OAAO;AAAE,aAAO;AAAA,IAAO;AAC3B,UAAM,KAAK,QAAQ,IAAI,IAAI;AAC3B,OAAG,QAAQ,IAAI;AACf,QAAI,OAAO;AAAE,SAAG,MAAM;AAAA,IAAG;AACzB,OAAG,QAAQ;AACX,OAAG,KAAK;AACR,WAAO;AAAA,EACX;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,KAAK,QAAM,OAAO;AACd,UAAM,EAAE,MAAM,IAAI;AAClB,QAAI,CAAC,OAAO;AAAE,aAAO;AAAA,IAAO;AAC5B,UAAM,KAAK,QAAQ,IAAI,IAAI;AAC3B,iBAAa,GAAG,SAAS;AACzB,OAAG,QAAQ;AACX,QAAI,OAAO;AAAE,SAAG,MAAM;AAAA,IAAG;AACzB,OAAG,OAAO,IAAI;AACd,WAAO;AAAA,EACX;AAAA,EAEA,QAAQ;AACJ,YAAQ,IAAI,IAAI,EAAE,MAAM;AACxB,WAAO;AAAA,EACX;AAAA,EAEA,QAAQ,QAAM,OAAO;AACjB,SAAK,KAAK,KAAK;AACf,WAAO,KAAK,MAAM,KAAK;AAAA,EAC3B;AAGJ;;;AIlIO,IAAM,cAAc,CAAC,UAAU,CAAC,MAAM,IAAI,MAAM,OAAO;AAMvD,IAAM,gBAAgB,MAAI;AAC7B,aAAW,CAAC,OAAO,MAAM,KAAK,QAAQ,QAAQ,GAAG;AAC7C,UAAM,KAAK;AAAA,EACf;AACJ;;;ALhBA,IAAO,gBAAQ;",
-  "names": ["import_props"]
+  "sources": ["../../src/index.js", "../../src/Pulse.js", "../../src/const.js", "../../src/tools.js", "../../src/static/options.js", "../../src/static/PulsePrivate.js", "../../src/static/metadata.js"],
+  "sourcesContent": ["import { Pulse } from \"./Pulse\";\nimport { _pulses } from \"./const\";\n\n\nexport {\n    Pulse\n}\n\n/**\n * Factory helper \u2013 simply calls `new Pulse(options)`.\n * @param {PulseOptions} [options={}]  See {@link PulseOptions}.\n * @returns {Pulse}\n */\nexport const createPulse = (options = {}) => new Pulse(options);\n\n\n/**\n * Process exit helper \u2013 stops all pending pulses.\n */\nexport const stopAllPulses = ()=>{\n    for (const [pulse, _pulse] of _pulses.entries()) {\n        pulse.stop();\n    }\n}\n\nexport default createPulse;\n", "import { solid, solids, virtuals } from \"@randajan/props\";\nimport { _pulses } from \"./const\";\nimport { formatOptions } from \"./static/options\";\nimport { PulsePrivate } from \"./static/PulsePrivate\";\n\r\n/**\r\n * Periodic scheduler that aligns each callback to exact multiples\r\n * of the given interval (optionally shifted by `offset`).\r\n */\r\nexport class Pulse {\r\n\r\n    /**\r\n     * Create a new Pulse instance.\r\n     * @param {PulseOptions} [options={}]  See {@link PulseOptions}.\r\n     */\r\n    constructor(options = {}) {\r\n        const _p = new PulsePrivate(this, options);\r\n\r\n        const { getNow, align, interval, offset, autoStart } = _p.opt;\r\n\r\n        virtuals(this, {\r\n            state:_=>_p.state,\r\n            last:_=>_p.last,\r\n            countdown:_=>_p.getCountdown(),\r\n            potential:_=>_p.getCountdown() ?? _p.getPotential(),\r\n            nextAt:_=>_p.state ? this.potential + getNow() : undefined\r\n        });\r\n\r\n        solids(this, {\r\n            interval,\r\n            offset,\r\n            align\r\n        });\r\n\r\n        _pulses.set(this, _p);\r\n\r\n        if (autoStart) { this.start(); }\r\n    }\r\n\r\n    /**\r\n     * Start the pulse loop (no-op if already running).\r\n     * @returns {boolean} `true` if it started now, `false` if it was already running.\r\n     */\r\n    start(reset=false) {\r\n        return _pulses.get(this).start(reset);\r\n    }\r\n\r\n    /**\r\n     * Stop the pulse loop (no-op if already stopped).\r\n     * @returns {boolean} `true` if it stopped now, `false` if it was already stopped.\r\n     */\r\n    stop(reset=false) {\r\n        return _pulses.get(this).stop(reset);\r\n    }\r\n\r\n    restart(reset=false) {\r\n        return _pulses.get(this).restart(reset);\r\n    }\r\n\r\n    reset() {\r\n        return _pulses.get(this).reset();\r\n    }\r\n\r\n}\r\n", "\r\n\r\n\r\nexport const _pulses = new Map();\r\n\r\nexport const blankFn = ()=>{};", "\n\nexport const is = (type, any)=>typeof any === type;\n\nexport const valid = (type, any, req=false, msg=\"argument\")=>{\n    if (any == null) {\n        if (!req) { return; }\n        throw new Error(`${msg} require typeof '${type}'`);\n    }\n    if (is(type, any)) { return any; }\n    throw new Error(`${msg} is not typeof '${type}'`);\n}\n\nexport const validRange = (min, max, any, req=false, msg=\"argument\")=>{\n    const num = valid(\"number\", any, req, msg);\n    if (num == null) { return; }\n    if (num < min) { throw new Error(`${msg} must be greater than ${min}`); }\n    if (num > max) { throw new Error(`${msg} must be less than ${max}`); }\n    return num;\n}", "import { blankFn } from \"../const\";\nimport { valid, validRange } from \"../tools\";\n\n\n\n/**\n * Configuration object for {@link Pulse}.\n * @typedef {Object} PulseOptions\n * @property {(pulse: import(\"../Pulse\").Pulse, meta: import(\"./metadata\").PulseMeta|number) => (*|Promise<*>)} onPulse **required** \u2013 user callback invoked on every pulse.\n * @property {boolean} align **required** \u2013 align to wall-clock interval edges when true, run relatively when false.\n * @property {number} interval **required** \u2013 period length in ms (10 \u2013 2 147 483 647).\n * @property {number} [offset=0] Timing offset. Range and meaning depend on `align` and `runOnStart`.\n * @property {boolean} [runOnStart=false] Schedule the first pulse immediately on start.\n * @property {number} [maxRuns=0] Maximum number of pulses before automatic stop. `0` means unlimited.\n * @property {() => number} [getNow=() => Date.now()] Custom time source, useful for tests or time travel.\n * @property {boolean} [autoStart=false] If true, the loop starts immediately after construction.\n * @property {boolean} [noMeta=false] If true, callbacks receive the numeric pulse id instead of `PulseMeta`.\n * @property {(pulse: import(\"../Pulse\").Pulse) => void} [onStart=blankFn] Called right before the pulse loop starts.\n * @property {(pulse: import(\"../Pulse\").Pulse) => void} [onStop=blankFn] Called right after the pulse loop stops.\n * @property {Function} [onError=blankFn] Error handler for exceptions or rejected `onPulse` promises.\n * @property {(pulse: import(\"../Pulse\").Pulse, meta: import(\"./metadata\").PulseMeta|number) => (void|Promise<void>)} [afterPulse=blankFn] Callback executed after every pulse.\n */\nexport const formatOptions = (options) => {\n    const o = {};\r\n\r\n    o.getNow = valid(\"function\", options.getNow, false, \"options.getNow\") || (_ => Date.now());\r\n\r\n    o.align = valid(\"boolean\", options.align, true, \"options.align\");\r\n\r\n    const minInterval = 10;\r\n    const maxInterval = 2_147_483_647;\r\n    o.interval = validRange(minInterval, maxInterval, options.interval, true, \"options.interval\");\r\n\r\n    o.runOnStart = valid(\"boolean\", options.runOnStart, false, \"options.runOnStart\") || false;\r\n\r\n    const offsetMsg = `options.offset (align:${o.align})`;\r\n\r\n    if (o.align) {\r\n        o.offset = (validRange(0, o.interval, options.offset, false, offsetMsg) ?? 0);\r\n    } else if (!o.runOnStart) {\r\n        o.offset = (validRange(-o.interval, (maxInterval - o.interval), options.offset, false, offsetMsg) ?? 0);\r\n    } else if (options.offset != null) {\n        throw new Error(`${offsetMsg} can't be set if runOnStart:true`);\n    } else {\n        o.offset = -o.interval;\n    }\r\n\r\n    o.maxRuns = validRange(0, Infinity, options.maxRuns, false, \"options.maxRuns\") ?? 0;\r\n\r\n    o.onPulse = valid(\"function\", options.onPulse, true, \"options.onPulse\");\r\n    o.onStart = valid(\"function\", options.onStart, false, \"options.onStart\") || blankFn;\r\n    o.onStop = valid(\"function\", options.onStop, false, \"options.onStop\") || blankFn;\r\n    o.onError = valid(\"function\", options.onError, false, \"options.onError\") || blankFn;\r\n\r\n    o.afterPulse = valid(\"function\", options.afterPulse, false, \"options.afterPulse\") || blankFn;\r\n    o.autoStart = valid(\"boolean\", options.autoStart, false, \"options.autoStart\") || false;\r\n    o.noMeta = valid(\"boolean\", options.noMeta, false, \"option.noMeta\") || false;\r\n\r\n    return Object.freeze(o);\r\n}\n", "import { solid } from \"@randajan/props\";\r\nimport { createMetaData } from \"./metadata\";\r\nimport { formatOptions } from \"./options\";\r\n\r\n\r\nexport class PulsePrivate {\r\n\r\n    constructor(pulse, options) {\r\n        this.pulse = pulse;\r\n        this.state = false;\r\n        this.nextId = 0;\r\n        this.opt = formatOptions(options);\r\n\r\n        this.run = this.run.bind(this);\r\n    }\r\n\r\n    getCountdown() {\r\n        const { state, fireAt, opt:{ getNow } } = this;\r\n        if (!state || fireAt == null) { return; }\r\n        return Math.max(0, fireAt - getNow());\r\n    }\r\n\r\n    getPotential(isInit = true) {\r\n        const { opt:{ align, runOnStart, interval, offset, getNow } } = this;\r\n        if (isInit && runOnStart) { return 0; }\r\n        if (!align) { return isInit ? (interval + offset) : interval; }\r\n        const now = getNow() - offset;\r\n        const rest = ((now % interval) + interval) % interval;\r\n        return rest === 0 ? interval : interval - rest;\r\n    }\r\n\r\n    reset() {\r\n        this.nextId = 0;\r\n        return true;\r\n    }\r\n\r\n    start(reset=false) {\r\n        const { pulse, state, timeoutId, opt:{ onStart } } = this;\r\n        if (state) { return false; }\r\n        onStart(pulse);\r\n        if (reset) { this.reset(); }\r\n        this.state = true;\r\n        return this.plan(true);\r\n    }\r\n\r\n    stop(reset=false) {\r\n        const { pulse, state, timeoutId, opt:{ onStop } } = this;\r\n        if (!state) { return false; }\r\n        clearTimeout(timeoutId);\r\n        this.state = false;\r\n        delete this.fireAt;\r\n        if (reset) { this.reset(); }\r\n        onStop(pulse);\r\n        return true;\r\n    }\r\n\r\n    plan(isInit) {\r\n        const { state, metaData, nextId, opt:{ maxRuns, getNow } } = this;\r\n        if (!state || metaData != null) { return false; }\r\n        if (maxRuns && maxRuns <= nextId) { this.stop(true); return false; }\r\n        const fireIn = this.getPotential(isInit);\r\n        this.fireAt = getNow() + fireIn;\r\n        this.timeoutId = setTimeout(this.run, fireIn);\r\n        this.timeoutId.unref?.();\r\n        return true;\r\n    }\r\n\r\n    async run() {\r\n        const { pulse, state, metaData, opt:{ noMeta, getNow, onPulse, onError, afterPulse } } = this;\r\n        if (!state || metaData) { return; }\r\n\r\n        const id = this.nextId++;\r\n        const md = this.metaData = noMeta ? id : createMetaData(this, id);\n        let errA, errB, result;\r\n\r\n        try {\r\n            result = await onPulse(pulse, md);\r\n            if (!noMeta) { solid(md, \"result\", result); }\r\n        }\r\n        catch (err) {\r\n            errA = err;\r\n            if (!noMeta) { solid(md, \"error\", errA); }\r\n        }\r\n\r\n        if (!noMeta) { solid(md, \"ended\", getNow()); }\r\n\r\n        if (errA != null) {\r\n            if (noMeta) { onError(pulse, errA, md); }\r\n            else { onError(pulse, md); }\r\n        }\r\n\r\n        try { await afterPulse(pulse, md); }\r\n        catch (err) { errB = err; }\r\n\r\n        this.last = noMeta ? result : md;\r\n        delete this.metaData;\r\n\r\n        if (errB != null) {\r\n            this.stop();\r\n            throw errB;\r\n        }\r\n\r\n        this.plan(false);\r\n    }\r\n\r\n    restart(reset) {\r\n        this.stop(reset);\r\n        return this.start(reset);\r\n    }\r\n\r\n}\n", "import { solid, virtual } from \"@randajan/props\";\r\n\r\n\r\n/**\n * Metadata object passed to every pulse callback.\n * @typedef {Object} PulseMeta\n * @property {number} id Sequential pulse id.\n * @property {number} started Timestamp when this pulse began.\n * @property {number} [ended] Timestamp when this pulse finished.\n * @property {number} runtime Milliseconds elapsed since `started`.\n * @property {number} lateBy Milliseconds over the configured interval.\n * @property {string[]|Error[]} warnings Snapshot of all warnings collected so far.\n * @property {*} [result] Value returned by `onPulse`.\n * @property {*} [error] Error thrown or rejected by `onPulse`.\n * @property {(warning: string|Error) => void} warn Push a warning into the internal list.\n */\nexport const createMetaData = (_p, id) => {\n    const md = {};\n    const w = [];\n    solid(md, \"id\", id);\n    solid(md, \"started\", _p.opt.getNow());\r\n    virtual(md, \"warnings\", _ => [...w]);\r\n    virtual(md, \"runtime\", _ => (md.ended ? md.ended : _p.opt.getNow()) - md.started);\r\n    virtual(md, \"lateBy\", _=>Math.max(0, md.runtime-_p.opt.interval));\r\n    solid(md, \"warn\", warning => w.push(warning), false);\r\n    return md;\r\n}\r\n\r\n"],
+  "mappings": "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",
+  "names": ["import_props", "import_props"]
 }

package/dist/esm/index.mjs

@@ -1,5 +1,5 @@
 // src/Pulse.js
-import { solid as solid2, solids, virtuals } from "@randajan/props";
+import { solid as solid3, solids, virtuals } from "@randajan/props";
 
 // src/const.js
 var _pulses = /* @__PURE__ */ new Map();
@@ -34,17 +34,172 @@ var validRange = (min, max, any, req = false, msg = "argument") => {
   return num;
 };
 
-// src/metadata.js
+// src/static/options.js
+var formatOptions = (options) => {
+  const o = {};
+  o.getNow = valid("function", options.getNow, false, "options.getNow") || ((_) => Date.now());
+  o.align = valid("boolean", options.align, true, "options.align");
+  const minInterval = 10;
+  const maxInterval = 2147483647;
+  o.interval = validRange(minInterval, maxInterval, options.interval, true, "options.interval");
+  o.runOnStart = valid("boolean", options.runOnStart, false, "options.runOnStart") || false;
+  const offsetMsg = `options.offset (align:${o.align})`;
+  if (o.align) {
+    o.offset = validRange(0, o.interval, options.offset, false, offsetMsg) ?? 0;
+  } else if (!o.runOnStart) {
+    o.offset = validRange(-o.interval, maxInterval - o.interval, options.offset, false, offsetMsg) ?? 0;
+  } else if (options.offset != null) {
+    throw new Error(`${offsetMsg} can't be set if runOnStart:true`);
+  } else {
+    o.offset = -o.interval;
+  }
+  o.maxRuns = validRange(0, Infinity, options.maxRuns, false, "options.maxRuns") ?? 0;
+  o.onPulse = valid("function", options.onPulse, true, "options.onPulse");
+  o.onStart = valid("function", options.onStart, false, "options.onStart") || blankFn;
+  o.onStop = valid("function", options.onStop, false, "options.onStop") || blankFn;
+  o.onError = valid("function", options.onError, false, "options.onError") || blankFn;
+  o.afterPulse = valid("function", options.afterPulse, false, "options.afterPulse") || blankFn;
+  o.autoStart = valid("boolean", options.autoStart, false, "options.autoStart") || false;
+  o.noMeta = valid("boolean", options.noMeta, false, "option.noMeta") || false;
+  return Object.freeze(o);
+};
+
+// src/static/PulsePrivate.js
+import { solid as solid2 } from "@randajan/props";
+
+// src/static/metadata.js
 import { solid, virtual } from "@randajan/props";
-var createMetaData = (id, getNow) => {
-  const p = {};
+var createMetaData = (_p, id) => {
+  const md = {};
   const w = [];
-  solid(p, "id", id);
-  solid(p, "started", getNow());
-  virtual(p, "warnings", (_) => [...w]);
-  virtual(p, "runtime", (_) => (p.ended ? p.ended : getNow()) - p.started);
-  solid(p, "warn", (warning) => w.push(warning), false);
-  return p;
+  solid(md, "id", id);
+  solid(md, "started", _p.opt.getNow());
+  virtual(md, "warnings", (_) => [...w]);
+  virtual(md, "runtime", (_) => (md.ended ? md.ended : _p.opt.getNow()) - md.started);
+  virtual(md, "lateBy", (_) => Math.max(0, md.runtime - _p.opt.interval));
+  solid(md, "warn", (warning) => w.push(warning), false);
+  return md;
+};
+
+// src/static/PulsePrivate.js
+var PulsePrivate = class {
+  constructor(pulse, options) {
+    this.pulse = pulse;
+    this.state = false;
+    this.nextId = 0;
+    this.opt = formatOptions(options);
+    this.run = this.run.bind(this);
+  }
+  getCountdown() {
+    const { state, fireAt, opt: { getNow } } = this;
+    if (!state || fireAt == null) {
+      return;
+    }
+    return Math.max(0, fireAt - getNow());
+  }
+  getPotential(isInit = true) {
+    const { opt: { align, runOnStart, interval, offset, getNow } } = this;
+    if (isInit && runOnStart) {
+      return 0;
+    }
+    if (!align) {
+      return isInit ? interval + offset : interval;
+    }
+    const now = getNow() - offset;
+    const rest = (now % interval + interval) % interval;
+    return rest === 0 ? interval : interval - rest;
+  }
+  reset() {
+    this.nextId = 0;
+    return true;
+  }
+  start(reset = false) {
+    const { pulse, state, timeoutId, opt: { onStart } } = this;
+    if (state) {
+      return false;
+    }
+    onStart(pulse);
+    if (reset) {
+      this.reset();
+    }
+    this.state = true;
+    return this.plan(true);
+  }
+  stop(reset = false) {
+    const { pulse, state, timeoutId, opt: { onStop } } = this;
+    if (!state) {
+      return false;
+    }
+    clearTimeout(timeoutId);
+    this.state = false;
+    delete this.fireAt;
+    if (reset) {
+      this.reset();
+    }
+    onStop(pulse);
+    return true;
+  }
+  plan(isInit) {
+    const { state, metaData, nextId, opt: { maxRuns, getNow } } = this;
+    if (!state || metaData != null) {
+      return false;
+    }
+    if (maxRuns && maxRuns <= nextId) {
+      this.stop(true);
+      return false;
+    }
+    const fireIn = this.getPotential(isInit);
+    this.fireAt = getNow() + fireIn;
+    this.timeoutId = setTimeout(this.run, fireIn);
+    this.timeoutId.unref?.();
+    return true;
+  }
+  async run() {
+    const { pulse, state, metaData, opt: { noMeta, getNow, onPulse, onError, afterPulse } } = this;
+    if (!state || metaData) {
+      return;
+    }
+    const id = this.nextId++;
+    const md = this.metaData = noMeta ? id : createMetaData(this, id);
+    let errA, errB, result;
+    try {
+      result = await onPulse(pulse, md);
+      if (!noMeta) {
+        solid2(md, "result", result);
+      }
+    } catch (err) {
+      errA = err;
+      if (!noMeta) {
+        solid2(md, "error", errA);
+      }
+    }
+    if (!noMeta) {
+      solid2(md, "ended", getNow());
+    }
+    if (errA != null) {
+      if (noMeta) {
+        onError(pulse, errA, md);
+      } else {
+        onError(pulse, md);
+      }
+    }
+    try {
+      await afterPulse(pulse, md);
+    } catch (err) {
+      errB = err;
+    }
+    this.last = noMeta ? result : md;
+    delete this.metaData;
+    if (errB != null) {
+      this.stop();
+      throw errB;
+    }
+    this.plan(false);
+  }
+  restart(reset) {
+    this.stop(reset);
+    return this.start(reset);
+  }
 };
 
 // src/Pulse.js
@@ -54,78 +209,19 @@ var Pulse = class {
    * @param {PulseOptions} [options={}]  See {@link PulseOptions}.
    */
   constructor(options = {}) {
-    const _p = {
-      state: false,
-      nextId: 0
-    };
-    const getNow = valid("function", options.getNow, false, "options.getNow") || ((_) => Date.now());
-    const interval = validRange(10, 2147483647, options.interval, true, "options.interval");
-    const offset = validRange(0, interval, options.offset, false, "options.offset") || 0;
-    const onPulse = valid("function", options.onPulse, true, "options.onPulse");
-    _p.onStart = valid("function", options.onStart, false, "options.onStart") || blankFn;
-    _p.onStop = valid("function", options.onStop, false, "options.onStop") || blankFn;
-    const onError = valid("function", options.onError, false, "options.onError") || blankFn;
-    const afterPulse = valid("function", options.afterPulse, false, "options.afterPulse") || blankFn;
-    const autoStart = valid("boolean", options.autoStart, false, "options.autoStart") || false;
-    const noMeta = valid("boolean", options.noMeta, false, "option.noMeta") || false;
-    _p.reset = (_) => {
-      _p.nextId = 0;
-    };
-    _p.plan = (_) => {
-      if (!_p.state || _p.metaData != null) {
-        return;
-      }
-      _p.timeoutId = setTimeout(_p.run, this.countdown);
-    };
-    _p.run = async (_) => {
-      if (!_p.state || _p.metaData) {
-        return;
-      }
-      const id = _p.nextId++;
-      const md = _p.metaData = noMeta ? id : createMetaData(id, getNow);
-      let errA, errB, result;
-      try {
-        result = await onPulse(this, md);
-        if (!noMeta) {
-          solid2(md, "result", result);
-        }
-      } catch (err) {
-        errA = err;
-        if (!noMeta) {
-          solid2(md, "error", errA);
-        }
-      }
-      if (!noMeta) {
-        solid2(md, "ended", getNow());
-      }
-      if (errA != null) {
-        if (noMeta) {
-          onError(this, errA, md);
-        } else {
-          onError(this, md);
-        }
-      }
-      try {
-        await afterPulse(this, md);
-      } catch (err) {
-        errB = err;
-      }
-      _p.last = noMeta ? result : md;
-      delete _p.metaData;
-      if (errB != null) {
-        _p.state = false;
-        throw errB;
-      }
-      _p.plan();
-    };
+    const _p = new PulsePrivate(this, options);
+    const { getNow, align, interval, offset, autoStart } = _p.opt;
     virtuals(this, {
       state: (_) => _p.state,
       last: (_) => _p.last,
-      countdown: (_) => interval - getNow() % interval + offset
+      countdown: (_) => _p.getCountdown(),
+      potential: (_) => _p.getCountdown() ?? _p.getPotential(),
+      nextAt: (_) => _p.state ? this.potential + getNow() : void 0
     });
     solids(this, {
       interval,
-      offset
+      offset,
+      align
     });
     _pulses.set(this, _p);
     if (autoStart) {
@@ -137,56 +233,30 @@ var Pulse = class {
    * @returns {boolean} `true` if it started now, `false` if it was already running.
    */
   start(reset = false) {
-    const { state } = this;
-    if (state) {
-      return false;
-    }
-    const _p = _pulses.get(this);
-    _p.onStart(this);
-    if (reset) {
-      _p.reset();
-    }
-    _p.state = true;
-    _p.plan();
-    return true;
+    return _pulses.get(this).start(reset);
   }
   /**
    * Stop the pulse loop (no-op if already stopped).
    * @returns {boolean} `true` if it stopped now, `false` if it was already stopped.
    */
   stop(reset = false) {
-    const { state } = this;
-    if (!state) {
-      return false;
-    }
-    const _p = _pulses.get(this);
-    clearTimeout(_p.timeoutId);
-    _p.state = false;
-    if (reset) {
-      _p.reset();
-    }
-    _p.onStop(this);
-    return true;
-  }
-  reset() {
-    _pulses.get(this).reset();
-    return true;
+    return _pulses.get(this).stop(reset);
   }
   restart(reset = false) {
-    this.stop(reset);
-    return this.start(reset);
+    return _pulses.get(this).restart(reset);
+  }
+  reset() {
+    return _pulses.get(this).reset();
   }
 };
 
-// src/static.js
+// src/index.js
 var createPulse = (options = {}) => new Pulse(options);
 var stopAllPulses = () => {
   for (const [pulse, _pulse] of _pulses.entries()) {
     pulse.stop();
   }
 };
-
-// src/index.js
 var index_default = createPulse;
 export {
   Pulse,

package/dist/esm/index.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../../src/Pulse.js", "../../src/const.js", "../../src/tools.js", "../../src/metadata.js", "../../src/static.js", "../../src/index.js"],
-  "sourcesContent": ["import { solid, solids, virtuals } from \"@randajan/props\";\r\nimport { blankFn, _pulses } from \"./const\";\r\nimport { valid, validRange } from \"./tools\";\r\nimport { createMetaData } from \"./metadata\";\r\n\r\n/**\r\n * Periodic scheduler that aligns each callback to exact multiples\r\n * of the given interval (optionally shifted by `offset`).\r\n */\r\nexport class Pulse {\r\n\r\n    /**\r\n     * Create a new Pulse instance.\r\n     * @param {PulseOptions} [options={}]  See {@link PulseOptions}.\r\n     */\r\n    constructor(options = {}) {\r\n        const _p = {\r\n            state: false,\r\n            nextId:0\r\n        }\r\n\r\n        const getNow = valid(\"function\", options.getNow, false, \"options.getNow\") || (_ => Date.now());\r\n\r\n        const interval = validRange(10, 2_147_483_647, options.interval, true, \"options.interval\");\r\n        const offset = (validRange(0, interval, options.offset, false, \"options.offset\") || 0);\r\n\r\n        const onPulse = valid(\"function\", options.onPulse, true, \"options.onPulse\");\r\n        _p.onStart = valid(\"function\", options.onStart, false, \"options.onStart\") || blankFn;\r\n        _p.onStop = valid(\"function\", options.onStop, false, \"options.onStop\") || blankFn;\r\n        \r\n        const onError = valid(\"function\", options.onError, false, \"options.onError\") || blankFn;\r\n        \r\n        const afterPulse = valid(\"function\", options.afterPulse, false, \"options.afterPulse\") || blankFn;\r\n        const autoStart = valid(\"boolean\", options.autoStart, false, \"options.autoStart\") || false;\r\n        const noMeta = valid(\"boolean\", options.noMeta, false, \"option.noMeta\") || false;\r\n\r\n        _p.reset = _=>{\r\n            _p.nextId = 0;\r\n        }\r\n\r\n        _p.plan = _ => {\r\n            if (!_p.state || _p.metaData != null) { return; }\r\n            _p.timeoutId = setTimeout(_p.run, this.countdown);\r\n        }\r\n\r\n        _p.run = async _ => {\r\n            if (!_p.state || _p.metaData) { return; }\r\n\r\n            const id = _p.nextId++;\r\n            const md = _p.metaData = noMeta ? id : createMetaData(id, getNow);\r\n            let errA, errB, result;\r\n\r\n            try {\r\n                result = await onPulse(this, md);\r\n                if (!noMeta) { solid(md, \"result\", result); }\r\n            }\r\n            catch (err) {\r\n                errA = err;\r\n                if (!noMeta) { solid(md, \"error\", errA); }\r\n            }\r\n\r\n            if (!noMeta) { solid(md, \"ended\", getNow()); }\r\n\r\n            if (errA != null) {\r\n                if (noMeta) { onError(this, errA, md); }\r\n                else { onError(this, md); }\r\n            }\r\n\r\n            try { await afterPulse(this, md); }\r\n            catch(err) { errB = err; }\r\n\r\n            _p.last = noMeta ? result : md;\r\n            delete _p.metaData;\r\n\r\n            if (errB != null) {\r\n                _p.state = false;\r\n                throw errB;\r\n            }\r\n            \r\n            _p.plan();\r\n        }\r\n\r\n        virtuals(this, {\r\n            state:_=>_p.state,\r\n            last:_=>_p.last,\r\n            countdown:_=>((interval - getNow() % interval) + offset)\r\n        });\r\n\r\n        solids(this, {\r\n            interval,\r\n            offset\r\n        });\r\n\r\n        _pulses.set(this, _p);\r\n\r\n        if (autoStart) { this.start(); }\r\n    }\r\n\r\n    /**\r\n     * Start the pulse loop (no-op if already running).\r\n     * @returns {boolean} `true` if it started now, `false` if it was already running.\r\n     */\r\n    start(reset=false) {\r\n        const { state } = this;\r\n        if (state) { return false; }\r\n        const _p = _pulses.get(this);\r\n        _p.onStart(this);\r\n        if (reset) { _p.reset(); }\r\n        _p.state = true;\r\n        _p.plan();\r\n        return true;\r\n    }\r\n\r\n    /**\r\n     * Stop the pulse loop (no-op if already stopped).\r\n     * @returns {boolean} `true` if it stopped now, `false` if it was already stopped.\r\n     */\r\n    stop(reset=false) {\r\n        const { state } = this;\r\n        if (!state) { return false; }\r\n        const _p = _pulses.get(this);\r\n        clearTimeout(_p.timeoutId);\r\n        _p.state = false;\r\n        if (reset) { _p.reset(); }\r\n        _p.onStop(this);\r\n        return true;\r\n    }\r\n\r\n    reset() {\r\n        _pulses.get(this).reset();\r\n        return true;\r\n    }\r\n\r\n    restart(reset=false) {\r\n        this.stop(reset);\r\n        return this.start(reset);\r\n    }\r\n\r\n\r\n}", "\r\n\r\n\r\nexport const _pulses = new Map();\r\n\r\nexport const blankFn = ()=>{};", "\r\n\r\nexport const is = (type, any)=>typeof any === type;\r\n\r\nexport const valid = (type, any, req=false, msg=\"argument\")=>{\r\n    if (any == null) {\r\n        if (!req) { return; }\r\n        throw new Error(`${msg} require typeof '${type}'`);\r\n    }\r\n    if (is(type, any)) { return any; }\r\n    throw new Error(`${msg} is not typeof '${type}'`);\r\n}\r\n\r\nexport const validRange = (min, max, any, req=false, msg=\"argument\")=>{\r\n    const num = valid(\"number\", any, req, msg);\r\n    if (num == null) { return; }\r\n    if (num < min) { throw new Error(`${msg} must be greater than ${min}`); }\r\n    if (num > max) { throw new Error(`${msg} must be less than ${max}`); }\r\n    return num;\r\n}", "import { solid, virtual } from \"@randajan/props\";\r\n\r\n\r\n/**\r\n * Metadata object passed to every pulse callback.\r\n * @typedef {Object} PulseMeta\r\n * @property {Date}   started   Timestamp when this pulse began.\r\n * @property {string[]} warnings  Snapshot of all warnings collected so far.\r\n * @property {number} runtime   Milliseconds elapsed since `started`.\r\n * @property {(warning: string|Error) => void} warn  Push a warning into the internal list.\r\n */\r\nexport const createMetaData = (id, getNow) => {\r\n    const p = {};\r\n    const w = [];\r\n    solid(p, \"id\", id);\r\n    solid(p, \"started\", getNow());\r\n    virtual(p, \"warnings\", _ => [...w]);\r\n    virtual(p, \"runtime\", _ => (p.ended ? p.ended : getNow()) - p.started);\r\n    solid(p, \"warn\", warning => w.push(warning), false);\r\n    return p;\r\n}\r\n\r\n/**\r\n * Configuration object for {@link Pulse}.\r\n * @typedef {Object} PulseOptions\r\n * @property {(meta: PulseMeta) => (void|Promise<void>)} onPulse   **required** \u2013 user callback invoked on every pulse.\r\n * @property {number}  interval  **required** \u2013 period length in ms (50 \u2013 2 147 483 647).\r\n * @property {number} [offset=0]   Shift in ms applied to the start of each interval (0 \u2264 offset < interval).\r\n * @property {() => number} [getNow=() => Date.now()]  Custom time source, useful for tests or time travel.\r\n * @property {(err: unknown) => void} [onError=blankFn]  Error handler for exceptions or rejected `onPulse` promises.\r\n * @property {boolean} [autoStart=false]  If true, the loop starts immediately after construction.\r\n */", "import { _pulses } from \"./const\";\r\nimport { Pulse } from \"./Pulse.js\";\r\n\r\n\r\n/**\r\n * Factory helper \u2013 simply calls `new Pulse(options)`.\r\n * @param {PulseOptions} [options={}]  See {@link PulseOptions}.\r\n * @returns {Pulse}\r\n */\r\nexport const createPulse = (options = {}) => new Pulse(options);\r\n\r\n/**\r\n * Process exit helper \u2013 stops all pending pulses.\r\n */\r\n\r\nexport const stopAllPulses = ()=>{\r\n    for (const [pulse, _pulse] of _pulses.entries()) {\r\n        pulse.stop();\r\n    }\r\n}\r\n", "import { Pulse } from \"./Pulse\";\nimport { createPulse, stopAllPulses } from \"./static\";\n\nexport default createPulse;\n\nexport { createPulse, stopAllPulses, Pulse }\n"],
-  "mappings": "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",
-  "names": ["solid", "solid"]
+  "sources": ["../../src/Pulse.js", "../../src/const.js", "../../src/tools.js", "../../src/static/options.js", "../../src/static/PulsePrivate.js", "../../src/static/metadata.js", "../../src/index.js"],
+  "sourcesContent": ["import { solid, solids, virtuals } from \"@randajan/props\";\nimport { _pulses } from \"./const\";\nimport { formatOptions } from \"./static/options\";\nimport { PulsePrivate } from \"./static/PulsePrivate\";\n\r\n/**\r\n * Periodic scheduler that aligns each callback to exact multiples\r\n * of the given interval (optionally shifted by `offset`).\r\n */\r\nexport class Pulse {\r\n\r\n    /**\r\n     * Create a new Pulse instance.\r\n     * @param {PulseOptions} [options={}]  See {@link PulseOptions}.\r\n     */\r\n    constructor(options = {}) {\r\n        const _p = new PulsePrivate(this, options);\r\n\r\n        const { getNow, align, interval, offset, autoStart } = _p.opt;\r\n\r\n        virtuals(this, {\r\n            state:_=>_p.state,\r\n            last:_=>_p.last,\r\n            countdown:_=>_p.getCountdown(),\r\n            potential:_=>_p.getCountdown() ?? _p.getPotential(),\r\n            nextAt:_=>_p.state ? this.potential + getNow() : undefined\r\n        });\r\n\r\n        solids(this, {\r\n            interval,\r\n            offset,\r\n            align\r\n        });\r\n\r\n        _pulses.set(this, _p);\r\n\r\n        if (autoStart) { this.start(); }\r\n    }\r\n\r\n    /**\r\n     * Start the pulse loop (no-op if already running).\r\n     * @returns {boolean} `true` if it started now, `false` if it was already running.\r\n     */\r\n    start(reset=false) {\r\n        return _pulses.get(this).start(reset);\r\n    }\r\n\r\n    /**\r\n     * Stop the pulse loop (no-op if already stopped).\r\n     * @returns {boolean} `true` if it stopped now, `false` if it was already stopped.\r\n     */\r\n    stop(reset=false) {\r\n        return _pulses.get(this).stop(reset);\r\n    }\r\n\r\n    restart(reset=false) {\r\n        return _pulses.get(this).restart(reset);\r\n    }\r\n\r\n    reset() {\r\n        return _pulses.get(this).reset();\r\n    }\r\n\r\n}\r\n", "\r\n\r\n\r\nexport const _pulses = new Map();\r\n\r\nexport const blankFn = ()=>{};", "\n\nexport const is = (type, any)=>typeof any === type;\n\nexport const valid = (type, any, req=false, msg=\"argument\")=>{\n    if (any == null) {\n        if (!req) { return; }\n        throw new Error(`${msg} require typeof '${type}'`);\n    }\n    if (is(type, any)) { return any; }\n    throw new Error(`${msg} is not typeof '${type}'`);\n}\n\nexport const validRange = (min, max, any, req=false, msg=\"argument\")=>{\n    const num = valid(\"number\", any, req, msg);\n    if (num == null) { return; }\n    if (num < min) { throw new Error(`${msg} must be greater than ${min}`); }\n    if (num > max) { throw new Error(`${msg} must be less than ${max}`); }\n    return num;\n}", "import { blankFn } from \"../const\";\nimport { valid, validRange } from \"../tools\";\n\n\n\n/**\n * Configuration object for {@link Pulse}.\n * @typedef {Object} PulseOptions\n * @property {(pulse: import(\"../Pulse\").Pulse, meta: import(\"./metadata\").PulseMeta|number) => (*|Promise<*>)} onPulse **required** \u2013 user callback invoked on every pulse.\n * @property {boolean} align **required** \u2013 align to wall-clock interval edges when true, run relatively when false.\n * @property {number} interval **required** \u2013 period length in ms (10 \u2013 2 147 483 647).\n * @property {number} [offset=0] Timing offset. Range and meaning depend on `align` and `runOnStart`.\n * @property {boolean} [runOnStart=false] Schedule the first pulse immediately on start.\n * @property {number} [maxRuns=0] Maximum number of pulses before automatic stop. `0` means unlimited.\n * @property {() => number} [getNow=() => Date.now()] Custom time source, useful for tests or time travel.\n * @property {boolean} [autoStart=false] If true, the loop starts immediately after construction.\n * @property {boolean} [noMeta=false] If true, callbacks receive the numeric pulse id instead of `PulseMeta`.\n * @property {(pulse: import(\"../Pulse\").Pulse) => void} [onStart=blankFn] Called right before the pulse loop starts.\n * @property {(pulse: import(\"../Pulse\").Pulse) => void} [onStop=blankFn] Called right after the pulse loop stops.\n * @property {Function} [onError=blankFn] Error handler for exceptions or rejected `onPulse` promises.\n * @property {(pulse: import(\"../Pulse\").Pulse, meta: import(\"./metadata\").PulseMeta|number) => (void|Promise<void>)} [afterPulse=blankFn] Callback executed after every pulse.\n */\nexport const formatOptions = (options) => {\n    const o = {};\r\n\r\n    o.getNow = valid(\"function\", options.getNow, false, \"options.getNow\") || (_ => Date.now());\r\n\r\n    o.align = valid(\"boolean\", options.align, true, \"options.align\");\r\n\r\n    const minInterval = 10;\r\n    const maxInterval = 2_147_483_647;\r\n    o.interval = validRange(minInterval, maxInterval, options.interval, true, \"options.interval\");\r\n\r\n    o.runOnStart = valid(\"boolean\", options.runOnStart, false, \"options.runOnStart\") || false;\r\n\r\n    const offsetMsg = `options.offset (align:${o.align})`;\r\n\r\n    if (o.align) {\r\n        o.offset = (validRange(0, o.interval, options.offset, false, offsetMsg) ?? 0);\r\n    } else if (!o.runOnStart) {\r\n        o.offset = (validRange(-o.interval, (maxInterval - o.interval), options.offset, false, offsetMsg) ?? 0);\r\n    } else if (options.offset != null) {\n        throw new Error(`${offsetMsg} can't be set if runOnStart:true`);\n    } else {\n        o.offset = -o.interval;\n    }\r\n\r\n    o.maxRuns = validRange(0, Infinity, options.maxRuns, false, \"options.maxRuns\") ?? 0;\r\n\r\n    o.onPulse = valid(\"function\", options.onPulse, true, \"options.onPulse\");\r\n    o.onStart = valid(\"function\", options.onStart, false, \"options.onStart\") || blankFn;\r\n    o.onStop = valid(\"function\", options.onStop, false, \"options.onStop\") || blankFn;\r\n    o.onError = valid(\"function\", options.onError, false, \"options.onError\") || blankFn;\r\n\r\n    o.afterPulse = valid(\"function\", options.afterPulse, false, \"options.afterPulse\") || blankFn;\r\n    o.autoStart = valid(\"boolean\", options.autoStart, false, \"options.autoStart\") || false;\r\n    o.noMeta = valid(\"boolean\", options.noMeta, false, \"option.noMeta\") || false;\r\n\r\n    return Object.freeze(o);\r\n}\n", "import { solid } from \"@randajan/props\";\r\nimport { createMetaData } from \"./metadata\";\r\nimport { formatOptions } from \"./options\";\r\n\r\n\r\nexport class PulsePrivate {\r\n\r\n    constructor(pulse, options) {\r\n        this.pulse = pulse;\r\n        this.state = false;\r\n        this.nextId = 0;\r\n        this.opt = formatOptions(options);\r\n\r\n        this.run = this.run.bind(this);\r\n    }\r\n\r\n    getCountdown() {\r\n        const { state, fireAt, opt:{ getNow } } = this;\r\n        if (!state || fireAt == null) { return; }\r\n        return Math.max(0, fireAt - getNow());\r\n    }\r\n\r\n    getPotential(isInit = true) {\r\n        const { opt:{ align, runOnStart, interval, offset, getNow } } = this;\r\n        if (isInit && runOnStart) { return 0; }\r\n        if (!align) { return isInit ? (interval + offset) : interval; }\r\n        const now = getNow() - offset;\r\n        const rest = ((now % interval) + interval) % interval;\r\n        return rest === 0 ? interval : interval - rest;\r\n    }\r\n\r\n    reset() {\r\n        this.nextId = 0;\r\n        return true;\r\n    }\r\n\r\n    start(reset=false) {\r\n        const { pulse, state, timeoutId, opt:{ onStart } } = this;\r\n        if (state) { return false; }\r\n        onStart(pulse);\r\n        if (reset) { this.reset(); }\r\n        this.state = true;\r\n        return this.plan(true);\r\n    }\r\n\r\n    stop(reset=false) {\r\n        const { pulse, state, timeoutId, opt:{ onStop } } = this;\r\n        if (!state) { return false; }\r\n        clearTimeout(timeoutId);\r\n        this.state = false;\r\n        delete this.fireAt;\r\n        if (reset) { this.reset(); }\r\n        onStop(pulse);\r\n        return true;\r\n    }\r\n\r\n    plan(isInit) {\r\n        const { state, metaData, nextId, opt:{ maxRuns, getNow } } = this;\r\n        if (!state || metaData != null) { return false; }\r\n        if (maxRuns && maxRuns <= nextId) { this.stop(true); return false; }\r\n        const fireIn = this.getPotential(isInit);\r\n        this.fireAt = getNow() + fireIn;\r\n        this.timeoutId = setTimeout(this.run, fireIn);\r\n        this.timeoutId.unref?.();\r\n        return true;\r\n    }\r\n\r\n    async run() {\r\n        const { pulse, state, metaData, opt:{ noMeta, getNow, onPulse, onError, afterPulse } } = this;\r\n        if (!state || metaData) { return; }\r\n\r\n        const id = this.nextId++;\r\n        const md = this.metaData = noMeta ? id : createMetaData(this, id);\n        let errA, errB, result;\r\n\r\n        try {\r\n            result = await onPulse(pulse, md);\r\n            if (!noMeta) { solid(md, \"result\", result); }\r\n        }\r\n        catch (err) {\r\n            errA = err;\r\n            if (!noMeta) { solid(md, \"error\", errA); }\r\n        }\r\n\r\n        if (!noMeta) { solid(md, \"ended\", getNow()); }\r\n\r\n        if (errA != null) {\r\n            if (noMeta) { onError(pulse, errA, md); }\r\n            else { onError(pulse, md); }\r\n        }\r\n\r\n        try { await afterPulse(pulse, md); }\r\n        catch (err) { errB = err; }\r\n\r\n        this.last = noMeta ? result : md;\r\n        delete this.metaData;\r\n\r\n        if (errB != null) {\r\n            this.stop();\r\n            throw errB;\r\n        }\r\n\r\n        this.plan(false);\r\n    }\r\n\r\n    restart(reset) {\r\n        this.stop(reset);\r\n        return this.start(reset);\r\n    }\r\n\r\n}\n", "import { solid, virtual } from \"@randajan/props\";\r\n\r\n\r\n/**\n * Metadata object passed to every pulse callback.\n * @typedef {Object} PulseMeta\n * @property {number} id Sequential pulse id.\n * @property {number} started Timestamp when this pulse began.\n * @property {number} [ended] Timestamp when this pulse finished.\n * @property {number} runtime Milliseconds elapsed since `started`.\n * @property {number} lateBy Milliseconds over the configured interval.\n * @property {string[]|Error[]} warnings Snapshot of all warnings collected so far.\n * @property {*} [result] Value returned by `onPulse`.\n * @property {*} [error] Error thrown or rejected by `onPulse`.\n * @property {(warning: string|Error) => void} warn Push a warning into the internal list.\n */\nexport const createMetaData = (_p, id) => {\n    const md = {};\n    const w = [];\n    solid(md, \"id\", id);\n    solid(md, \"started\", _p.opt.getNow());\r\n    virtual(md, \"warnings\", _ => [...w]);\r\n    virtual(md, \"runtime\", _ => (md.ended ? md.ended : _p.opt.getNow()) - md.started);\r\n    virtual(md, \"lateBy\", _=>Math.max(0, md.runtime-_p.opt.interval));\r\n    solid(md, \"warn\", warning => w.push(warning), false);\r\n    return md;\r\n}\r\n\r\n", "import { Pulse } from \"./Pulse\";\nimport { _pulses } from \"./const\";\n\n\nexport {\n    Pulse\n}\n\n/**\n * Factory helper \u2013 simply calls `new Pulse(options)`.\n * @param {PulseOptions} [options={}]  See {@link PulseOptions}.\n * @returns {Pulse}\n */\nexport const createPulse = (options = {}) => new Pulse(options);\n\n\n/**\n * Process exit helper \u2013 stops all pending pulses.\n */\nexport const stopAllPulses = ()=>{\n    for (const [pulse, _pulse] of _pulses.entries()) {\n        pulse.stop();\n    }\n}\n\nexport default createPulse;\n"],
+  "mappings": "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",
+  "names": ["solid", "solid", "solid"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@randajan/pulse",
-  "version": "1.1.4",
+  "version": "2.0.0",
   "description": "Lightweight, promise-friendly scheduler that outperforms classic cron for any interval shorter than one month.",
   "repository": "randajan/pulse",
   "type": "module",
@@ -12,6 +12,9 @@
       "require": "./dist/cjs/index.cjs"
     }
   },
+  "scripts": {
+    "build": "node index.js isBuild=true"
+  },
   "license": "MIT",
   "devDependencies": {
     "@randajan/simple-lib": "^3.3.0"