@randajan/pulse 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022-present Jan Randa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @randajan/pulse
+
+
+[![NPM](https://img.shields.io/npm/v/@randajan/pulse.svg)](https://www.npmjs.com/package/@randajan/pulse) 
+[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
+
+
+---
+
+## 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.
+
+The package ships dual builds—**ESM** *and* **CommonJS**—and works the same in Node.js and the browser.
+
+### ESM **&** CommonJS ready
+
+```js
+// ESM
+import createPulse, { Pulse } from "@randajan/pulse";
+
+// CommonJS
+const createPulse = require("@randajan/pulse");
+```
+
+---
+
+## Quick start
+
+```js
+import createPulse from "@randajan/pulse";
+
+const pulse = createPulse({
+  interval: 1000,                // 1 second
+  onPulse: meta => {
+    console.log("tick", meta.runtime, "ms");
+  },
+  onError: err => console.error("Pulse error:", err),
+  autoStart: true               // start immediately
+});
+
+// Later…
+setTimeout(() => pulse.stop(), 10_000);
+```
+
+Every time **onPulse** runs it receives a fresh metadata object:
+
+```ts
+interface PulseMeta {
+  readonly started:  Date;
+  readonly runtime:  number;            // ms since started
+  readonly warnings: string[];
+  warn(w: string | Error): void;        // push warning
+}
+```
+
+---
+
+## `createPulse(options)` — options reference
+
+| Option      | Type       | Required | Default            | Description                                                        |
+| ----------- | ---------- | -------- | ------------------ | ------------------------------------------------------------------ |
+| `onPulse`   | `function` | ✔︎       | —                  | Async/sync callback executed on each pulse. Receives `PulseMeta`.  |
+| `interval`  | `number`   | ✔︎       | —                  | Period in ms. Min **50 ms**, max **2 147 483 647 ms** (\~24 days). |
+| `offset`    | `number`   |          | `0`                | Fixed shift applied to every pulse (0 ≤ offset < interval).        |
+| `getNow`    | `function` |          | `() => Date.now()` | Custom clock—handy for deterministic tests or time travel.         |
+| `onError`   | `function` |          | `() => {}`         | Called when `onPulse` throws or rejects.                           |
+| `autoStart` | `boolean`  |          | `false`            | If `true`, the scheduler starts right after construction.          |
+
+---
+
+## API
+
+| Member                 | Returns   | Description                                          |
+| ---------------------- | --------- | ---------------------------------------------------- |
+| `createPulse(options)` | `Pulse`   | Convenience wrapper around `new Pulse(options)`.     |
+| `new Pulse(options)`   | `Pulse`   | Class constructor when you prefer `new`.             |
+| `pulse.start()`        | `boolean` | Starts the loop; returns `false` if already running. |
+| `pulse.stop()`         | `boolean` | Stops the loop; returns `false` if already stopped.  |
+| `pulse.state`          | `boolean` | `true` = running, `false` = stopped.                 |
+| `pulse.interval`       | `number`  | Interval in ms (read‑only).                          |
+| `pulse.offset`         | `number`  | Offset in ms (read‑only).                            |
+
+---
+
+## 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.
+
+---
+
+## Recipes
+
+### Long delays (> 24 days)
+
+JavaScript timers accept at most **2 147 483 647 ms**. To wait longer, chain pulses:
+
+```js
+createPulse({
+  interval: 2_147_483_647,
+  onPulse: async meta => {
+    if (stillWaiting()) return;   // keep sleeping…
+    // …real logic here
+  },
+  autoStart: true
+});
+```
+
+
+---
+
+## License
+
+MIT © [randajan](https://github.com/randajan)
+

package/dist/cjs/index.cjs

@@ -0,0 +1,154 @@
+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 = (_) => {
+  const p = {};
+  const w = [];
+  (0, import_props.solid)(p, "started", /* @__PURE__ */ new Date());
+  (0, import_props.virtual)(p, "warnings", (_2) => [...w]);
+  (0, import_props.virtual)(p, "runtime", (_2) => Date.now() - p.started.getTime());
+  (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
+    };
+    const onPulse = valid("function", options.onPulse, true, "options.onPulse");
+    const interval = validRange(50, 2147483647, options.interval, true, "options.interval");
+    const offset = validRange(0, interval, options.offset, false, "options.offset") || 0;
+    const getNow = valid("function", options.getNow, false, "options.getNow") || ((_) => Date.now());
+    const onError = valid("function", options.onError, false, "options.onError") || blankFn;
+    const autoStart = valid("boolean", options.autoStart, false, "options.autoStart") || false;
+    _p.plan = async (_) => {
+      if (!_p.state || _p.metaData) {
+        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;
+      }
+      _p.metaData = createMetaData();
+      try {
+        await onPulse(_p.metaData);
+      } catch (err) {
+        onError(err);
+      }
+      delete _p.metaData;
+      _p.plan();
+    };
+    (0, import_props.virtual)(this, "state", (_) => _p.state);
+    (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() {
+    const { state } = this;
+    if (state) {
+      return false;
+    }
+    const _p = vault.get(this);
+    _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() {
+    const { state } = this;
+    if (!state) {
+      return false;
+    }
+    const _p = vault.get(this);
+    _p.state = false;
+    clearTimeout(_p.timeoutId);
+    return true;
+  }
+};
+
+// 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"],
+  "sourcesContent": ["import { createPulse, Pulse } from \"./Pulse\";\n\nexport default createPulse;\n\nexport { createPulse, Pulse }\n", "import { solid, solids, virtual } 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 = _ => {\r\n    const p = {};\r\n    const w = [];\r\n    solid(p, \"started\", new Date());\r\n    virtual(p, \"warnings\", _ => [...w]);\r\n    virtual(p, \"runtime\", _ => Date.now() - p.started.getTime());\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        }\r\n\r\n        const onPulse = valid(\"function\", options.onPulse, true, \"options.onPulse\");\r\n        const interval = validRange(50, 2_147_483_647, options.interval, true, \"options.interval\");\r\n        const offset = (validRange(0, interval, options.offset, false, \"options.offset\") || 0);\r\n        const getNow = valid(\"function\", options.getNow, false, \"options.getNow\") || (_ => Date.now());\r\n        const onError = valid(\"function\", options.onError, false, \"options.onError\") || blankFn;\r\n        const autoStart = valid(\"boolean\", options.autoStart, false, \"options.autoStart\") || false;\r\n\r\n        _p.plan = async _ => {\r\n            if (!_p.state || _p.metaData) { 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            _p.metaData = createMetaData();\r\n            try { await onPulse(_p.metaData); }\r\n            catch (err) { onError(err); }\r\n            delete _p.metaData;\r\n            _p.plan();\r\n        }\r\n\r\n        virtual(this, \"state\", _ => _p.state);\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() {\r\n        const { state } = this;\r\n        if (state) { return false; }\r\n        const _p = vault.get(this);\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() {\r\n        const { state } = this;\r\n        if (!state) { return false; }\r\n        const _p = vault.get(this);\r\n        _p.state = false;\r\n        clearTimeout(_p.timeoutId);\r\n        return true;\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": "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",
+  "names": ["_"]
+}

package/dist/esm/index.mjs

@@ -0,0 +1,132 @@
+// src/Pulse.js
+import { solid, solids, virtual } 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 = (_) => {
+  const p = {};
+  const w = [];
+  solid(p, "started", /* @__PURE__ */ new Date());
+  virtual(p, "warnings", (_2) => [...w]);
+  virtual(p, "runtime", (_2) => Date.now() - p.started.getTime());
+  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
+    };
+    const onPulse = valid("function", options.onPulse, true, "options.onPulse");
+    const interval = validRange(50, 2147483647, options.interval, true, "options.interval");
+    const offset = validRange(0, interval, options.offset, false, "options.offset") || 0;
+    const getNow = valid("function", options.getNow, false, "options.getNow") || ((_) => Date.now());
+    const onError = valid("function", options.onError, false, "options.onError") || blankFn;
+    const autoStart = valid("boolean", options.autoStart, false, "options.autoStart") || false;
+    _p.plan = async (_) => {
+      if (!_p.state || _p.metaData) {
+        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;
+      }
+      _p.metaData = createMetaData();
+      try {
+        await onPulse(_p.metaData);
+      } catch (err) {
+        onError(err);
+      }
+      delete _p.metaData;
+      _p.plan();
+    };
+    virtual(this, "state", (_) => _p.state);
+    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() {
+    const { state } = this;
+    if (state) {
+      return false;
+    }
+    const _p = vault.get(this);
+    _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() {
+    const { state } = this;
+    if (!state) {
+      return false;
+    }
+    const _p = vault.get(this);
+    _p.state = false;
+    clearTimeout(_p.timeoutId);
+    return true;
+  }
+};
+
+// src/index.js
+var index_default = createPulse;
+export {
+  Pulse,
+  createPulse,
+  index_default as default
+};
+//# 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/index.js"],
+  "sourcesContent": ["import { solid, solids, virtual } 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 = _ => {\r\n    const p = {};\r\n    const w = [];\r\n    solid(p, \"started\", new Date());\r\n    virtual(p, \"warnings\", _ => [...w]);\r\n    virtual(p, \"runtime\", _ => Date.now() - p.started.getTime());\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        }\r\n\r\n        const onPulse = valid(\"function\", options.onPulse, true, \"options.onPulse\");\r\n        const interval = validRange(50, 2_147_483_647, options.interval, true, \"options.interval\");\r\n        const offset = (validRange(0, interval, options.offset, false, \"options.offset\") || 0);\r\n        const getNow = valid(\"function\", options.getNow, false, \"options.getNow\") || (_ => Date.now());\r\n        const onError = valid(\"function\", options.onError, false, \"options.onError\") || blankFn;\r\n        const autoStart = valid(\"boolean\", options.autoStart, false, \"options.autoStart\") || false;\r\n\r\n        _p.plan = async _ => {\r\n            if (!_p.state || _p.metaData) { 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            _p.metaData = createMetaData();\r\n            try { await onPulse(_p.metaData); }\r\n            catch (err) { onError(err); }\r\n            delete _p.metaData;\r\n            _p.plan();\r\n        }\r\n\r\n        virtual(this, \"state\", _ => _p.state);\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() {\r\n        const { state } = this;\r\n        if (state) { return false; }\r\n        const _p = vault.get(this);\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() {\r\n        const { state } = this;\r\n        if (!state) { return false; }\r\n        const _p = vault.get(this);\r\n        _p.state = false;\r\n        clearTimeout(_p.timeoutId);\r\n        return true;\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": ["_"]
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@randajan/pulse",
+  "version": "0.0.2",
+  "description": "Lightweight, promise-friendly scheduler that outperforms classic cron for any interval shorter than one month.",
+  "repository": "randajan/pulse",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.mjs",
+      "require": "./dist/cjs/index.cjs"
+    }
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@randajan/simple-lib": "^3.2.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "scheduler",
+    "cron",
+    "cron-alternative",
+    "job-scheduling",
+    "interval-timer",
+    "sub-monthly",
+    "promise-friendly",
+    "zero-dependency",
+    "nodejs",
+    "pulse"
+  ],
+  "homepage": "https://github.com/randajan/pulse",
+  "bugs": {
+    "url": "https://github.com/randajan/pulse/issues"
+  },
+  "author": {
+    "name": "Jan Randa",
+    "email": "jnranda@gmail.com",
+    "url": "https://www.linkedin.com/in/randajan/"
+  },
+  "dependencies": {
+    "@randajan/props": "^0.1.4"
+  }
+}