@crup/react-timer-hook 0.0.1-alpha.2

package/dist/index.cjs

@@ -0,0 +1,841 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  durationParts: () => durationParts,
+  useTimer: () => useTimer,
+  useTimerGroup: () => useTimerGroup
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/durationParts.ts
+var SECOND = 1e3;
+var MINUTE = 60 * SECOND;
+var HOUR = 60 * MINUTE;
+var DAY = 24 * HOUR;
+function durationParts(milliseconds) {
+  const totalMilliseconds = Math.max(0, Math.trunc(Number.isFinite(milliseconds) ? milliseconds : 0));
+  const days = Math.floor(totalMilliseconds / DAY);
+  const afterDays = totalMilliseconds % DAY;
+  const hours = Math.floor(afterDays / HOUR);
+  const afterHours = afterDays % HOUR;
+  const minutes = Math.floor(afterHours / MINUTE);
+  const afterMinutes = afterHours % MINUTE;
+  const seconds = Math.floor(afterMinutes / SECOND);
+  return {
+    totalMilliseconds,
+    totalSeconds: Math.floor(totalMilliseconds / SECOND),
+    milliseconds: afterMinutes % SECOND,
+    seconds,
+    minutes,
+    hours,
+    days
+  };
+}
+
+// src/useTimer.ts
+var import_react = require("react");
+
+// src/debug.ts
+function resolveDebug(debug) {
+  if (!debug) return { enabled: false, includeTicks: false };
+  if (debug === true) return { enabled: true, includeTicks: false, logger: console.debug };
+  if (typeof debug === "function") return { enabled: true, includeTicks: false, logger: debug };
+  return {
+    enabled: debug.enabled !== false,
+    includeTicks: debug.includeTicks ?? false,
+    label: debug.label,
+    logger: debug.logger ?? console.debug
+  };
+}
+function emitDebug(debug, event) {
+  const config = resolveDebug(debug);
+  if (!config.enabled || !config.logger) return;
+  if (event.type === "timer:tick" && !config.includeTicks) return;
+  config.logger({
+    ...event,
+    label: event.label ?? config.label
+  });
+}
+function baseDebugEvent(snapshot, generation) {
+  return {
+    generation,
+    tick: snapshot.tick,
+    now: snapshot.now,
+    elapsedMilliseconds: snapshot.elapsedMilliseconds,
+    status: snapshot.status
+  };
+}
+
+// src/clocks.ts
+function readClock() {
+  const wallNow = Date.now();
+  const monotonicNow = typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : wallNow;
+  return { wallNow, monotonicNow };
+}
+function validatePositiveFinite(value, name) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new RangeError(`${name} must be a finite number greater than 0`);
+  }
+}
+
+// src/state.ts
+function createTimerState(clock) {
+  return {
+    status: "idle",
+    generation: 0,
+    tick: 0,
+    startedAt: null,
+    pausedAt: null,
+    endedAt: null,
+    cancelledAt: null,
+    cancelReason: null,
+    baseElapsedMilliseconds: 0,
+    activeStartedAtMonotonic: null,
+    now: clock.wallNow
+  };
+}
+function getElapsedMilliseconds(state, clock) {
+  if (state.status !== "running" || state.activeStartedAtMonotonic === null) {
+    return state.baseElapsedMilliseconds;
+  }
+  return Math.max(0, state.baseElapsedMilliseconds + clock.monotonicNow - state.activeStartedAtMonotonic);
+}
+function toSnapshot(state, clock) {
+  const elapsedMilliseconds = getElapsedMilliseconds(state, clock);
+  return {
+    status: state.status,
+    now: clock.wallNow,
+    tick: state.tick,
+    startedAt: state.startedAt,
+    pausedAt: state.pausedAt,
+    endedAt: state.endedAt,
+    cancelledAt: state.cancelledAt,
+    cancelReason: state.cancelReason,
+    elapsedMilliseconds,
+    isIdle: state.status === "idle",
+    isRunning: state.status === "running",
+    isPaused: state.status === "paused",
+    isEnded: state.status === "ended",
+    isCancelled: state.status === "cancelled"
+  };
+}
+function startTimerState(state, clock) {
+  if (state.status !== "idle") return false;
+  state.status = "running";
+  state.startedAt = clock.wallNow;
+  state.pausedAt = null;
+  state.endedAt = null;
+  state.cancelledAt = null;
+  state.cancelReason = null;
+  state.activeStartedAtMonotonic = clock.monotonicNow;
+  state.now = clock.wallNow;
+  return true;
+}
+function pauseTimerState(state, clock) {
+  if (state.status !== "running") return false;
+  state.baseElapsedMilliseconds = getElapsedMilliseconds(state, clock);
+  state.activeStartedAtMonotonic = null;
+  state.status = "paused";
+  state.pausedAt = clock.wallNow;
+  state.now = clock.wallNow;
+  return true;
+}
+function resumeTimerState(state, clock) {
+  if (state.status !== "paused") return false;
+  state.status = "running";
+  state.pausedAt = null;
+  state.activeStartedAtMonotonic = clock.monotonicNow;
+  state.now = clock.wallNow;
+  return true;
+}
+function resetTimerState(state, clock, options = {}) {
+  state.generation += 1;
+  state.tick = 0;
+  state.status = options.autoStart ? "running" : "idle";
+  state.startedAt = options.autoStart ? clock.wallNow : null;
+  state.pausedAt = null;
+  state.endedAt = null;
+  state.cancelledAt = null;
+  state.cancelReason = null;
+  state.baseElapsedMilliseconds = 0;
+  state.activeStartedAtMonotonic = options.autoStart ? clock.monotonicNow : null;
+  state.now = clock.wallNow;
+  return true;
+}
+function restartTimerState(state, clock) {
+  return resetTimerState(state, clock, { autoStart: true });
+}
+function cancelTimerState(state, clock, reason) {
+  if (state.status === "ended" || state.status === "cancelled") return false;
+  state.baseElapsedMilliseconds = getElapsedMilliseconds(state, clock);
+  state.activeStartedAtMonotonic = null;
+  state.status = "cancelled";
+  state.cancelledAt = clock.wallNow;
+  state.cancelReason = reason ?? null;
+  state.now = clock.wallNow;
+  return true;
+}
+function endTimerState(state, clock) {
+  if (state.status !== "running") return false;
+  state.baseElapsedMilliseconds = getElapsedMilliseconds(state, clock);
+  state.activeStartedAtMonotonic = null;
+  state.status = "ended";
+  state.endedAt = clock.wallNow;
+  state.now = clock.wallNow;
+  return true;
+}
+function tickTimerState(state, clock) {
+  if (state.status !== "running") return false;
+  state.tick += 1;
+  state.now = clock.wallNow;
+  return true;
+}
+
+// src/useTimer.ts
+function useTimer(options = {}) {
+  const updateIntervalMs = options.updateIntervalMs ?? 1e3;
+  validatePositiveFinite(updateIntervalMs, "updateIntervalMs");
+  validateSchedules(options.schedules);
+  const optionsRef = (0, import_react.useRef)(options);
+  optionsRef.current = options;
+  const stateRef = (0, import_react.useRef)(null);
+  if (stateRef.current === null) {
+    stateRef.current = createTimerState(readClock());
+  }
+  const mountedRef = (0, import_react.useRef)(false);
+  const timeoutRef = (0, import_react.useRef)(null);
+  const schedulesRef = (0, import_react.useRef)(/* @__PURE__ */ new Map());
+  const endCalledGenerationRef = (0, import_react.useRef)(null);
+  const [, rerender] = (0, import_react.useReducer)((value) => value + 1, 0);
+  const clearScheduledTick = (0, import_react.useCallback)(() => {
+    if (timeoutRef.current !== null) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+  }, []);
+  const getSnapshot = (0, import_react.useCallback)((clock = readClock()) => {
+    return toSnapshot(stateRef.current, clock);
+  }, []);
+  const emit = (0, import_react.useCallback)(
+    (type, snapshot2, extra = {}) => {
+      emitDebug(optionsRef.current.debug, {
+        type,
+        scope: "timer",
+        ...baseDebugEvent(snapshot2, stateRef.current.generation),
+        ...extra
+      });
+    },
+    []
+  );
+  const controlsRef = (0, import_react.useRef)(null);
+  const callOnEnd = (0, import_react.useCallback)(
+    (snapshot2) => {
+      const generation2 = stateRef.current.generation;
+      if (endCalledGenerationRef.current === generation2) return;
+      endCalledGenerationRef.current = generation2;
+      try {
+        void optionsRef.current.onEnd?.(snapshot2, controlsRef.current);
+      } catch (error) {
+        emitDebug(optionsRef.current.debug, {
+          type: "callback:error",
+          scope: "timer",
+          ...baseDebugEvent(snapshot2, generation2),
+          error
+        });
+      }
+    },
+    []
+  );
+  const runSchedule = (0, import_react.useCallback)(
+    (schedule, key, scheduleState, snapshot2, generation2) => {
+      if (scheduleState.pending && (schedule.overlap ?? "skip") === "skip") {
+        emitDebug(optionsRef.current.debug, {
+          type: "schedule:skip",
+          scope: "timer",
+          scheduleId: schedule.id ?? key,
+          reason: "overlap",
+          ...baseDebugEvent(snapshot2, generation2)
+        });
+        return;
+      }
+      scheduleState.lastRunAt = snapshot2.now;
+      scheduleState.pending = true;
+      emitDebug(optionsRef.current.debug, {
+        type: "schedule:start",
+        scope: "timer",
+        scheduleId: schedule.id ?? key,
+        ...baseDebugEvent(snapshot2, generation2)
+      });
+      Promise.resolve().then(() => schedule.callback(snapshot2, controlsRef.current)).then(
+        () => {
+          emitDebug(optionsRef.current.debug, {
+            type: "schedule:end",
+            scope: "timer",
+            scheduleId: schedule.id ?? key,
+            ...baseDebugEvent(snapshot2, generation2)
+          });
+        },
+        (error) => {
+          emitDebug(optionsRef.current.debug, {
+            type: "schedule:error",
+            scope: "timer",
+            scheduleId: schedule.id ?? key,
+            error,
+            ...baseDebugEvent(snapshot2, generation2)
+          });
+        }
+      ).finally(() => {
+        if (stateRef.current?.generation === generation2) {
+          scheduleState.pending = false;
+        }
+      });
+    },
+    []
+  );
+  const evaluateSchedules = (0, import_react.useCallback)(
+    (snapshot2, generation2, activation = false) => {
+      const schedules = optionsRef.current.schedules ?? [];
+      const liveKeys = /* @__PURE__ */ new Set();
+      schedules.forEach((schedule, index) => {
+        const key = schedule.id ?? String(index);
+        liveKeys.add(key);
+        let scheduleState = schedulesRef.current.get(key);
+        if (!scheduleState) {
+          scheduleState = { lastRunAt: null, pending: false, leadingGeneration: null };
+          schedulesRef.current.set(key, scheduleState);
+        }
+        if (activation && schedule.leading && scheduleState.leadingGeneration !== generation2) {
+          scheduleState.leadingGeneration = generation2;
+          runSchedule(schedule, key, scheduleState, snapshot2, generation2);
+          return;
+        }
+        if (scheduleState.lastRunAt === null) {
+          scheduleState.lastRunAt = snapshot2.now;
+          return;
+        }
+        if (snapshot2.now - scheduleState.lastRunAt >= schedule.everyMs) {
+          runSchedule(schedule, key, scheduleState, snapshot2, generation2);
+        }
+      });
+      for (const key of schedulesRef.current.keys()) {
+        if (!liveKeys.has(key)) schedulesRef.current.delete(key);
+      }
+    },
+    [runSchedule]
+  );
+  const processRunningState = (0, import_react.useCallback)(
+    (clock = readClock(), activation = false) => {
+      const state = stateRef.current;
+      if (state.status !== "running") return;
+      const snapshot2 = toSnapshot(state, clock);
+      const generation2 = state.generation;
+      if (optionsRef.current.endWhen?.(snapshot2)) {
+        if (endTimerState(state, clock)) {
+          const endedSnapshot = toSnapshot(state, clock);
+          emit("timer:end", endedSnapshot);
+          clearScheduledTick();
+          callOnEnd(endedSnapshot);
+          rerender();
+        }
+        return;
+      }
+      evaluateSchedules(snapshot2, generation2, activation);
+    },
+    [callOnEnd, clearScheduledTick, emit, evaluateSchedules]
+  );
+  const start = (0, import_react.useCallback)(() => {
+    const clock = readClock();
+    if (!startTimerState(stateRef.current, clock)) return;
+    const snapshot2 = toSnapshot(stateRef.current, clock);
+    emit("timer:start", snapshot2);
+    processRunningState(clock, true);
+    rerender();
+  }, [emit, processRunningState]);
+  const pause = (0, import_react.useCallback)(() => {
+    const clock = readClock();
+    if (!pauseTimerState(stateRef.current, clock)) return;
+    clearScheduledTick();
+    const snapshot2 = toSnapshot(stateRef.current, clock);
+    emit("timer:pause", snapshot2);
+    rerender();
+  }, [clearScheduledTick, emit]);
+  const resume = (0, import_react.useCallback)(() => {
+    const clock = readClock();
+    if (!resumeTimerState(stateRef.current, clock)) return;
+    const snapshot2 = toSnapshot(stateRef.current, clock);
+    emit("timer:resume", snapshot2);
+    processRunningState(clock, true);
+    rerender();
+  }, [emit, processRunningState]);
+  const reset = (0, import_react.useCallback)(
+    (resetOptions = {}) => {
+      const clock = readClock();
+      clearScheduledTick();
+      resetTimerState(stateRef.current, clock, resetOptions);
+      schedulesRef.current.clear();
+      endCalledGenerationRef.current = null;
+      const snapshot2 = toSnapshot(stateRef.current, clock);
+      emit("timer:reset", snapshot2);
+      if (resetOptions.autoStart) processRunningState(clock, true);
+      rerender();
+    },
+    [clearScheduledTick, emit, processRunningState]
+  );
+  const restart = (0, import_react.useCallback)(() => {
+    const clock = readClock();
+    clearScheduledTick();
+    restartTimerState(stateRef.current, clock);
+    schedulesRef.current.clear();
+    endCalledGenerationRef.current = null;
+    const snapshot2 = toSnapshot(stateRef.current, clock);
+    emit("timer:restart", snapshot2);
+    processRunningState(clock, true);
+    rerender();
+  }, [clearScheduledTick, emit, processRunningState]);
+  const cancel = (0, import_react.useCallback)(
+    (reason) => {
+      const clock = readClock();
+      if (!cancelTimerState(stateRef.current, clock, reason)) return;
+      clearScheduledTick();
+      const snapshot2 = toSnapshot(stateRef.current, clock);
+      emit("timer:cancel", snapshot2, { reason });
+      rerender();
+    },
+    [clearScheduledTick, emit]
+  );
+  controlsRef.current = (0, import_react.useMemo)(
+    () => ({ start, pause, resume, reset, restart, cancel }),
+    [cancel, pause, reset, restart, resume, start]
+  );
+  (0, import_react.useEffect)(() => {
+    mountedRef.current = true;
+    if (optionsRef.current.autoStart && stateRef.current.status === "idle") {
+      controlsRef.current.start();
+    }
+    return () => {
+      mountedRef.current = false;
+      clearScheduledTick();
+    };
+  }, [clearScheduledTick]);
+  const snapshot = getSnapshot();
+  const generation = stateRef.current.generation;
+  const status = snapshot.status;
+  (0, import_react.useEffect)(() => {
+    if (!mountedRef.current || status !== "running") {
+      clearScheduledTick();
+      return;
+    }
+    clearScheduledTick();
+    emit("scheduler:start", getSnapshot());
+    timeoutRef.current = setTimeout(() => {
+      if (!mountedRef.current) return;
+      if (stateRef.current.generation !== generation) return;
+      if (stateRef.current.status !== "running") return;
+      const clock = readClock();
+      tickTimerState(stateRef.current, clock);
+      const tickSnapshot = toSnapshot(stateRef.current, clock);
+      emit("timer:tick", tickSnapshot);
+      processRunningState(clock);
+      rerender();
+    }, optionsRef.current.updateIntervalMs ?? 1e3);
+    return () => {
+      if (timeoutRef.current !== null) {
+        emit("scheduler:stop", getSnapshot());
+      }
+      clearScheduledTick();
+    };
+  }, [clearScheduledTick, emit, generation, getSnapshot, processRunningState, snapshot.tick, status]);
+  return {
+    ...snapshot,
+    ...controlsRef.current
+  };
+}
+function validateSchedules(schedules) {
+  schedules?.forEach((schedule) => validatePositiveFinite(schedule.everyMs, "schedule.everyMs"));
+}
+
+// src/useTimerGroup.ts
+var import_react2 = require("react");
+function useTimerGroup(options = {}) {
+  const updateIntervalMs = options.updateIntervalMs ?? 1e3;
+  validatePositiveFinite(updateIntervalMs, "updateIntervalMs");
+  validateItems(options.items);
+  const optionsRef = (0, import_react2.useRef)(options);
+  optionsRef.current = options;
+  const itemsRef = (0, import_react2.useRef)(/* @__PURE__ */ new Map());
+  const mountedRef = (0, import_react2.useRef)(false);
+  const timeoutRef = (0, import_react2.useRef)(null);
+  const [, rerender] = (0, import_react2.useReducer)((value) => value + 1, 0);
+  const clearScheduledTick = (0, import_react2.useCallback)(() => {
+    if (timeoutRef.current !== null) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+  }, []);
+  const getItemSnapshot = (0, import_react2.useCallback)((item, clock = readClock()) => {
+    return toSnapshot(item.state, clock);
+  }, []);
+  const emit = (0, import_react2.useCallback)(
+    (type, item, snapshot, extra = {}) => {
+      emitDebug(optionsRef.current.debug, {
+        type,
+        scope: "timer-group",
+        timerId: item?.id,
+        ...baseDebugEvent(snapshot, item?.state.generation ?? 0),
+        ...extra
+      });
+    },
+    []
+  );
+  const controlsFor = (0, import_react2.useCallback)((id) => {
+    return {
+      start: () => start(id),
+      pause: () => pause(id),
+      resume: () => resume(id),
+      reset: (resetOptions) => reset(id, resetOptions),
+      restart: () => restart(id),
+      cancel: (reason) => cancel(id, reason)
+    };
+  }, []);
+  const callOnEnd = (0, import_react2.useCallback)(
+    (item, snapshot) => {
+      const generation = item.state.generation;
+      if (item.endCalledGeneration === generation) return;
+      item.endCalledGeneration = generation;
+      try {
+        void item.definition.onEnd?.(snapshot, controlsFor(item.id));
+      } catch (error) {
+        emitDebug(optionsRef.current.debug, {
+          type: "callback:error",
+          scope: "timer-group",
+          timerId: item.id,
+          error,
+          ...baseDebugEvent(snapshot, generation)
+        });
+      }
+    },
+    [controlsFor]
+  );
+  const runSchedule = (0, import_react2.useCallback)(
+    (item, schedule, key, scheduleState, snapshot, generation) => {
+      if (scheduleState.pending && (schedule.overlap ?? "skip") === "skip") {
+        emitDebug(optionsRef.current.debug, {
+          type: "schedule:skip",
+          scope: "timer-group",
+          timerId: item.id,
+          scheduleId: schedule.id ?? key,
+          reason: "overlap",
+          ...baseDebugEvent(snapshot, generation)
+        });
+        return;
+      }
+      scheduleState.lastRunAt = snapshot.now;
+      scheduleState.pending = true;
+      emitDebug(optionsRef.current.debug, {
+        type: "schedule:start",
+        scope: "timer-group",
+        timerId: item.id,
+        scheduleId: schedule.id ?? key,
+        ...baseDebugEvent(snapshot, generation)
+      });
+      Promise.resolve().then(() => schedule.callback(snapshot, controlsFor(item.id))).then(
+        () => {
+          emitDebug(optionsRef.current.debug, {
+            type: "schedule:end",
+            scope: "timer-group",
+            timerId: item.id,
+            scheduleId: schedule.id ?? key,
+            ...baseDebugEvent(snapshot, generation)
+          });
+        },
+        (error) => {
+          emitDebug(optionsRef.current.debug, {
+            type: "schedule:error",
+            scope: "timer-group",
+            timerId: item.id,
+            scheduleId: schedule.id ?? key,
+            error,
+            ...baseDebugEvent(snapshot, generation)
+          });
+        }
+      ).finally(() => {
+        const liveItem = itemsRef.current.get(item.id);
+        if (liveItem?.state.generation === generation) {
+          scheduleState.pending = false;
+        }
+      });
+    },
+    [controlsFor]
+  );
+  const evaluateItemSchedules = (0, import_react2.useCallback)(
+    (item, snapshot, activation = false) => {
+      const schedules = item.definition.schedules ?? [];
+      const liveKeys = /* @__PURE__ */ new Set();
+      schedules.forEach((schedule, index) => {
+        const key = schedule.id ?? String(index);
+        liveKeys.add(key);
+        let scheduleState = item.schedules.get(key);
+        if (!scheduleState) {
+          scheduleState = { lastRunAt: null, pending: false, leadingGeneration: null };
+          item.schedules.set(key, scheduleState);
+        }
+        if (activation && schedule.leading && scheduleState.leadingGeneration !== item.state.generation) {
+          scheduleState.leadingGeneration = item.state.generation;
+          runSchedule(item, schedule, key, scheduleState, snapshot, item.state.generation);
+          return;
+        }
+        if (scheduleState.lastRunAt === null) {
+          scheduleState.lastRunAt = item.state.startedAt ?? snapshot.now;
+          if (snapshot.now - scheduleState.lastRunAt >= schedule.everyMs) {
+            runSchedule(item, schedule, key, scheduleState, snapshot, item.state.generation);
+          }
+          return;
+        }
+        if (snapshot.now - scheduleState.lastRunAt >= schedule.everyMs) {
+          runSchedule(item, schedule, key, scheduleState, snapshot, item.state.generation);
+        }
+      });
+      for (const key of item.schedules.keys()) {
+        if (!liveKeys.has(key)) item.schedules.delete(key);
+      }
+    },
+    [runSchedule]
+  );
+  const processItem = (0, import_react2.useCallback)(
+    (item, clock = readClock(), activation = false) => {
+      if (item.state.status !== "running") return;
+      const snapshot = toSnapshot(item.state, clock);
+      if (item.definition.endWhen?.(snapshot)) {
+        if (endTimerState(item.state, clock)) {
+          const endedSnapshot = toSnapshot(item.state, clock);
+          emit("timer:end", item, endedSnapshot);
+          callOnEnd(item, endedSnapshot);
+        }
+        return;
+      }
+      evaluateItemSchedules(item, snapshot, activation);
+    },
+    [callOnEnd, emit, evaluateItemSchedules]
+  );
+  const ensureItem = (0, import_react2.useCallback)((definition) => {
+    const existing = itemsRef.current.get(definition.id);
+    if (existing) {
+      existing.definition = definition;
+      return { item: existing, added: false };
+    }
+    const item = {
+      id: definition.id,
+      state: createTimerState(readClock()),
+      definition,
+      schedules: /* @__PURE__ */ new Map(),
+      endCalledGeneration: null
+    };
+    itemsRef.current.set(definition.id, item);
+    if (definition.autoStart) {
+      startTimerState(item.state, readClock());
+    }
+    return { item, added: true };
+  }, []);
+  const syncItems = (0, import_react2.useCallback)(() => {
+    const definitions = optionsRef.current.items ?? [];
+    const liveIds = /* @__PURE__ */ new Set();
+    let changed = false;
+    definitions.forEach((definition) => {
+      liveIds.add(definition.id);
+      const { item, added } = ensureItem(definition);
+      changed = changed || added;
+      if (definition.autoStart && item.state.status === "idle") {
+        changed = startTimerState(item.state, readClock()) || changed;
+      }
+    });
+    for (const id of itemsRef.current.keys()) {
+      if (!liveIds.has(id)) {
+        itemsRef.current.delete(id);
+        changed = true;
+      }
+    }
+    return changed;
+  }, [ensureItem]);
+  (0, import_react2.useEffect)(() => {
+    if (syncItems()) rerender();
+  }, [syncItems, options.items]);
+  const add = (0, import_react2.useCallback)((item) => {
+    validateItems([item]);
+    if (itemsRef.current.has(item.id)) throw new Error(`Timer item "${item.id}" already exists`);
+    ensureItem(item);
+    rerender();
+  }, [ensureItem]);
+  const update = (0, import_react2.useCallback)((id, item) => {
+    const existing = itemsRef.current.get(id);
+    if (!existing) return;
+    const next = { ...existing.definition, ...item, id };
+    validateItems([next]);
+    existing.definition = next;
+    rerender();
+  }, []);
+  const remove = (0, import_react2.useCallback)((id) => {
+    itemsRef.current.delete(id);
+    rerender();
+  }, []);
+  const clear = (0, import_react2.useCallback)(() => {
+    itemsRef.current.clear();
+    clearScheduledTick();
+    rerender();
+  }, [clearScheduledTick]);
+  const start = (0, import_react2.useCallback)((id) => {
+    const item = itemsRef.current.get(id);
+    if (!item) return;
+    const clock = readClock();
+    if (!startTimerState(item.state, clock)) return;
+    emit("timer:start", item, toSnapshot(item.state, clock));
+    processItem(item, clock, true);
+    rerender();
+  }, [emit, processItem]);
+  const pause = (0, import_react2.useCallback)((id) => {
+    const item = itemsRef.current.get(id);
+    if (!item) return;
+    const clock = readClock();
+    if (!pauseTimerState(item.state, clock)) return;
+    emit("timer:pause", item, toSnapshot(item.state, clock));
+    rerender();
+  }, [emit]);
+  const resume = (0, import_react2.useCallback)((id) => {
+    const item = itemsRef.current.get(id);
+    if (!item) return;
+    const clock = readClock();
+    if (!resumeTimerState(item.state, clock)) return;
+    emit("timer:resume", item, toSnapshot(item.state, clock));
+    processItem(item, clock, true);
+    rerender();
+  }, [emit, processItem]);
+  const reset = (0, import_react2.useCallback)((id, resetOptions = {}) => {
+    const item = itemsRef.current.get(id);
+    if (!item) return;
+    const clock = readClock();
+    resetTimerState(item.state, clock, resetOptions);
+    item.schedules.clear();
+    item.endCalledGeneration = null;
+    emit("timer:reset", item, toSnapshot(item.state, clock));
+    if (resetOptions.autoStart) processItem(item, clock, true);
+    rerender();
+  }, [emit, processItem]);
+  const restart = (0, import_react2.useCallback)((id) => {
+    const item = itemsRef.current.get(id);
+    if (!item) return;
+    const clock = readClock();
+    restartTimerState(item.state, clock);
+    item.schedules.clear();
+    item.endCalledGeneration = null;
+    emit("timer:restart", item, toSnapshot(item.state, clock));
+    processItem(item, clock, true);
+    rerender();
+  }, [emit, processItem]);
+  const cancel = (0, import_react2.useCallback)((id, reason) => {
+    const item = itemsRef.current.get(id);
+    if (!item) return;
+    const clock = readClock();
+    if (!cancelTimerState(item.state, clock, reason)) return;
+    emit("timer:cancel", item, toSnapshot(item.state, clock), { reason });
+    rerender();
+  }, [emit]);
+  const ids = Array.from(itemsRef.current.keys());
+  const activeSignature = ids.map((id) => `${id}:${itemsRef.current.get(id).state.status}:${itemsRef.current.get(id).state.generation}:${itemsRef.current.get(id).state.tick}`).join("|");
+  (0, import_react2.useEffect)(() => {
+    mountedRef.current = true;
+    const runningItems = Array.from(itemsRef.current.values()).filter((item) => item.state.status === "running");
+    if (runningItems.length === 0) {
+      clearScheduledTick();
+      return;
+    }
+    clearScheduledTick();
+    const first = runningItems[0];
+    emit("scheduler:start", first, toSnapshot(first.state, readClock()));
+    timeoutRef.current = setTimeout(() => {
+      if (!mountedRef.current) return;
+      const clock = readClock();
+      for (const item of itemsRef.current.values()) {
+        if (item.state.status !== "running") continue;
+        tickTimerState(item.state, clock);
+        const snapshot = toSnapshot(item.state, clock);
+        emit("timer:tick", item, snapshot);
+        processItem(item, clock);
+      }
+      rerender();
+    }, optionsRef.current.updateIntervalMs ?? 1e3);
+    return () => {
+      if (timeoutRef.current !== null) {
+        emit("scheduler:stop", first, toSnapshot(first.state, readClock()));
+      }
+      clearScheduledTick();
+      mountedRef.current = false;
+    };
+  }, [activeSignature, clearScheduledTick, emit, processItem]);
+  const get = (0, import_react2.useCallback)(
+    (id) => {
+      const item = itemsRef.current.get(id);
+      if (!item) return void 0;
+      return getItemSnapshot(item);
+    },
+    [getItemSnapshot]
+  );
+  const now = readClock().wallNow;
+  return (0, import_react2.useMemo)(
+    () => ({
+      now,
+      size: itemsRef.current.size,
+      ids: Array.from(itemsRef.current.keys()),
+      get,
+      add,
+      update,
+      remove,
+      clear,
+      start,
+      pause,
+      resume,
+      reset,
+      restart,
+      cancel,
+      startAll: () => Array.from(itemsRef.current.keys()).forEach(start),
+      pauseAll: () => Array.from(itemsRef.current.keys()).forEach(pause),
+      resumeAll: () => Array.from(itemsRef.current.keys()).forEach(resume),
+      resetAll: (resetOptions) => Array.from(itemsRef.current.keys()).forEach((id) => reset(id, resetOptions)),
+      restartAll: () => Array.from(itemsRef.current.keys()).forEach(restart),
+      cancelAll: (reason) => Array.from(itemsRef.current.keys()).forEach((id) => cancel(id, reason))
+    }),
+    [add, cancel, clear, get, now, pause, remove, reset, restart, resume, start, update]
+  );
+}
+function validateItems(items) {
+  const ids = /* @__PURE__ */ new Set();
+  items?.forEach((item) => {
+    if (ids.has(item.id)) throw new Error(`Duplicate timer item id "${item.id}"`);
+    ids.add(item.id);
+    item.schedules?.forEach((schedule) => validatePositiveFinite(schedule.everyMs, "schedule.everyMs"));
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  durationParts,
+  useTimer,
+  useTimerGroup
+});
+//# sourceMappingURL=index.cjs.map