@randajan/pulse 2.0.0 → 3.0.0

package/dist/esm/index.mjs

@@ -1,11 +1,3 @@
-// src/Pulse.js
-import { solid as solid3, solids, virtuals } from "@randajan/props";
-
-// src/const.js
-var _pulses = /* @__PURE__ */ new Map();
-var blankFn = () => {
-};
-
 // src/tools.js
 var is = (type, any) => typeof any === type;
 var valid = (type, any, req = false, msg = "argument") => {
@@ -13,31 +5,61 @@ var valid = (type, any, req = false, msg = "argument") => {
     if (!req) {
       return;
     }
-    throw new Error(`${msg} require typeof '${type}'`);
+    throw new Error(`[pulse] ${msg} require typeof '${type}'`);
   }
   if (is(type, any)) {
     return any;
   }
-  throw new Error(`${msg} is not typeof '${type}'`);
+  throw new Error(`[pulse] ${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 (min != null && num < min) {
+    throw new Error(`[pulse] ${msg} must be >= ${min}`);
   }
-  if (num > max) {
-    throw new Error(`${msg} must be less than ${max}`);
+  if (max != null && num > max) {
+    throw new Error(`[pulse] ${msg} must be <= ${max}`);
   }
   return num;
 };
+var validRangeFinite = (min, any, req = false, msg = "argument") => {
+  const num = validRange(min, null, any, req, msg);
+  if (num == null) {
+    return;
+  }
+  if (!Number.isFinite(num)) {
+    throw new Error(`[pulse] ${msg} must be finite`);
+  }
+  return num;
+};
+var validateGetNow = (options) => {
+  const custom = valid("function", options.getNow, false, "options.getNow");
+  if (!custom) {
+    return (_) => Date.now();
+  }
+  const safe = (_) => validRangeFinite(0, custom(), true, "options.getNow result");
+  safe();
+  return safe;
+};
 
-// src/static/options.js
+// src/options.js
+var blankFn = () => {
+};
 var formatOptions = (options) => {
   const o = {};
-  o.getNow = valid("function", options.getNow, false, "options.getNow") || ((_) => Date.now());
+  if (options.noMeta != null) {
+    throw new Error("options.noMeta is obsolete");
+  }
+  if (options.maxRuns != null) {
+    throw new Error("options.maxRuns is obsolete");
+  }
+  if (options.afterPulse != null) {
+    throw new Error("options.afterPulse is obsolete");
+  }
+  o.getNow = validateGetNow(options);
   o.align = valid("boolean", options.align, true, "options.align");
   const minInterval = 10;
   const maxInterval = 2147483647;
@@ -53,215 +75,407 @@ var formatOptions = (options) => {
   } else {
     o.offset = -o.interval;
   }
-  o.maxRuns = validRange(0, Infinity, options.maxRuns, false, "options.maxRuns") ?? 0;
   o.onPulse = valid("function", options.onPulse, true, "options.onPulse");
   o.onStart = valid("function", options.onStart, false, "options.onStart") || blankFn;
   o.onStop = valid("function", options.onStop, false, "options.onStop") || blankFn;
-  o.onError = valid("function", options.onError, false, "options.onError") || blankFn;
-  o.afterPulse = valid("function", options.afterPulse, false, "options.afterPulse") || blankFn;
+  o.onError = valid("function", options.onError, false, "options.onError");
   o.autoStart = valid("boolean", options.autoStart, false, "options.autoStart") || false;
-  o.noMeta = valid("boolean", options.noMeta, false, "option.noMeta") || false;
   return Object.freeze(o);
 };
 
-// src/static/PulsePrivate.js
-import { solid as solid2 } from "@randajan/props";
-
-// src/static/metadata.js
-import { solid, virtual } from "@randajan/props";
-var createMetaData = (_p, id) => {
-  const md = {};
-  const w = [];
-  solid(md, "id", id);
-  solid(md, "started", _p.opt.getNow());
-  virtual(md, "warnings", (_) => [...w]);
-  virtual(md, "runtime", (_) => (md.ended ? md.ended : _p.opt.getNow()) - md.started);
-  virtual(md, "lateBy", (_) => Math.max(0, md.runtime - _p.opt.interval));
-  solid(md, "warn", (warning) => w.push(warning), false);
-  return md;
+// src/errors.js
+var PulseError = class extends Error {
+  constructor(type, name, cause) {
+    super(`Pulse ${type} failed`, { cause });
+    this.name = name;
+    this.pulseErrType = type;
+  }
 };
-
-// src/static/PulsePrivate.js
-var PulsePrivate = class {
-  constructor(pulse, options) {
-    this.pulse = pulse;
-    this.state = false;
-    this.nextId = 0;
-    this.opt = formatOptions(options);
-    this.run = this.run.bind(this);
-  }
-  getCountdown() {
-    const { state, fireAt, opt: { getNow } } = this;
-    if (!state || fireAt == null) {
-      return;
+var PulseStartError = class extends PulseError {
+  constructor(cause) {
+    super("start", "PulseStartError", cause);
+  }
+};
+var PulseStopError = class extends PulseError {
+  constructor(cause) {
+    super("stop", "PulseStopError", cause);
+  }
+};
+var PulseScheduleError = class extends PulseError {
+  constructor(cause) {
+    super("schedule", "PulseScheduleError", cause);
+  }
+};
+var PulseExecuteError = class extends PulseError {
+  constructor(cause) {
+    super("execute", "PulseExecuteError", cause);
+  }
+};
+var PulseRuntimeError = class extends PulseError {
+  constructor(cause) {
+    super("runtime", "PulseRuntimeError", cause);
+  }
+};
+var getErrType = (err) => {
+  if (err instanceof PulseError) {
+    return err.pulseErrType;
+  }
+  return "unknown";
+};
+var handleError = async (pulse, error, onError) => {
+  const type = getErrType(error);
+  if (!onError) {
+    console.error(`[pulse] ${type} error:`, error);
+  } else {
+    try {
+      await onError(pulse, type, error);
+    } catch (e2) {
+      console.error(`[pulse] options.onError('${type}') failed: `, e2);
     }
-    return Math.max(0, fireAt - getNow());
   }
-  getPotential(isInit = true) {
-    const { opt: { align, runOnStart, interval, offset, getNow } } = this;
-    if (isInit && runOnStart) {
-      return 0;
+};
+
+// src/class/PulseCycle.js
+var PulseCycle = class {
+  #pulse = null;
+  #session = null;
+  #opt = null;
+  #warnings = [];
+  #ok = true;
+  #id = void 0;
+  #done = void 0;
+  #result = void 0;
+  #error = void 0;
+  #started = void 0;
+  #ended = void 0;
+  constructor(pulse, session, opt) {
+    this.#pulse = pulse;
+    this.#session = session;
+    this.#opt = opt;
+  }
+  get pulse() {
+    return this.#pulse;
+  }
+  get session() {
+    return this.#session;
+  }
+  get signal() {
+    return this.#session.signal;
+  }
+  get id() {
+    return this.#id;
+  }
+  get ok() {
+    return this.#ok;
+  }
+  get done() {
+    return this.#done;
+  }
+  get started() {
+    return this.#started;
+  }
+  get ended() {
+    return this.#ended;
+  }
+  get runtime() {
+    return (this.#done ? this.#ended : this.#opt.getNow()) - this.#started;
+  }
+  get lateBy() {
+    return Math.max(0, this.runtime - this.#opt.interval);
+  }
+  get warnings() {
+    return [...this.#warnings];
+  }
+  get result() {
+    return this.#result;
+  }
+  get error() {
+    return this.#error;
+  }
+  warn(warning) {
+    return this.#warnings.push(warning);
+  }
+  async _execute(id) {
+    if (this.#id != null) {
+      return false;
     }
-    if (!align) {
-      return isInit ? interval + offset : interval;
+    const { getNow, onPulse } = this.#opt;
+    this.#id = id;
+    this.#started = getNow();
+    try {
+      this.#result = await onPulse(this);
+    } catch (err) {
+      this.#error = err;
+      this.#ok = false;
     }
-    const now = getNow() - offset;
-    const rest = (now % interval + interval) % interval;
-    return rest === 0 ? interval : interval - rest;
-  }
-  reset() {
-    this.nextId = 0;
+    this.#done = true;
+    this.#ended = getNow();
     return true;
   }
-  start(reset = false) {
-    const { pulse, state, timeoutId, opt: { onStart } } = this;
-    if (state) {
+  toJSON() {
+    const { id, ok, done, started, ended, runtime, lateBy, warnings, result, error } = this;
+    return { id, ok, done, started, ended, runtime, lateBy, warnings, result, error };
+  }
+};
+
+// src/class/PulseSession.js
+var PulseSession = class {
+  #pulse = null;
+  #opt = null;
+  #ctrl = new AbortController();
+  #state = false;
+  #timeoutId;
+  #fireAt;
+  #current = null;
+  #last;
+  #consumeNextId;
+  constructor(pulse, opt, consumeNextId) {
+    this.#pulse = pulse;
+    this.#opt = opt;
+    this.#consumeNextId = consumeNextId;
+  }
+  get pulse() {
+    return this.#pulse;
+  }
+  get signal() {
+    return this.#ctrl.signal;
+  }
+  get interval() {
+    return this.#opt.interval;
+  }
+  get offset() {
+    return this.#opt.offset;
+  }
+  get align() {
+    return this.#opt.align;
+  }
+  get state() {
+    return this.#state && !this.#ctrl.signal.aborted;
+  }
+  get current() {
+    return this.#current;
+  }
+  get last() {
+    return this.#last;
+  }
+  get countdown() {
+    return this.calculateCountdown();
+  }
+  get potential() {
+    return this.#pulse.potential;
+  }
+  get nextAt() {
+    return this.state ? this.#pulse.potential + this.#opt.getNow() : void 0;
+  }
+  get nextId() {
+    return this.#pulse.nextId;
+  }
+  calculateCountdown() {
+    if (!this.state || this.#fireAt == null) {
+      return;
+    }
+    return Math.max(0, this.#fireAt - this.#opt.getNow());
+  }
+  start() {
+    if (this.#state) {
       return false;
     }
-    onStart(pulse);
-    if (reset) {
-      this.reset();
+    this.#state = true;
+    try {
+      this.#opt.onStart(this);
+    } catch (err) {
+      this.#state = false;
+      this.#ctrl.abort(err);
+      throw new PulseStartError(err);
     }
-    this.state = true;
-    return this.plan(true);
+    return this.#schedule(true);
   }
-  stop(reset = false) {
-    const { pulse, state, timeoutId, opt: { onStop } } = this;
-    if (!state) {
+  stop(reason) {
+    if (!this.#state) {
       return false;
     }
-    clearTimeout(timeoutId);
-    this.state = false;
-    delete this.fireAt;
-    if (reset) {
-      this.reset();
+    if (this.#pulse.session === this) {
+      return this.#pulse.stop(reason);
+    }
+    this.#state = false;
+    clearTimeout(this.#timeoutId);
+    this.#fireAt = void 0;
+    this.#current = null;
+    this.#ctrl.abort(reason);
+    if (reason != null) {
+      this.#handleError(reason);
+    }
+    try {
+      this.#opt.onStop(this, reason);
+    } catch (err) {
+      this.#handleError(new PulseStopError(err));
     }
-    onStop(pulse);
     return true;
   }
-  plan(isInit) {
-    const { state, metaData, nextId, opt: { maxRuns, getNow } } = this;
-    if (!state || metaData != null) {
+  #handleError(error) {
+    return handleError(this.pulse, error, this.#opt.onError);
+  }
+  // Even a temporarily broken clock/configuration must not permanently stall scheduling.
+  #schedule(isInit) {
+    if (!this.state || this.#current != null) {
       return false;
     }
-    if (maxRuns && maxRuns <= nextId) {
-      this.stop(true);
+    try {
+      const fireIn = this.#pulse.calculatePotential(isInit);
+      this.#fireAt = this.#opt.getNow() + fireIn;
+      this.#timeoutId = setTimeout(this.#tick, fireIn);
+      this.#timeoutId.unref?.();
+      return true;
+    } catch (err) {
+      this.stop(new PulseScheduleError(err));
       return false;
     }
-    const fireIn = this.getPotential(isInit);
-    this.fireAt = getNow() + fireIn;
-    this.timeoutId = setTimeout(this.run, fireIn);
-    this.timeoutId.unref?.();
-    return true;
   }
-  async run() {
-    const { pulse, state, metaData, opt: { noMeta, getNow, onPulse, onError, afterPulse } } = this;
-    if (!state || metaData) {
+  #tick = async () => {
+    if (!this.state || this.#current != null) {
       return;
     }
-    const id = this.nextId++;
-    const md = this.metaData = noMeta ? id : createMetaData(this, id);
-    let errA, errB, result;
+    let cycle;
     try {
-      result = await onPulse(pulse, md);
-      if (!noMeta) {
-        solid2(md, "result", result);
+      this.#current = cycle = new PulseCycle(this.#pulse, this, this.#opt);
+      await cycle._execute(this.#consumeNextId());
+      if (!cycle.ok) {
+        this.#handleError(new PulseRuntimeError(cycle.error));
       }
     } catch (err) {
-      errA = err;
-      if (!noMeta) {
-        solid2(md, "error", errA);
-      }
-    }
-    if (!noMeta) {
-      solid2(md, "ended", getNow());
-    }
-    if (errA != null) {
-      if (noMeta) {
-        onError(pulse, errA, md);
-      } else {
-        onError(pulse, md);
-      }
+      this.stop(new PulseExecuteError(err));
     }
-    try {
-      await afterPulse(pulse, md);
-    } catch (err) {
-      errB = err;
+    if (!this.state) {
+      return;
     }
-    this.last = noMeta ? result : md;
-    delete this.metaData;
-    if (errB != null) {
-      this.stop();
-      throw errB;
+    if (cycle && this.#current === cycle) {
+      this.#last = cycle;
+      this.#current = null;
     }
-    this.plan(false);
-  }
-  restart(reset) {
-    this.stop(reset);
-    return this.start(reset);
+    this.#schedule(false);
+  };
+  toJSON() {
+    const { interval, offset, align, state, current, last, countdown, potential, nextAt, nextId } = this;
+    return { interval, offset, align, state, current, last, countdown, potential, nextAt, nextId };
   }
 };
 
-// src/Pulse.js
+// src/class/Pulse.js
 var Pulse = class {
-  /**
-   * Create a new Pulse instance.
-   * @param {PulseOptions} [options={}]  See {@link PulseOptions}.
-   */
+  #opt;
+  #session = null;
+  #nextId = 0;
+  #last;
   constructor(options = {}) {
-    const _p = new PulsePrivate(this, options);
-    const { getNow, align, interval, offset, autoStart } = _p.opt;
-    virtuals(this, {
-      state: (_) => _p.state,
-      last: (_) => _p.last,
-      countdown: (_) => _p.getCountdown(),
-      potential: (_) => _p.getCountdown() ?? _p.getPotential(),
-      nextAt: (_) => _p.state ? this.potential + getNow() : void 0
-    });
-    solids(this, {
-      interval,
-      offset,
-      align
-    });
-    _pulses.set(this, _p);
-    if (autoStart) {
+    this.#opt = formatOptions(options);
+    if (this.#opt.autoStart) {
       this.start();
     }
   }
-  /**
-   * Start the pulse loop (no-op if already running).
-   * @returns {boolean} `true` if it started now, `false` if it was already running.
-   */
-  start(reset = false) {
-    return _pulses.get(this).start(reset);
+  get session() {
+    return this.#session;
   }
-  /**
-   * Stop the pulse loop (no-op if already stopped).
-   * @returns {boolean} `true` if it stopped now, `false` if it was already stopped.
-   */
-  stop(reset = false) {
-    return _pulses.get(this).stop(reset);
+  get state() {
+    return this.#session?.state ?? false;
   }
-  restart(reset = false) {
-    return _pulses.get(this).restart(reset);
+  get current() {
+    return this.#session?.current;
+  }
+  get last() {
+    return this.#session?.last ?? this.#last;
+  }
+  get countdown() {
+    return this.#session?.countdown;
+  }
+  get potential() {
+    return this.countdown ?? this.calculatePotential();
+  }
+  get nextAt() {
+    return this.state ? this.potential + this.#opt.getNow() : void 0;
+  }
+  get nextId() {
+    return this.#nextId;
+  }
+  get interval() {
+    return this.#opt.interval;
+  }
+  get offset() {
+    return this.#opt.offset;
+  }
+  get align() {
+    return this.#opt.align;
+  }
+  calculatePotential(isInit = true) {
+    const { align, runOnStart, interval, offset, getNow } = this.#opt;
+    if (isInit && runOnStart) {
+      return 0;
+    }
+    if (!align) {
+      return isInit ? interval + offset : interval;
+    }
+    const now = getNow() - offset;
+    const rest = (now % interval + interval) % interval;
+    return rest === 0 ? interval : interval - rest;
+  }
+  #handleError(error) {
+    return handleError(this, error, this.#opt.onError);
+  }
+  #consumeNextId = () => this.#nextId++;
+  /** Start a new session. Returns false if already running. */
+  start() {
+    if (this.state) {
+      return false;
+    }
+    const session = new PulseSession(this, this.#opt, this.#consumeNextId);
+    this.#session = session;
+    try {
+      return session.start();
+    } catch (err) {
+      if (this.#session === session) {
+        this.#session = null;
+      }
+      this.#handleError(err);
+      throw err;
+    }
+  }
+  /** Stop the current session, without cancelling a newer one. */
+  stop(reason) {
+    const session = this.#session;
+    if (!session?.state) {
+      return false;
+    }
+    this.#session = null;
+    this.#last = session.last ?? this.#last;
+    return session.stop(reason);
+  }
+  restart() {
+    this.stop();
+    return this.start();
+  }
+  toJSON() {
+    const { interval, offset, align, state, current, last, countdown, potential, nextAt, nextId } = this;
+    return { interval, offset, align, state, current, last, countdown, potential, nextAt, nextId };
   }
   reset() {
-    return _pulses.get(this).reset();
+    throw new Error("[pulse] reset() is obsolete");
   }
 };
 
 // src/index.js
 var createPulse = (options = {}) => new Pulse(options);
-var stopAllPulses = () => {
-  for (const [pulse, _pulse] of _pulses.entries()) {
-    pulse.stop();
-  }
-};
 var index_default = createPulse;
 export {
   Pulse,
+  PulseCycle,
+  PulseError,
+  PulseExecuteError,
+  PulseRuntimeError,
+  PulseScheduleError,
+  PulseSession,
+  PulseStartError,
+  PulseStopError,
   createPulse,
   index_default as default,
-  stopAllPulses
+  handleError
 };
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.mjs.map