@randajan/pulse 1.0.1 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@randajan/pulse",
-  "version": "1.0.1",
+  "version": "1.1.2",
   "description": "Lightweight, promise-friendly scheduler that outperforms classic cron for any interval shorter than one month.",
   "repository": "randajan/pulse",
   "type": "module",

package/dist/cjs/index.cjs

@@ -1,210 +0,0 @@
-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
-});
-module.exports = __toCommonJS(index_exports);
-
-// src/Pulse.js
-var import_props = require("@randajan/props");
-
-// src/const.js
-var vault = /* @__PURE__ */ new WeakMap();
-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/Pulse.js
-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;
-};
-var createPulse = (options = {}) => new Pulse(options);
-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;
-      }
-      const now = getNow();
-      const runIn = interval - now % interval + offset;
-      _p.timeoutId = setTimeout(_p.run, runIn);
-    };
-    _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_props.solid)(md, "result", result);
-        }
-      } catch (err) {
-        errA = err;
-        if (!noMeta) {
-          (0, import_props.solid)(md, "error", errA);
-        }
-      }
-      if (!noMeta) {
-        (0, import_props.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_props.virtuals)(this, {
-      state: (_) => _p.state,
-      last: (_) => _p.last
-    });
-    (0, import_props.solids)(this, {
-      interval,
-      offset
-    });
-    vault.set(this, _p);
-    process.on("exit", (_) => this.stop());
-    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 = vault.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 = vault.get(this);
-    clearTimeout(_p.timeoutId);
-    _p.state = false;
-    if (reset) {
-      _p.reset();
-    }
-    _p.onStop(this);
-    return true;
-  }
-  reset() {
-    vault.get(this).reset();
-    return true;
-  }
-  restart(reset = false) {
-    this.stop(reset);
-    return this.start(reset);
-  }
-};
-
-// src/index.js
-var index_default = createPulse;
-//# sourceMappingURL=index.js.map

package/dist/cjs/index.cjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../src/index.js", "../../src/Pulse.js", "../../src/const.js", "../../src/tools.js"],
-  "sourcesContent": ["import { createPulse, Pulse } from \"./Pulse\";\n\nexport default createPulse;\n\nexport { createPulse, Pulse }\n", "import { solid, solids, virtual, virtuals } from \"@randajan/props\";\r\nimport { blankFn, vault } from \"./const\";\r\nimport { valid, validRange } from \"./tools\";\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\nconst 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 */\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 * 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            const now = getNow();\r\n            const runIn = (interval - now % interval) + offset;\r\n            _p.timeoutId = setTimeout(_p.run, runIn);\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        });\r\n\r\n        solids(this, {\r\n            interval,\r\n            offset\r\n        });\r\n\r\n        vault.set(this, _p);\r\n\r\n        process.on(\"exit\", _ => this.stop());\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 = vault.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 = vault.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        vault.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 vault = new WeakMap();\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}"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,mBAAiD;;;ACG1C,IAAM,QAAQ,oBAAI,QAAQ;AAE1B,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;;;AFPA,IAAM,iBAAiB,CAAC,IAAI,WAAW;AACnC,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;AAkBO,IAAM,cAAc,CAAC,UAAU,CAAC,MAAM,IAAI,MAAM,OAAO;AAMvD,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,YAAM,MAAM,OAAO;AACnB,YAAM,QAAS,WAAW,MAAM,WAAY;AAC5C,SAAG,YAAY,WAAW,GAAG,KAAK,KAAK;AAAA,IAC3C;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,kCAAM,IAAI,UAAU,MAAM;AAAA,QAAG;AAAA,MAChD,SACO,KAAK;AACR,eAAO;AACP,YAAI,CAAC,QAAQ;AAAE,kCAAM,IAAI,SAAS,IAAI;AAAA,QAAG;AAAA,MAC7C;AAEA,UAAI,CAAC,QAAQ;AAAE,gCAAM,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,+BAAS,MAAM;AAAA,MACX,OAAM,OAAG,GAAG;AAAA,MACZ,MAAK,OAAG,GAAG;AAAA,IACf,CAAC;AAED,6BAAO,MAAM;AAAA,MACT;AAAA,MACA;AAAA,IACJ,CAAC;AAED,UAAM,IAAI,MAAM,EAAE;AAElB,YAAQ,GAAG,QAAQ,OAAK,KAAK,KAAK,CAAC;AACnC,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,MAAM,IAAI,IAAI;AACzB,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,MAAM,IAAI,IAAI;AACzB,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,UAAM,IAAI,IAAI,EAAE,MAAM;AACtB,WAAO;AAAA,EACX;AAAA,EAEA,QAAQ,QAAM,OAAO;AACjB,SAAK,KAAK,KAAK;AACf,WAAO,KAAK,MAAM,KAAK;AAAA,EAC3B;AAGJ;;;AD/KA,IAAO,gBAAQ;",
-  "names": []
-}

package/dist/esm/index.mjs

@@ -1,188 +0,0 @@
-// src/Pulse.js
-import { solid, solids, virtual, virtuals } from "@randajan/props";
-
-// src/const.js
-var vault = /* @__PURE__ */ new WeakMap();
-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/Pulse.js
-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;
-};
-var createPulse = (options = {}) => new Pulse(options);
-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;
-      }
-      const now = getNow();
-      const runIn = interval - now % interval + offset;
-      _p.timeoutId = setTimeout(_p.run, runIn);
-    };
-    _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) {
-          solid(md, "result", result);
-        }
-      } catch (err) {
-        errA = err;
-        if (!noMeta) {
-          solid(md, "error", errA);
-        }
-      }
-      if (!noMeta) {
-        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();
-    };
-    virtuals(this, {
-      state: (_) => _p.state,
-      last: (_) => _p.last
-    });
-    solids(this, {
-      interval,
-      offset
-    });
-    vault.set(this, _p);
-    process.on("exit", (_) => this.stop());
-    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 = vault.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 = vault.get(this);
-    clearTimeout(_p.timeoutId);
-    _p.state = false;
-    if (reset) {
-      _p.reset();
-    }
-    _p.onStop(this);
-    return true;
-  }
-  reset() {
-    vault.get(this).reset();
-    return true;
-  }
-  restart(reset = false) {
-    this.stop(reset);
-    return this.start(reset);
-  }
-};
-
-// src/index.js
-var index_default = createPulse;
-export {
-  Pulse,
-  createPulse,
-  index_default as default
-};
-//# sourceMappingURL=index.js.map

package/dist/esm/index.mjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../src/Pulse.js", "../../src/const.js", "../../src/tools.js", "../../src/index.js"],
-  "sourcesContent": ["import { solid, solids, virtual, virtuals } from \"@randajan/props\";\r\nimport { blankFn, vault } from \"./const\";\r\nimport { valid, validRange } from \"./tools\";\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\nconst 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 */\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 * 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            const now = getNow();\r\n            const runIn = (interval - now % interval) + offset;\r\n            _p.timeoutId = setTimeout(_p.run, runIn);\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        });\r\n\r\n        solids(this, {\r\n            interval,\r\n            offset\r\n        });\r\n\r\n        vault.set(this, _p);\r\n\r\n        process.on(\"exit\", _ => this.stop());\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 = vault.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 = vault.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        vault.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 vault = new WeakMap();\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 { createPulse, Pulse } from \"./Pulse\";\n\nexport default createPulse;\n\nexport { createPulse, Pulse }\n"],
-  "mappings": "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",
-  "names": []
-}