@randajan/pulse 0.0.2 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -60,12 +60,17 @@ interface PulseMeta {
60
60
 
61
61
  | Option | Type | Required | Default | Description |
62
62
  | ----------- | ---------- | -------- | ------------------ | ------------------------------------------------------------------ |
63
- | `onPulse` | `function` | ✔︎ | — | Async/sync callback executed on each pulse. Receives `PulseMeta`. |
64
- | `interval` | `number` | ✔︎ | — | Period in ms. Min **50 ms**, max **2 147 483 647 ms** (\~24 days). |
63
+ | `interval` | `number` | ✔︎ | — | Period in ms. Min **10 ms**, max **2 147 483 647 ms** (\~24 days). |
65
64
  | `offset` | `number` |   | `0` | Fixed shift applied to every pulse (0 ≤ offset < interval). |
66
65
  | `getNow` | `function` |   | `() => Date.now()` | Custom clock—handy for deterministic tests or time travel. |
67
- | `onError` | `function` |   | `() => {}` | Called when `onPulse` throws or rejects. |
68
66
  | `autoStart` | `boolean` |   | `false` | If `true`, the scheduler starts right after construction. |
67
+ | `noMeta` | `boolean` |   | `false` | If `false`, the scheduler creates metadata `PuleMeta` at runtime |
68
+ | `onPulse` | `function` | ✔︎ | — | Async/sync callback executed on each pulse. Receives `PulseMeta`. |
69
+ | `onError` | `function` |   | `() => {}` | Called when `onPulse` throws or rejects. |
70
+ | `onStart` | `function` |   | `() => {}` | Called right before pulse starts. |
71
+ | `onStop` | `function` |   | `() => {}` | Called right after pulse stops. |
72
+ | `afterPulse` | `function` | | `() => {}` | Async/sync callback executed after each pulse even if the onPulse raises an error. Receives `PulseMeta`. |
73
+
69
74
 
70
75
  ---
71
76
 
@@ -77,7 +82,10 @@ interface PulseMeta {
77
82
  | `new Pulse(options)` | `Pulse` | Class constructor when you prefer `new`. |
78
83
  | `pulse.start()` | `boolean` | Starts the loop; returns `false` if already running. |
79
84
  | `pulse.stop()` | `boolean` | Stops the loop; returns `false` if already stopped. |
80
- | `pulse.state` | `boolean` | `true` = running, `false` = stopped. |
85
+ | `pulse.restart()` | `boolean` | Call pulse.stop() and then pulse.start() |
86
+ | `pulse.reset()` | `boolean` | Resets nextId counter |
87
+ | `pulse.state` | `boolean` | `true` = running, `false` = stopped (read-only) |
88
+ | `pulse.nextId` | `number` | next pulse id (read-only). |
81
89
  | `pulse.interval` | `number` | Interval in ms (read‑only). |
82
90
  | `pulse.offset` | `number` | Offset in ms (read‑only). |
83
91
 
@@ -62,12 +62,13 @@ var validRange = (min, max, any, req = false, msg = "argument") => {
62
62
  };
63
63
 
64
64
  // src/Pulse.js
65
- var createMetaData = (_) => {
65
+ var createMetaData = (id, getNow) => {
66
66
  const p = {};
67
67
  const w = [];
68
- (0, import_props.solid)(p, "started", /* @__PURE__ */ new Date());
69
- (0, import_props.virtual)(p, "warnings", (_2) => [...w]);
70
- (0, import_props.virtual)(p, "runtime", (_2) => Date.now() - p.started.getTime());
68
+ (0, import_props.solid)(p, "id", id);
69
+ (0, import_props.solid)(p, "started", getNow());
70
+ (0, import_props.virtual)(p, "warnings", (_) => [...w]);
71
+ (0, import_props.virtual)(p, "runtime", (_) => (p.ended ? p.ended : getNow()) - p.started);
71
72
  (0, import_props.solid)(p, "warn", (warning) => w.push(warning), false);
72
73
  return p;
73
74
  };
@@ -79,16 +80,24 @@ var Pulse = class {
79
80
  */
80
81
  constructor(options = {}) {
81
82
  const _p = {
82
- state: false
83
+ state: false,
84
+ nextId: 0
83
85
  };
84
- const onPulse = valid("function", options.onPulse, true, "options.onPulse");
85
- const interval = validRange(50, 2147483647, options.interval, true, "options.interval");
86
- const offset = validRange(0, interval, options.offset, false, "options.offset") || 0;
87
86
  const getNow = valid("function", options.getNow, false, "options.getNow") || ((_) => Date.now());
87
+ const interval = validRange(10, 2147483647, options.interval, true, "options.interval");
88
+ const offset = validRange(0, interval, options.offset, false, "options.offset") || 0;
89
+ const onPulse = valid("function", options.onPulse, true, "options.onPulse");
90
+ _p.onStart = valid("function", options.onStart, false, "options.onStart") || blankFn;
91
+ _p.onStop = valid("function", options.onStop, false, "options.onStop") || blankFn;
88
92
  const onError = valid("function", options.onError, false, "options.onError") || blankFn;
93
+ const afterPulse = valid("function", options.afterPulse, false, "options.afterPulse") || blankFn;
89
94
  const autoStart = valid("boolean", options.autoStart, false, "options.autoStart") || false;
90
- _p.plan = async (_) => {
91
- if (!_p.state || _p.metaData) {
95
+ const noMeta = valid("boolean", options.noMeta, false, "option.noMeta") || false;
96
+ _p.reset = (_) => {
97
+ _p.nextId = 0;
98
+ };
99
+ _p.plan = (_) => {
100
+ if (!_p.state || _p.metaData != null) {
92
101
  return;
93
102
  }
94
103
  const now = getNow();
@@ -99,16 +108,43 @@ var Pulse = class {
99
108
  if (!_p.state || _p.metaData) {
100
109
  return;
101
110
  }
102
- _p.metaData = createMetaData();
111
+ const id = _p.nextId++;
112
+ const md = _p.metaData = noMeta ? id : createMetaData(id, getNow);
113
+ let errA, errB;
114
+ try {
115
+ const result = await onPulse(this, md);
116
+ if (!noMeta) {
117
+ (0, import_props.solid)(md, "result", result);
118
+ }
119
+ } catch (err) {
120
+ errA = err;
121
+ if (!noMeta) {
122
+ (0, import_props.solid)(md, "error", errA);
123
+ }
124
+ }
125
+ if (noMeta) {
126
+ onError(this, errA, md);
127
+ } else {
128
+ (0, import_props.solid)(md, "ended", getNow());
129
+ onError(this, md);
130
+ }
103
131
  try {
104
- await onPulse(_p.metaData);
132
+ await afterPulse(this, md);
105
133
  } catch (err) {
106
- onError(err);
134
+ errB = err;
107
135
  }
136
+ _p.last = md;
108
137
  delete _p.metaData;
138
+ if (errB) {
139
+ _p.state = false;
140
+ throw errB;
141
+ }
109
142
  _p.plan();
110
143
  };
111
- (0, import_props.virtual)(this, "state", (_) => _p.state);
144
+ (0, import_props.virtuals)(this, {
145
+ state: (_) => _p.state,
146
+ last: (_) => _p.last
147
+ });
112
148
  (0, import_props.solids)(this, {
113
149
  interval,
114
150
  offset
@@ -123,12 +159,16 @@ var Pulse = class {
123
159
  * Start the pulse loop (no-op if already running).
124
160
  * @returns {boolean} `true` if it started now, `false` if it was already running.
125
161
  */
126
- start() {
162
+ start(reset = false) {
127
163
  const { state } = this;
128
164
  if (state) {
129
165
  return false;
130
166
  }
131
167
  const _p = vault.get(this);
168
+ _p.onStart(this);
169
+ if (reset) {
170
+ _p.reset();
171
+ }
132
172
  _p.state = true;
133
173
  _p.plan();
134
174
  return true;
@@ -137,16 +177,28 @@ var Pulse = class {
137
177
  * Stop the pulse loop (no-op if already stopped).
138
178
  * @returns {boolean} `true` if it stopped now, `false` if it was already stopped.
139
179
  */
140
- stop() {
180
+ stop(reset = false) {
141
181
  const { state } = this;
142
182
  if (!state) {
143
183
  return false;
144
184
  }
145
185
  const _p = vault.get(this);
146
- _p.state = false;
147
186
  clearTimeout(_p.timeoutId);
187
+ _p.state = false;
188
+ if (reset) {
189
+ _p.reset();
190
+ }
191
+ _p.onStop(this);
192
+ return true;
193
+ }
194
+ reset() {
195
+ vault.get(this).reset();
148
196
  return true;
149
197
  }
198
+ restart(reset = false) {
199
+ this.stop(reset);
200
+ return this.start(reset);
201
+ }
150
202
  };
151
203
 
152
204
  // src/index.js
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "version": 3,
3
3
  "sources": ["../../src/index.js", "../../src/Pulse.js", "../../src/const.js", "../../src/tools.js"],
4
- "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}"],
5
- "mappings": "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",
6
- "names": ["_"]
4
+ "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;\r\n\r\n try {\r\n const 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) {\r\n onError(this, errA, md);\r\n } else {\r\n solid(md, \"ended\", getNow());\r\n 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 = md;\r\n delete _p.metaData;\r\n\r\n if (errB) {\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}"],
5
+ "mappings": "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",
6
+ "names": []
7
7
  }
@@ -1,5 +1,5 @@
1
1
  // src/Pulse.js
2
- import { solid, solids, virtual } from "@randajan/props";
2
+ import { solid, solids, virtual, virtuals } from "@randajan/props";
3
3
 
4
4
  // src/const.js
5
5
  var vault = /* @__PURE__ */ new WeakMap();
@@ -35,12 +35,13 @@ var validRange = (min, max, any, req = false, msg = "argument") => {
35
35
  };
36
36
 
37
37
  // src/Pulse.js
38
- var createMetaData = (_) => {
38
+ var createMetaData = (id, getNow) => {
39
39
  const p = {};
40
40
  const w = [];
41
- solid(p, "started", /* @__PURE__ */ new Date());
42
- virtual(p, "warnings", (_2) => [...w]);
43
- virtual(p, "runtime", (_2) => Date.now() - p.started.getTime());
41
+ solid(p, "id", id);
42
+ solid(p, "started", getNow());
43
+ virtual(p, "warnings", (_) => [...w]);
44
+ virtual(p, "runtime", (_) => (p.ended ? p.ended : getNow()) - p.started);
44
45
  solid(p, "warn", (warning) => w.push(warning), false);
45
46
  return p;
46
47
  };
@@ -52,16 +53,24 @@ var Pulse = class {
52
53
  */
53
54
  constructor(options = {}) {
54
55
  const _p = {
55
- state: false
56
+ state: false,
57
+ nextId: 0
56
58
  };
57
- const onPulse = valid("function", options.onPulse, true, "options.onPulse");
58
- const interval = validRange(50, 2147483647, options.interval, true, "options.interval");
59
- const offset = validRange(0, interval, options.offset, false, "options.offset") || 0;
60
59
  const getNow = valid("function", options.getNow, false, "options.getNow") || ((_) => Date.now());
60
+ const interval = validRange(10, 2147483647, options.interval, true, "options.interval");
61
+ const offset = validRange(0, interval, options.offset, false, "options.offset") || 0;
62
+ const onPulse = valid("function", options.onPulse, true, "options.onPulse");
63
+ _p.onStart = valid("function", options.onStart, false, "options.onStart") || blankFn;
64
+ _p.onStop = valid("function", options.onStop, false, "options.onStop") || blankFn;
61
65
  const onError = valid("function", options.onError, false, "options.onError") || blankFn;
66
+ const afterPulse = valid("function", options.afterPulse, false, "options.afterPulse") || blankFn;
62
67
  const autoStart = valid("boolean", options.autoStart, false, "options.autoStart") || false;
63
- _p.plan = async (_) => {
64
- if (!_p.state || _p.metaData) {
68
+ const noMeta = valid("boolean", options.noMeta, false, "option.noMeta") || false;
69
+ _p.reset = (_) => {
70
+ _p.nextId = 0;
71
+ };
72
+ _p.plan = (_) => {
73
+ if (!_p.state || _p.metaData != null) {
65
74
  return;
66
75
  }
67
76
  const now = getNow();
@@ -72,16 +81,43 @@ var Pulse = class {
72
81
  if (!_p.state || _p.metaData) {
73
82
  return;
74
83
  }
75
- _p.metaData = createMetaData();
84
+ const id = _p.nextId++;
85
+ const md = _p.metaData = noMeta ? id : createMetaData(id, getNow);
86
+ let errA, errB;
87
+ try {
88
+ const result = await onPulse(this, md);
89
+ if (!noMeta) {
90
+ solid(md, "result", result);
91
+ }
92
+ } catch (err) {
93
+ errA = err;
94
+ if (!noMeta) {
95
+ solid(md, "error", errA);
96
+ }
97
+ }
98
+ if (noMeta) {
99
+ onError(this, errA, md);
100
+ } else {
101
+ solid(md, "ended", getNow());
102
+ onError(this, md);
103
+ }
76
104
  try {
77
- await onPulse(_p.metaData);
105
+ await afterPulse(this, md);
78
106
  } catch (err) {
79
- onError(err);
107
+ errB = err;
80
108
  }
109
+ _p.last = md;
81
110
  delete _p.metaData;
111
+ if (errB) {
112
+ _p.state = false;
113
+ throw errB;
114
+ }
82
115
  _p.plan();
83
116
  };
84
- virtual(this, "state", (_) => _p.state);
117
+ virtuals(this, {
118
+ state: (_) => _p.state,
119
+ last: (_) => _p.last
120
+ });
85
121
  solids(this, {
86
122
  interval,
87
123
  offset
@@ -96,12 +132,16 @@ var Pulse = class {
96
132
  * Start the pulse loop (no-op if already running).
97
133
  * @returns {boolean} `true` if it started now, `false` if it was already running.
98
134
  */
99
- start() {
135
+ start(reset = false) {
100
136
  const { state } = this;
101
137
  if (state) {
102
138
  return false;
103
139
  }
104
140
  const _p = vault.get(this);
141
+ _p.onStart(this);
142
+ if (reset) {
143
+ _p.reset();
144
+ }
105
145
  _p.state = true;
106
146
  _p.plan();
107
147
  return true;
@@ -110,16 +150,28 @@ var Pulse = class {
110
150
  * Stop the pulse loop (no-op if already stopped).
111
151
  * @returns {boolean} `true` if it stopped now, `false` if it was already stopped.
112
152
  */
113
- stop() {
153
+ stop(reset = false) {
114
154
  const { state } = this;
115
155
  if (!state) {
116
156
  return false;
117
157
  }
118
158
  const _p = vault.get(this);
119
- _p.state = false;
120
159
  clearTimeout(_p.timeoutId);
160
+ _p.state = false;
161
+ if (reset) {
162
+ _p.reset();
163
+ }
164
+ _p.onStop(this);
165
+ return true;
166
+ }
167
+ reset() {
168
+ vault.get(this).reset();
121
169
  return true;
122
170
  }
171
+ restart(reset = false) {
172
+ this.stop(reset);
173
+ return this.start(reset);
174
+ }
123
175
  };
124
176
 
125
177
  // src/index.js
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "version": 3,
3
3
  "sources": ["../../src/Pulse.js", "../../src/const.js", "../../src/tools.js", "../../src/index.js"],
4
- "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"],
5
- "mappings": "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",
6
- "names": ["_"]
4
+ "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;\r\n\r\n try {\r\n const 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) {\r\n onError(this, errA, md);\r\n } else {\r\n solid(md, \"ended\", getNow());\r\n 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 = md;\r\n delete _p.metaData;\r\n\r\n if (errB) {\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"],
5
+ "mappings": "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",
6
+ "names": []
7
7
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@randajan/pulse",
3
- "version": "0.0.2",
3
+ "version": "1.0.0",
4
4
  "description": "Lightweight, promise-friendly scheduler that outperforms classic cron for any interval shorter than one month.",
5
5
  "repository": "randajan/pulse",
6
6
  "type": "module",