feat(schedules): expose timing context

Author: crup

README.md

@@ -108,7 +108,8 @@ const timer = useTimer({
       id: 'auction-poll',
       everyMs: 5000,
       overlap: 'skip',
-      callback: async (_snapshot, controls) => {
+      callback: async (_snapshot, controls, context) => {
+        console.log(`auction poll fired ${context.firedAt - context.scheduledAt}ms late`);
         const auction = await api.getAuction(auctionId);
         if (auction.status === 'sold') controls.cancel('sold');
       },
@@ -139,9 +140,9 @@ Current build:
 
 | File | Raw | Gzip | Brotli |
 | --- | ---: | ---: | ---: |
-| `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 |
+| `dist/index.js` | 12.80 kB | 3.88 kB | 3.47 kB |
+| `dist/index.cjs` | 14.04 kB | 4.12 kB | 3.70 kB |
+| `dist/index.d.ts` | 4.32 kB | 1.04 kB | 951 B |
 
 CI writes a size summary to the GitHub Actions UI and posts bundle-size reports on pull requests.
 

docs-site/docs/api/types.mdx

@@ -28,15 +28,30 @@ const parts = durationParts(90_500);
 ## Schedules
 
 ```ts
+type TimerScheduleContext = {
+  scheduleId: string;
+  scheduledAt: number;
+  firedAt: number;
+  nextRunAt: number;
+  overdueCount: number;
+  effectiveEveryMs: number;
+};
+
 type TimerSchedule = {
   id?: string;
   everyMs: number;
   leading?: boolean;
   overlap?: 'skip' | 'allow';
-  callback: (snapshot: TimerSnapshot, controls: TimerControls) => void | Promise<void>;
+  callback: (
+    snapshot: TimerSnapshot,
+    controls: TimerControls,
+    context: TimerScheduleContext,
+  ) => void | Promise<void>;
 };
 ```
 
+`scheduledAt` is the intended fire time. `firedAt` is when the browser actually ran the callback. `overdueCount` reports how many schedule windows were missed before this callback because the browser, tab, or previous work delayed execution.
+
 ## Debug
 
 Debug is opt-in. The package does not emit logs by default.

docs-site/docs/api/use-timer-group.mdx

@@ -11,6 +11,8 @@ function useTimerGroup(options?: UseTimerGroupOptions): TimerGroupResult;
 
 Use `useTimerGroup()` when every row needs independent pause, resume, cancel, restart, schedules, or `onEnd`.
 
+Item schedules use the same `TimerSchedule` contract as `useTimer()`, including the third schedule context argument for intended fire time, actual fire time, next run time, and overdue interval count.
+
 ```ts
 type UseTimerGroupOptions = {
   updateIntervalMs?: number;

docs-site/docs/api/use-timer.mdx

@@ -28,7 +28,7 @@ type UseTimerOptions = {
 
 `onEnd` fires once per generation. `restart()` creates a new generation.
 
-Schedules run while active and default to `overlap: 'skip'`.
+Schedules run while active and default to `overlap: 'skip'`. The schedule callback receives a third `context` argument with `scheduledAt`, `firedAt`, `nextRunAt`, `overdueCount`, and `effectiveEveryMs`, so delayed browser timers can be measured without exposing timeout handles.
 
 ## Controls
 

docs-site/static/llms-full.txt

@@ -36,6 +36,8 @@ Use `useTimerGroup()` for many keyed timers that each need independent lifecycle
 
 Schedules are app-owned side effects. Default overlap behavior is `skip`.
 
+Schedule callbacks receive `(snapshot, controls, context)`. `context` includes `scheduleId`, `scheduledAt`, `firedAt`, `nextRunAt`, `overdueCount`, and `effectiveEveryMs`.
+
 ## Recipes index
 
 Basic:

docs-site/static/llms.txt

@@ -18,5 +18,6 @@ Core rules:
 - Use endWhen(snapshot) to end a lifecycle.
 - Use cancel(reason) for terminal early stops.
 - Schedules run while active and default to overlap: 'skip'.
+- Schedule callbacks receive context with scheduledAt, firedAt, nextRunAt, overdueCount, and effectiveEveryMs.
 - Debug logs are opt-in only.
 - Formatting, locale, timezone, caching, retries, and business rules are userland.

src/__tests__/useTimer.schedules.test.tsx

@@ -132,4 +132,89 @@ describe('useTimer schedules', () => {
 
     expect(callback).toHaveBeenCalledTimes(1);
   });
+
+  it('passes schedule timing context to callbacks', async () => {
+    const callback = vi.fn();
+    renderHook(() =>
+      useTimer({
+        autoStart: true,
+        updateIntervalMs: 100,
+        schedules: [{ id: 'poll', everyMs: 100, callback }],
+      }),
+    );
+
+    act(() => vi.advanceTimersByTime(100));
+    await act(async () => {});
+
+    expect(callback).toHaveBeenCalledWith(
+      expect.objectContaining({ now: 100 }),
+      expect.objectContaining({ cancel: expect.any(Function) }),
+      {
+        scheduleId: 'poll',
+        scheduledAt: 100,
+        firedAt: 100,
+        nextRunAt: 200,
+        overdueCount: 0,
+        effectiveEveryMs: 100,
+      },
+    );
+  });
+
+  it('reports overdue intervals when a scheduled timeout fires late', async () => {
+    const callback = vi.fn();
+    renderHook(() =>
+      useTimer({
+        autoStart: true,
+        updateIntervalMs: 1000,
+        schedules: [{ id: 'poll', everyMs: 100, leading: true, callback }],
+      }),
+    );
+
+    await act(async () => {});
+    callback.mockClear();
+
+    act(() => vi.setSystemTime(350));
+    act(() => vi.advanceTimersByTime(100));
+    await act(async () => {});
+
+    expect(callback).toHaveBeenCalledWith(
+      expect.objectContaining({ now: 450 }),
+      expect.anything(),
+      {
+        scheduleId: 'poll',
+        scheduledAt: 400,
+        firedAt: 450,
+        nextRunAt: 500,
+        overdueCount: 3,
+        effectiveEveryMs: 100,
+      },
+    );
+  });
+
+  it('emits schedule timing context in debug logs', async () => {
+    const logger = vi.fn();
+    renderHook(() =>
+      useTimer({
+        autoStart: true,
+        updateIntervalMs: 100,
+        debug: { logger },
+        schedules: [{ id: 'poll', everyMs: 100, callback: vi.fn() }],
+      }),
+    );
+
+    act(() => vi.advanceTimersByTime(100));
+    await act(async () => {});
+
+    expect(logger).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'schedule:start',
+        scheduleId: 'poll',
+        scheduledAt: 100,
+        firedAt: 100,
+        nextRunAt: 200,
+        overdueCount: 0,
+        effectiveEveryMs: 100,
+      }),
+    );
+  });
 });

src/__tests__/useTimerGroup.schedules.test.tsx

@@ -36,6 +36,52 @@ describe('useTimerGroup schedules and debug', () => {
     expect(logger).toHaveBeenCalledWith(expect.objectContaining({ type: 'schedule:start', timerId: 'a', scheduleId: 'poll' }));
   });
 
+  it('passes schedule timing context to item callbacks and debug logs', async () => {
+    const callback = vi.fn();
+    const logger = vi.fn();
+    renderHook(() =>
+      useTimerGroup({
+        updateIntervalMs: 100,
+        debug: { logger },
+        items: [
+          {
+            id: 'a',
+            autoStart: true,
+            schedules: [{ id: 'poll', everyMs: 100, callback }],
+          },
+        ],
+      }),
+    );
+
+    act(() => vi.advanceTimersByTime(100));
+    await act(async () => {});
+
+    expect(callback).toHaveBeenCalledWith(
+      expect.objectContaining({ now: 100 }),
+      expect.objectContaining({ cancel: expect.any(Function) }),
+      {
+        scheduleId: 'poll',
+        scheduledAt: 100,
+        firedAt: 100,
+        nextRunAt: 200,
+        overdueCount: 0,
+        effectiveEveryMs: 100,
+      },
+    );
+    expect(logger).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'schedule:start',
+        timerId: 'a',
+        scheduleId: 'poll',
+        scheduledAt: 100,
+        firedAt: 100,
+        nextRunAt: 200,
+        overdueCount: 0,
+        effectiveEveryMs: 100,
+      }),
+    );
+  });
+
   it('drives many timers with one cadence', () => {
     const items = Array.from({ length: 100 }, (_, index) => ({ id: String(index), autoStart: true }));
     const { result } = renderHook(() => useTimerGroup({ updateIntervalMs: 100, items }));

src/index.ts

@@ -13,6 +13,7 @@ export type {
   TimerGroupItemControls,
   TimerGroupResult,
   TimerSchedule,
+  TimerScheduleContext,
   TimerSnapshot,
   TimerStatus,
   UseTimerGroupOptions,

src/types.ts

@@ -38,12 +38,21 @@ export type TimerControls = {
 
 export type TimerEndPredicate = (snapshot: TimerSnapshot) => boolean;
 
+export type TimerScheduleContext = {
+  scheduleId: string;
+  scheduledAt: number;
+  firedAt: number;
+  nextRunAt: number;
+  overdueCount: number;
+  effectiveEveryMs: number;
+};
+
 export type TimerSchedule = {
   id?: string;
   everyMs: number;
   leading?: boolean;
   overlap?: 'skip' | 'allow';
-  callback: (snapshot: TimerSnapshot, controls: TimerControls) => void | Promise<void>;
+  callback: (snapshot: TimerSnapshot, controls: TimerControls, context: TimerScheduleContext) => void | Promise<void>;
 };
 
 export type TimerDebug =
@@ -86,6 +95,11 @@ export type TimerDebugEvent = {
   status: TimerStatus;
   reason?: string;
   error?: unknown;
+  scheduledAt?: number;
+  firedAt?: number;
+  nextRunAt?: number;
+  overdueCount?: number;
+  effectiveEveryMs?: number;
 };
 
 export type UseTimerOptions = {