# @crup/react-timer-hook

A lightweight React hooks library for building timers, stopwatches, and real-time clocks with minimal boilerplate.

Docs: https://crup.github.io/react-timer-hook/
Package: @crup/react-timer-hook
Install: npm install @crup/react-timer-hook@latest
Runtime: Node 18+ and React 18+
Repository: https://github.com/crup/react-timer-hook

Public exports:
- useTimer(options): one timer lifecycle.
- @crup/react-timer-hook/group useTimerGroup(options): many keyed independent lifecycles with one shared scheduler.
- @crup/react-timer-hook/schedules useScheduledTimer(options): schedule-enabled timer with context.
- @crup/react-timer-hook/duration durationParts(milliseconds): duration display helper.
- @crup/react-timer-hook/diagnostics consoleTimerDiagnostics(options): console diagnostics helper.

Core rules:
- Use timer.now for wall-clock deadlines and clocks.
- Use timer.elapsedMilliseconds for active elapsed duration.
- Use endWhen(snapshot) to end a lifecycle.
- Use onError(error, snapshot, controls) when onEnd can throw or reject.
- Use cancel(reason) for terminal early stops.
- Schedules are opt-in through @crup/react-timer-hook/schedules and default to overlap: 'skip'.
- Schedule callbacks receive context with scheduledAt, firedAt, nextRunAt, overdueCount, and effectiveEveryMs.
- Schedule callbacks can define onError(error, snapshot, controls, context); otherwise timer or item onError is used.
- Diagnostics are opt-in only.
- UI display and data fetching stay in userland.