@randajan/pulse 0.1.0 → 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
@@ -67,6 +67,8 @@ interface PulseMeta {
67
67
  | `noMeta` | `boolean` |   | `false` | If `false`, the scheduler creates metadata `PuleMeta` at runtime |
68
68
  | `onPulse` | `function` | ✔︎ | — | Async/sync callback executed on each pulse. Receives `PulseMeta`. |
69
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. |
70
72
  | `afterPulse` | `function` | | `() => {}` | Async/sync callback executed after each pulse even if the onPulse raises an error. Receives `PulseMeta`. |
71
73
 
72
74
 
@@ -80,7 +82,10 @@ interface PulseMeta {
80
82
  | `new Pulse(options)` | `Pulse` | Class constructor when you prefer `new`. |
81
83
  | `pulse.start()` | `boolean` | Starts the loop; returns `false` if already running. |
82
84
  | `pulse.stop()` | `boolean` | Stops the loop; returns `false` if already stopped. |
83
- | `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). |
84
89
  | `pulse.interval` | `number` | Interval in ms (read‑only). |
85
90
  | `pulse.offset` | `number` | Offset in ms (read‑only). |
86
91
 
@@ -62,9 +62,10 @@ var validRange = (min, max, any, req = false, msg = "argument") => {
62
62
  };
63
63
 
64
64
  // src/Pulse.js
65
- var createMetaData = (getNow) => {
65
+ var createMetaData = (id, getNow) => {
66
66
  const p = {};
67
67
  const w = [];
68
+ (0, import_props.solid)(p, "id", id);
68
69
  (0, import_props.solid)(p, "started", getNow());
69
70
  (0, import_props.virtual)(p, "warnings", (_) => [...w]);
70
71
  (0, import_props.virtual)(p, "runtime", (_) => (p.ended ? p.ended : getNow()) - p.started);
@@ -79,18 +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");
86
+ const getNow = valid("function", options.getNow, false, "options.getNow") || ((_) => Date.now());
85
87
  const interval = validRange(10, 2147483647, options.interval, true, "options.interval");
86
88
  const offset = validRange(0, interval, options.offset, false, "options.offset") || 0;
87
- const getNow = valid("function", options.getNow, false, "options.getNow") || ((_) => Date.now());
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;
89
93
  const afterPulse = valid("function", options.afterPulse, false, "options.afterPulse") || blankFn;
90
94
  const autoStart = valid("boolean", options.autoStart, false, "options.autoStart") || false;
91
95
  const noMeta = valid("boolean", options.noMeta, false, "option.noMeta") || false;
92
- _p.plan = async (_) => {
93
- if (!_p.state || _p.metaData) {
96
+ _p.reset = (_) => {
97
+ _p.nextId = 0;
98
+ };
99
+ _p.plan = (_) => {
100
+ if (!_p.state || _p.metaData != null) {
94
101
  return;
95
102
  }
96
103
  const now = getNow();
@@ -101,35 +108,43 @@ var Pulse = class {
101
108
  if (!_p.state || _p.metaData) {
102
109
  return;
103
110
  }
104
- const md = _p.metaData = noMeta ? void 0 : createMetaData(getNow);
105
- let error;
111
+ const id = _p.nextId++;
112
+ const md = _p.metaData = noMeta ? id : createMetaData(id, getNow);
113
+ let errA, errB;
106
114
  try {
107
- const result = await onPulse(md);
108
- if (md) {
115
+ const result = await onPulse(this, md);
116
+ if (!noMeta) {
109
117
  (0, import_props.solid)(md, "result", result);
110
118
  }
111
119
  } catch (err) {
112
- error = err;
113
- if (md) {
114
- (0, import_props.solid)(md, "error", err);
120
+ errA = err;
121
+ if (!noMeta) {
122
+ (0, import_props.solid)(md, "error", errA);
115
123
  }
116
124
  }
117
- if (md) {
125
+ if (noMeta) {
126
+ onError(this, errA, md);
127
+ } else {
118
128
  (0, import_props.solid)(md, "ended", getNow());
119
- }
120
- if (error) {
121
- onError(error, md);
129
+ onError(this, md);
122
130
  }
123
131
  try {
124
- await afterPulse(md);
125
- delete _p.metaData;
126
- _p.plan();
132
+ await afterPulse(this, md);
127
133
  } catch (err) {
134
+ errB = err;
135
+ }
136
+ _p.last = md;
137
+ delete _p.metaData;
138
+ if (errB) {
128
139
  _p.state = false;
129
- throw err;
140
+ throw errB;
130
141
  }
142
+ _p.plan();
131
143
  };
132
- (0, import_props.virtual)(this, "state", (_) => _p.state);
144
+ (0, import_props.virtuals)(this, {
145
+ state: (_) => _p.state,
146
+ last: (_) => _p.last
147
+ });
133
148
  (0, import_props.solids)(this, {
134
149
  interval,
135
150
  offset
@@ -144,12 +159,16 @@ var Pulse = class {
144
159
  * Start the pulse loop (no-op if already running).
145
160
  * @returns {boolean} `true` if it started now, `false` if it was already running.
146
161
  */
147
- start() {
162
+ start(reset = false) {
148
163
  const { state } = this;
149
164
  if (state) {
150
165
  return false;
151
166
  }
152
167
  const _p = vault.get(this);
168
+ _p.onStart(this);
169
+ if (reset) {
170
+ _p.reset();
171
+ }
153
172
  _p.state = true;
154
173
  _p.plan();
155
174
  return true;
@@ -158,16 +177,28 @@ var Pulse = class {
158
177
  * Stop the pulse loop (no-op if already stopped).
159
178
  * @returns {boolean} `true` if it stopped now, `false` if it was already stopped.
160
179
  */
161
- stop() {
180
+ stop(reset = false) {
162
181
  const { state } = this;
163
182
  if (!state) {
164
183
  return false;
165
184
  }
166
185
  const _p = vault.get(this);
167
- _p.state = false;
168
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();
169
196
  return true;
170
197
  }
198
+ restart(reset = false) {
199
+ this.stop(reset);
200
+ return this.start(reset);
201
+ }
171
202
  };
172
203
 
173
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 = (getNow) => {\r\n const p = {};\r\n const w = [];\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 }\r\n\r\n const onPulse = valid(\"function\", options.onPulse, true, \"options.onPulse\");\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 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 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.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\r\n const md = _p.metaData = noMeta ? undefined : createMetaData(getNow);\r\n let error;\r\n\r\n try {\r\n const result = await onPulse(md);\r\n if (md) { solid(md, \"result\", result); }\r\n }\r\n catch (err) {\r\n error = err;\r\n if (md) { solid(md, \"error\", err); }\r\n }\r\n\r\n if (md) { solid(md, \"ended\", getNow()); }\r\n if (error) { onError(error, md); }\r\n\r\n try {\r\n await afterPulse(md);\r\n delete _p.metaData;\r\n _p.plan();\r\n }\r\n catch(err) {\r\n _p.state = false;\r\n throw err;\r\n }\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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",
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": ";;;;;;;;;;;;;;;;;;;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;AAEV,UAAI;AACA,cAAM,SAAS,MAAM,QAAQ,MAAM,EAAE;AACrC,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,QAAQ;AACR,gBAAQ,MAAM,MAAM,EAAE;AAAA,MAC1B,OAAO;AACH,gCAAM,IAAI,SAAS,OAAO,CAAC;AAC3B,gBAAQ,MAAM,EAAE;AAAA,MACpB;AAEA,UAAI;AAAE,cAAM,WAAW,MAAM,EAAE;AAAA,MAAG,SAC5B,KAAK;AAAE,eAAO;AAAA,MAAK;AAEzB,SAAG,OAAO;AACV,aAAO,GAAG;AAEV,UAAI,MAAM;AACN,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;",
6
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,9 +35,10 @@ var validRange = (min, max, any, req = false, msg = "argument") => {
35
35
  };
36
36
 
37
37
  // src/Pulse.js
38
- var createMetaData = (getNow) => {
38
+ var createMetaData = (id, getNow) => {
39
39
  const p = {};
40
40
  const w = [];
41
+ solid(p, "id", id);
41
42
  solid(p, "started", getNow());
42
43
  virtual(p, "warnings", (_) => [...w]);
43
44
  virtual(p, "runtime", (_) => (p.ended ? p.ended : getNow()) - p.started);
@@ -52,18 +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");
59
+ const getNow = valid("function", options.getNow, false, "options.getNow") || ((_) => Date.now());
58
60
  const interval = validRange(10, 2147483647, options.interval, true, "options.interval");
59
61
  const offset = validRange(0, interval, options.offset, false, "options.offset") || 0;
60
- const getNow = valid("function", options.getNow, false, "options.getNow") || ((_) => Date.now());
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;
62
66
  const afterPulse = valid("function", options.afterPulse, false, "options.afterPulse") || blankFn;
63
67
  const autoStart = valid("boolean", options.autoStart, false, "options.autoStart") || false;
64
68
  const noMeta = valid("boolean", options.noMeta, false, "option.noMeta") || false;
65
- _p.plan = async (_) => {
66
- if (!_p.state || _p.metaData) {
69
+ _p.reset = (_) => {
70
+ _p.nextId = 0;
71
+ };
72
+ _p.plan = (_) => {
73
+ if (!_p.state || _p.metaData != null) {
67
74
  return;
68
75
  }
69
76
  const now = getNow();
@@ -74,35 +81,43 @@ var Pulse = class {
74
81
  if (!_p.state || _p.metaData) {
75
82
  return;
76
83
  }
77
- const md = _p.metaData = noMeta ? void 0 : createMetaData(getNow);
78
- let error;
84
+ const id = _p.nextId++;
85
+ const md = _p.metaData = noMeta ? id : createMetaData(id, getNow);
86
+ let errA, errB;
79
87
  try {
80
- const result = await onPulse(md);
81
- if (md) {
88
+ const result = await onPulse(this, md);
89
+ if (!noMeta) {
82
90
  solid(md, "result", result);
83
91
  }
84
92
  } catch (err) {
85
- error = err;
86
- if (md) {
87
- solid(md, "error", err);
93
+ errA = err;
94
+ if (!noMeta) {
95
+ solid(md, "error", errA);
88
96
  }
89
97
  }
90
- if (md) {
98
+ if (noMeta) {
99
+ onError(this, errA, md);
100
+ } else {
91
101
  solid(md, "ended", getNow());
92
- }
93
- if (error) {
94
- onError(error, md);
102
+ onError(this, md);
95
103
  }
96
104
  try {
97
- await afterPulse(md);
98
- delete _p.metaData;
99
- _p.plan();
105
+ await afterPulse(this, md);
100
106
  } catch (err) {
107
+ errB = err;
108
+ }
109
+ _p.last = md;
110
+ delete _p.metaData;
111
+ if (errB) {
101
112
  _p.state = false;
102
- throw err;
113
+ throw errB;
103
114
  }
115
+ _p.plan();
104
116
  };
105
- virtual(this, "state", (_) => _p.state);
117
+ virtuals(this, {
118
+ state: (_) => _p.state,
119
+ last: (_) => _p.last
120
+ });
106
121
  solids(this, {
107
122
  interval,
108
123
  offset
@@ -117,12 +132,16 @@ var Pulse = class {
117
132
  * Start the pulse loop (no-op if already running).
118
133
  * @returns {boolean} `true` if it started now, `false` if it was already running.
119
134
  */
120
- start() {
135
+ start(reset = false) {
121
136
  const { state } = this;
122
137
  if (state) {
123
138
  return false;
124
139
  }
125
140
  const _p = vault.get(this);
141
+ _p.onStart(this);
142
+ if (reset) {
143
+ _p.reset();
144
+ }
126
145
  _p.state = true;
127
146
  _p.plan();
128
147
  return true;
@@ -131,16 +150,28 @@ var Pulse = class {
131
150
  * Stop the pulse loop (no-op if already stopped).
132
151
  * @returns {boolean} `true` if it stopped now, `false` if it was already stopped.
133
152
  */
134
- stop() {
153
+ stop(reset = false) {
135
154
  const { state } = this;
136
155
  if (!state) {
137
156
  return false;
138
157
  }
139
158
  const _p = vault.get(this);
140
- _p.state = false;
141
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();
142
169
  return true;
143
170
  }
171
+ restart(reset = false) {
172
+ this.stop(reset);
173
+ return this.start(reset);
174
+ }
144
175
  };
145
176
 
146
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 = (getNow) => {\r\n const p = {};\r\n const w = [];\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 }\r\n\r\n const onPulse = valid(\"function\", options.onPulse, true, \"options.onPulse\");\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 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 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.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\r\n const md = _p.metaData = noMeta ? undefined : createMetaData(getNow);\r\n let error;\r\n\r\n try {\r\n const result = await onPulse(md);\r\n if (md) { solid(md, \"result\", result); }\r\n }\r\n catch (err) {\r\n error = err;\r\n if (md) { solid(md, \"error\", err); }\r\n }\r\n\r\n if (md) { solid(md, \"ended\", getNow()); }\r\n if (error) { onError(error, md); }\r\n\r\n try {\r\n await afterPulse(md);\r\n delete _p.metaData;\r\n _p.plan();\r\n }\r\n catch(err) {\r\n _p.state = false;\r\n throw err;\r\n }\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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",
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
6
  "names": []
7
7
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@randajan/pulse",
3
- "version": "0.1.0",
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",