Types

Lifecycle error callback

onError?: (
  error: unknown,
  snapshot: TimerSnapshot,
  controls: TimerControls,
) => void;

Use onError when onEnd can throw or return a rejected promise.

Duration parts

type DurationParts = {
  totalMilliseconds: number;
  totalSeconds: number;
  milliseconds: number;
  seconds: number;
  minutes: number;
  hours: number;
  days: number;
};

import { durationParts } from '@crup/react-timer-hook/duration';

const parts = durationParts(90_500);

Schedules

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,
    context: TimerScheduleContext,
  ) => void | Promise<void>;
  onError?: (
    error: unknown,
    snapshot: TimerSnapshot,
    controls: TimerControls,
    context: TimerScheduleContext,
  ) => 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.

Schedule IDs must be unique within the same schedule list. If a schedule callback fails, schedule onError handles it. If schedule onError is omitted, the timer or timer-group item onError is used.

Diagnostics

Diagnostics are opt-in. The package does not emit logs by default.

type TimerDiagnostics =
  | TimerDiagnosticsLogger
  | {
      enabled?: boolean;
      logger: TimerDiagnosticsLogger;
      includeTicks?: boolean;
      label?: string;
    };