@randajan/pulse 1.1.4 → 3.0.0

package/dist/cjs/index.cjs

@@ -20,20 +20,20 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   Pulse: () => Pulse,
+  PulseCycle: () => PulseCycle,
+  PulseError: () => PulseError,
+  PulseExecuteError: () => PulseExecuteError,
+  PulseRuntimeError: () => PulseRuntimeError,
+  PulseScheduleError: () => PulseScheduleError,
+  PulseSession: () => PulseSession,
+  PulseStartError: () => PulseStartError,
+  PulseStopError: () => PulseStopError,
   createPulse: () => createPulse,
   default: () => index_default,
-  stopAllPulses: () => stopAllPulses
+  handleError: () => handleError
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/Pulse.js
-var import_props2 = require("@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") => {
@@ -41,179 +41,477 @@ 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/metadata.js
-var import_props = require("@randajan/props");
-var createMetaData = (id, getNow) => {
-  const p = {};
-  const w = [];
-  (0, import_props.solid)(p, "id", id);
-  (0, import_props.solid)(p, "started", getNow());
-  (0, import_props.virtual)(p, "warnings", (_) => [...w]);
-  (0, import_props.virtual)(p, "runtime", (_) => (p.ended ? p.ended : getNow()) - p.started);
-  (0, import_props.solid)(p, "warn", (warning) => w.push(warning), false);
-  return p;
+// src/options.js
+var blankFn = () => {
+};
+var formatOptions = (options) => {
+  const o = {};
+  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;
+  o.interval = validRange(minInterval, maxInterval, options.interval, true, "options.interval");
+  o.runOnStart = valid("boolean", options.runOnStart, false, "options.runOnStart") || false;
+  const offsetMsg = `options.offset (align:${o.align})`;
+  if (o.align) {
+    o.offset = validRange(0, o.interval, options.offset, false, offsetMsg) ?? 0;
+  } else if (!o.runOnStart) {
+    o.offset = validRange(-o.interval, maxInterval - o.interval, options.offset, false, offsetMsg) ?? 0;
+  } else if (options.offset != null) {
+    throw new Error(`${offsetMsg} can't be set if runOnStart:true`);
+  } else {
+    o.offset = -o.interval;
+  }
+  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");
+  o.autoStart = valid("boolean", options.autoStart, false, "options.autoStart") || false;
+  return Object.freeze(o);
 };
 
-// src/Pulse.js
-var Pulse = class {
-  /**
-   * Create a new Pulse instance.
-   * @param {PulseOptions} [options={}]  See {@link PulseOptions}.
-   */
-  constructor(options = {}) {
-    const _p = {
-      state: false,
-      nextId: 0
-    };
-    const getNow = valid("function", options.getNow, false, "options.getNow") || ((_) => Date.now());
-    const interval = validRange(10, 2147483647, options.interval, true, "options.interval");
-    const offset = validRange(0, interval, options.offset, false, "options.offset") || 0;
-    const onPulse = valid("function", options.onPulse, true, "options.onPulse");
-    _p.onStart = valid("function", options.onStart, false, "options.onStart") || blankFn;
-    _p.onStop = valid("function", options.onStop, false, "options.onStop") || blankFn;
-    const onError = valid("function", options.onError, false, "options.onError") || blankFn;
-    const afterPulse = valid("function", options.afterPulse, false, "options.afterPulse") || blankFn;
-    const autoStart = valid("boolean", options.autoStart, false, "options.autoStart") || false;
-    const noMeta = valid("boolean", options.noMeta, false, "option.noMeta") || false;
-    _p.reset = (_) => {
-      _p.nextId = 0;
-    };
-    _p.plan = (_) => {
-      if (!_p.state || _p.metaData != null) {
-        return;
-      }
-      _p.timeoutId = setTimeout(_p.run, this.countdown);
-    };
-    _p.run = async (_) => {
-      if (!_p.state || _p.metaData) {
-        return;
-      }
-      const id = _p.nextId++;
-      const md = _p.metaData = noMeta ? id : createMetaData(id, getNow);
-      let errA, errB, result;
-      try {
-        result = await onPulse(this, md);
-        if (!noMeta) {
-          (0, import_props2.solid)(md, "result", result);
-        }
-      } catch (err) {
-        errA = err;
-        if (!noMeta) {
-          (0, import_props2.solid)(md, "error", errA);
-        }
-      }
-      if (!noMeta) {
-        (0, import_props2.solid)(md, "ended", getNow());
-      }
-      if (errA != null) {
-        if (noMeta) {
-          onError(this, errA, md);
-        } else {
-          onError(this, md);
-        }
-      }
-      try {
-        await afterPulse(this, md);
-      } catch (err) {
-        errB = err;
-      }
-      _p.last = noMeta ? result : md;
-      delete _p.metaData;
-      if (errB != null) {
-        _p.state = false;
-        throw errB;
-      }
-      _p.plan();
-    };
-    (0, import_props2.virtuals)(this, {
-      state: (_) => _p.state,
-      last: (_) => _p.last,
-      countdown: (_) => interval - getNow() % interval + offset
-    });
-    (0, import_props2.solids)(this, {
-      interval,
-      offset
-    });
-    _pulses.set(this, _p);
-    if (autoStart) {
-      this.start();
+// src/errors.js
+var PulseError = class extends Error {
+  constructor(type, name, cause) {
+    super(`Pulse ${type} failed`, { cause });
+    this.name = name;
+    this.pulseErrType = type;
+  }
+};
+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);
     }
   }
-  /**
-   * Start the pulse loop (no-op if already running).
-   * @returns {boolean} `true` if it started now, `false` if it was already running.
-   */
-  start(reset = false) {
-    const { state } = this;
-    if (state) {
+};
+
+// 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;
     }
-    const _p = _pulses.get(this);
-    _p.onStart(this);
-    if (reset) {
-      _p.reset();
+    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;
     }
-    _p.state = true;
-    _p.plan();
+    this.#done = true;
+    this.#ended = getNow();
     return true;
   }
-  /**
-   * Stop the pulse loop (no-op if already stopped).
-   * @returns {boolean} `true` if it stopped now, `false` if it was already stopped.
-   */
-  stop(reset = false) {
-    const { state } = this;
-    if (!state) {
+  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;
     }
-    const _p = _pulses.get(this);
-    clearTimeout(_p.timeoutId);
-    _p.state = false;
-    if (reset) {
-      _p.reset();
+    this.#state = true;
+    try {
+      this.#opt.onStart(this);
+    } catch (err) {
+      this.#state = false;
+      this.#ctrl.abort(err);
+      throw new PulseStartError(err);
     }
-    _p.onStop(this);
-    return true;
+    return this.#schedule(true);
   }
-  reset() {
-    _pulses.get(this).reset();
+  stop(reason) {
+    if (!this.#state) {
+      return false;
+    }
+    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));
+    }
     return true;
   }
-  restart(reset = false) {
-    this.stop(reset);
-    return this.start(reset);
+  #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;
+    }
+    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;
+    }
+  }
+  #tick = async () => {
+    if (!this.state || this.#current != null) {
+      return;
+    }
+    let cycle;
+    try {
+      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) {
+      this.stop(new PulseExecuteError(err));
+    }
+    if (!this.state) {
+      return;
+    }
+    if (cycle && this.#current === cycle) {
+      this.#last = cycle;
+      this.#current = null;
+    }
+    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/static.js
-var createPulse = (options = {}) => new Pulse(options);
-var stopAllPulses = () => {
-  for (const [pulse, _pulse] of _pulses.entries()) {
-    pulse.stop();
+// src/class/Pulse.js
+var Pulse = class {
+  #opt;
+  #session = null;
+  #nextId = 0;
+  #last;
+  constructor(options = {}) {
+    this.#opt = formatOptions(options);
+    if (this.#opt.autoStart) {
+      this.start();
+    }
+  }
+  get session() {
+    return this.#session;
+  }
+  get state() {
+    return this.#session?.state ?? false;
+  }
+  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() {
+    throw new Error("[pulse] reset() is obsolete");
   }
 };
 
 // src/index.js
+var createPulse = (options = {}) => new Pulse(options);
 var index_default = createPulse;
-//# sourceMappingURL=index.js.map
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Pulse,
+  PulseCycle,
+  PulseError,
+  PulseExecuteError,
+  PulseRuntimeError,
+  PulseScheduleError,
+  PulseSession,
+  PulseStartError,
+  PulseStopError,
+  createPulse,
+  handleError
+});
+//# sourceMappingURL=index.cjs.map