@randajan/pulse 1.1.2 → 1.1.4

package/README.md

@@ -88,6 +88,7 @@ interface PulseMeta {
 | `pulse.nextId`          | `number` | next pulse id (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         |
 
 ---

package/dist/cjs/index.cjs

@@ -0,0 +1,219 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.js
+var index_exports = {};
+__export(index_exports, {
+  Pulse: () => Pulse,
+  createPulse: () => createPulse,
+  default: () => index_default,
+  stopAllPulses: () => stopAllPulses
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/Pulse.js
+var import_props2 = require("@randajan/props");
+
+// src/const.js
+var _pulses = /* @__PURE__ */ new Map();
+var blankFn = () => {
+};
+
+// src/tools.js
+var is = (type, any) => typeof any === type;
+var valid = (type, any, req = false, msg = "argument") => {
+  if (any == null) {
+    if (!req) {
+      return;
+    }
+    throw new Error(`${msg} require typeof '${type}'`);
+  }
+  if (is(type, any)) {
+    return any;
+  }
+  throw new Error(`${msg} is not typeof '${type}'`);
+};
+var validRange = (min, max, any, req = false, msg = "argument") => {
+  const num = valid("number", any, req, msg);
+  if (num == null) {
+    return;
+  }
+  if (num < min) {
+    throw new Error(`${msg} must be greater than ${min}`);
+  }
+  if (num > max) {
+    throw new Error(`${msg} must be less than ${max}`);
+  }
+  return num;
+};
+
+// src/metadata.js
+var import_props = require("@randajan/props");
+var createMetaData = (id, getNow) => {
+  const p = {};
+  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;
+};
+
+// src/Pulse.js
+var Pulse = class {
+  /**
+   * Create a new Pulse instance.
+   * @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, {
+      state: (_) => _p.state,
+      last: (_) => _p.last,
+      countdown: (_) => interval - getNow() % interval + offset
+    });
+    (0, import_props2.solids)(this, {
+      interval,
+      offset
+    });
+    _pulses.set(this, _p);
+    if (autoStart) {
+      this.start();
+    }
+  }
+  /**
+   * Start the pulse loop (no-op if already running).
+   * @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;
+  }
+  /**
+   * 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;
+  }
+  restart(reset = false) {
+    this.stop(reset);
+    return this.start(reset);
+  }
+};
+
+// src/static.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

@@ -0,0 +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": "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",
+  "names": ["import_props"]
+}

package/dist/esm/index.mjs

@@ -0,0 +1,197 @@
+// src/Pulse.js
+import { solid as solid2, solids, virtuals } from "@randajan/props";
+
+// src/const.js
+var _pulses = /* @__PURE__ */ new Map();
+var blankFn = () => {
+};
+
+// src/tools.js
+var is = (type, any) => typeof any === type;
+var valid = (type, any, req = false, msg = "argument") => {
+  if (any == null) {
+    if (!req) {
+      return;
+    }
+    throw new Error(`${msg} require typeof '${type}'`);
+  }
+  if (is(type, any)) {
+    return any;
+  }
+  throw new Error(`${msg} is not typeof '${type}'`);
+};
+var validRange = (min, max, any, req = false, msg = "argument") => {
+  const num = valid("number", any, req, msg);
+  if (num == null) {
+    return;
+  }
+  if (num < min) {
+    throw new Error(`${msg} must be greater than ${min}`);
+  }
+  if (num > max) {
+    throw new Error(`${msg} must be less than ${max}`);
+  }
+  return num;
+};
+
+// src/metadata.js
+import { solid, virtual } from "@randajan/props";
+var createMetaData = (id, getNow) => {
+  const p = {};
+  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;
+};
+
+// src/Pulse.js
+var Pulse = class {
+  /**
+   * Create a new Pulse instance.
+   * @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();
+    };
+    virtuals(this, {
+      state: (_) => _p.state,
+      last: (_) => _p.last,
+      countdown: (_) => interval - getNow() % interval + offset
+    });
+    solids(this, {
+      interval,
+      offset
+    });
+    _pulses.set(this, _p);
+    if (autoStart) {
+      this.start();
+    }
+  }
+  /**
+   * Start the pulse loop (no-op if already running).
+   * @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;
+  }
+  /**
+   * 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;
+  }
+  restart(reset = false) {
+    this.stop(reset);
+    return this.start(reset);
+  }
+};
+
+// src/static.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,
+  createPulse,
+  index_default as default,
+  stopAllPulses
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/index.mjs.map

@@ -0,0 +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"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@randajan/pulse",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Lightweight, promise-friendly scheduler that outperforms classic cron for any interval shorter than one month.",
   "repository": "randajan/pulse",
   "type": "module",
@@ -14,7 +14,7 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@randajan/simple-lib": "^3.2.0"
+    "@randajan/simple-lib": "^3.3.0"
   },
   "files": [
     "dist",