perf(timer): schedule by nearest due time

Author: crup

README.md

@@ -139,8 +139,8 @@ Current build:
 
 | File | Raw | Gzip | Brotli |
 | --- | ---: | ---: | ---: |
-| `dist/index.js` | 11.82 kB | 3.55 kB | 3.20 kB |
-| `dist/index.cjs` | 12.94 kB | 3.79 kB | 3.42 kB |
+| `dist/index.js` | 12.45 kB | 3.75 kB | 3.36 kB |
+| `dist/index.cjs` | 13.69 kB | 4.01 kB | 3.60 kB |
 | `dist/index.d.ts` | 3.95 kB | 992 B | 888 B |
 
 CI writes a size summary to the GitHub Actions UI and posts bundle-size reports on pull requests.

src/__tests__/useTimer.schedules.test.tsx

@@ -96,4 +96,40 @@ describe('useTimer schedules', () => {
     await act(async () => {});
     expect(callback).toHaveBeenCalledTimes(3);
   });
+
+  it('uses the latest schedule callback without restarting the timer', async () => {
+    const firstCallback = vi.fn();
+    const secondCallback = vi.fn();
+    const { rerender } = renderHook(({ callback }) =>
+      useTimer({
+        autoStart: true,
+        updateIntervalMs: 100,
+        schedules: [{ id: 'poll', everyMs: 100, callback }],
+      }),
+      { initialProps: { callback: firstCallback } },
+    );
+
+    rerender({ callback: secondCallback });
+    act(() => vi.advanceTimersByTime(100));
+    await act(async () => {});
+
+    expect(firstCallback).not.toHaveBeenCalled();
+    expect(secondCallback).toHaveBeenCalledTimes(1);
+  });
+
+  it('checks schedule cadence independently from render update interval', async () => {
+    const callback = vi.fn();
+    renderHook(() =>
+      useTimer({
+        autoStart: true,
+        updateIntervalMs: 1000,
+        schedules: [{ id: 'fast-poll', everyMs: 100, callback }],
+      }),
+    );
+
+    act(() => vi.advanceTimersByTime(100));
+    await act(async () => {});
+
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
 });

src/__tests__/useTimer.strict-mode.test.tsx

@@ -24,6 +24,38 @@ describe('useTimer rerender and Strict Mode behavior', () => {
     expect(result.current.tick).toBe(1);
   });
 
+  it('keeps control method identities stable across rerenders and ticks', () => {
+    const { result, rerender } = renderHook(() => useTimer({ autoStart: true, updateIntervalMs: 100 }));
+    const controls = {
+      start: result.current.start,
+      pause: result.current.pause,
+      resume: result.current.resume,
+      reset: result.current.reset,
+      restart: result.current.restart,
+      cancel: result.current.cancel,
+    };
+
+    rerender();
+    act(() => vi.advanceTimersByTime(100));
+
+    expect(result.current.start).toBe(controls.start);
+    expect(result.current.pause).toBe(controls.pause);
+    expect(result.current.resume).toBe(controls.resume);
+    expect(result.current.reset).toBe(controls.reset);
+    expect(result.current.restart).toBe(controls.restart);
+    expect(result.current.cancel).toBe(controls.cancel);
+  });
+
+  it('does not delay the active timeout on parent rerender', () => {
+    const { result, rerender } = renderHook(() => useTimer({ autoStart: true, updateIntervalMs: 100 }));
+
+    act(() => vi.advanceTimersByTime(50));
+    rerender();
+    act(() => vi.advanceTimersByTime(50));
+
+    expect(result.current.tick).toBe(1);
+  });
+
   it('Strict Mode does not duplicate onEnd', () => {
     const onEnd = vi.fn();
     renderHook(

src/__tests__/useTimerGroup.schedules.test.tsx

@@ -44,4 +44,33 @@ describe('useTimerGroup schedules and debug', () => {
     expect(result.current.get('0')?.tick).toBe(1);
     expect(result.current.get('99')?.tick).toBe(1);
   });
+
+  it('keeps group control method identities stable across rerenders and ticks', () => {
+    const items = [{ id: 'a', autoStart: true }];
+    const { result, rerender } = renderHook(() => useTimerGroup({ updateIntervalMs: 100, items }));
+    const controls = {
+      start: result.current.start,
+      pause: result.current.pause,
+      resume: result.current.resume,
+      reset: result.current.reset,
+      restart: result.current.restart,
+      cancel: result.current.cancel,
+      pauseAll: result.current.pauseAll,
+      resumeAll: result.current.resumeAll,
+      restartAll: result.current.restartAll,
+    };
+
+    rerender();
+    act(() => vi.advanceTimersByTime(100));
+
+    expect(result.current.start).toBe(controls.start);
+    expect(result.current.pause).toBe(controls.pause);
+    expect(result.current.resume).toBe(controls.resume);
+    expect(result.current.reset).toBe(controls.reset);
+    expect(result.current.restart).toBe(controls.restart);
+    expect(result.current.cancel).toBe(controls.cancel);
+    expect(result.current.pauseAll).toBe(controls.pauseAll);
+    expect(result.current.resumeAll).toBe(controls.resumeAll);
+    expect(result.current.restartAll).toBe(controls.restartAll);
+  });
 });

src/useTimer.ts

@@ -199,6 +199,24 @@ export function useTimer(options: UseTimerOptions = {}): TimerSnapshot & TimerCo
     [callOnEnd, clearScheduledTick, emit, evaluateSchedules],
   );
 
+  const getNextDelay = useCallback((clock = readClock()) => {
+    const updateIntervalMs = optionsRef.current.updateIntervalMs ?? 1000;
+    let nextDelay = updateIntervalMs;
+
+    const state = stateRef.current!;
+    if (state.status !== 'running') return updateIntervalMs;
+
+    const schedules = optionsRef.current.schedules ?? [];
+    schedules.forEach((schedule, index) => {
+      const key = schedule.id ?? String(index);
+      const scheduleState = schedulesRef.current.get(key);
+      const lastRunAt = scheduleState?.lastRunAt ?? state.startedAt ?? clock.wallNow;
+      nextDelay = Math.min(nextDelay, Math.max(1, lastRunAt + schedule.everyMs - clock.wallNow));
+    });
+
+    return nextDelay;
+  }, []);
+
   const start = useCallback(() => {
     const clock = readClock();
     if (!startTimerState(stateRef.current!, clock)) return;
@@ -305,15 +323,15 @@ export function useTimer(options: UseTimerOptions = {}): TimerSnapshot & TimerCo
       emit('timer:tick', tickSnapshot);
       processRunningState(clock);
       rerender();
-    }, optionsRef.current.updateIntervalMs ?? 1000);
+    }, getNextDelay());
 
     return () => {
       if (timeoutRef.current !== null) {
         emit('scheduler:stop', getSnapshot());
       }
       clearScheduledTick();
     };
-  }, [clearScheduledTick, emit, generation, getSnapshot, processRunningState, snapshot.tick, status]);
+  }, [clearScheduledTick, emit, generation, getNextDelay, getSnapshot, processRunningState, snapshot.tick, status]);
 
   return {
     ...snapshot,

src/useTimerGroup.ts

@@ -235,6 +235,25 @@ export function useTimerGroup(options: UseTimerGroupOptions = {}): TimerGroupRes
     [callOnEnd, emit, evaluateItemSchedules],
   );
 
+  const getNextDelay = useCallback((clock = readClock()) => {
+    const updateIntervalMs = optionsRef.current.updateIntervalMs ?? 1000;
+    let nextDelay = updateIntervalMs;
+
+    for (const item of itemsRef.current.values()) {
+      if (item.state.status !== 'running') continue;
+
+      const schedules = item.definition.schedules ?? [];
+      schedules.forEach((schedule, index) => {
+        const key = schedule.id ?? String(index);
+        const scheduleState = item.schedules.get(key);
+        const lastRunAt = scheduleState?.lastRunAt ?? item.state.startedAt ?? clock.wallNow;
+        nextDelay = Math.min(nextDelay, Math.max(1, lastRunAt + schedule.everyMs - clock.wallNow));
+      });
+    }
+
+    return nextDelay;
+  }, []);
+
   const ensureItem = useCallback((definition: TimerGroupItem): { item: InternalGroupItem; added: boolean } => {
     const existing = itemsRef.current.get(definition.id);
     if (existing) {
@@ -401,7 +420,7 @@ export function useTimerGroup(options: UseTimerGroupOptions = {}): TimerGroupRes
       }
 
       rerender();
-    }, optionsRef.current.updateIntervalMs ?? 1000);
+    }, getNextDelay());
 
     return () => {
       if (timeoutRef.current !== null) {
@@ -410,7 +429,7 @@ export function useTimerGroup(options: UseTimerGroupOptions = {}): TimerGroupRes
       clearScheduledTick();
       mountedRef.current = false;
     };
-  }, [activeSignature, clearScheduledTick, emit, processItem]);
+  }, [activeSignature, clearScheduledTick, emit, getNextDelay, processItem]);
 
   const get = useCallback(
     (id: string) => {
@@ -422,6 +441,12 @@ export function useTimerGroup(options: UseTimerGroupOptions = {}): TimerGroupRes
   );
 
   const now = readClock().wallNow;
+  const startAll = useCallback(() => Array.from(itemsRef.current.keys()).forEach(start), [start]);
+  const pauseAll = useCallback(() => Array.from(itemsRef.current.keys()).forEach(pause), [pause]);
+  const resumeAll = useCallback(() => Array.from(itemsRef.current.keys()).forEach(resume), [resume]);
+  const resetAll = useCallback((resetOptions?: { autoStart?: boolean }) => Array.from(itemsRef.current.keys()).forEach(id => reset(id, resetOptions)), [reset]);
+  const restartAll = useCallback(() => Array.from(itemsRef.current.keys()).forEach(restart), [restart]);
+  const cancelAll = useCallback((reason?: string) => Array.from(itemsRef.current.keys()).forEach(id => cancel(id, reason)), [cancel]);
 
   return useMemo(
     () => ({
@@ -439,14 +464,14 @@ export function useTimerGroup(options: UseTimerGroupOptions = {}): TimerGroupRes
       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?: { autoStart?: boolean }) => Array.from(itemsRef.current.keys()).forEach(id => reset(id, resetOptions)),
-      restartAll: () => Array.from(itemsRef.current.keys()).forEach(restart),
-      cancelAll: (reason?: string) => Array.from(itemsRef.current.keys()).forEach(id => cancel(id, reason)),
+      startAll,
+      pauseAll,
+      resumeAll,
+      resetAll,
+      restartAll,
+      cancelAll,
     }),
-    [add, cancel, clear, get, now, pause, remove, reset, restart, resume, start, update],
+    [add, cancel, cancelAll, clear, get, now, pause, pauseAll, remove, reset, resetAll, restart, restartAll, resume, resumeAll, start, startAll, update],
   );
 }