# @crup/react-timer-hook full AI context

## Install

```sh
npm install @crup/react-timer-hook@latest
pnpm add @crup/react-timer-hook@latest
```

Runtime requirements: Node 18+ and React 18+.

## Exports

```ts
import { useTimer } from '@crup/react-timer-hook';
import { consoleTimerDiagnostics } from '@crup/react-timer-hook/diagnostics';
import { durationParts } from '@crup/react-timer-hook/duration';
import { useTimerGroup } from '@crup/react-timer-hook/group';
import { useScheduledTimer } from '@crup/react-timer-hook/schedules';
```

## useTimer

```ts
useTimer({
  autoStart?: boolean;
  updateIntervalMs?: number;
  endWhen?: (snapshot: TimerSnapshot) => boolean;
  onEnd?: (snapshot: TimerSnapshot, controls: TimerControls) => void | Promise<void>;
  onError?: (error: unknown, snapshot: TimerSnapshot, controls: TimerControls) => void;
})
```

Use `now` for wall-clock countdowns and clocks. Use `elapsedMilliseconds` for stopwatches and pausable duration countdowns.

## useTimerGroup

Use `useTimerGroup()` for many keyed timers that each need independent lifecycle controls.

## Schedules

Use `useScheduledTimer()` from `@crup/react-timer-hook/schedules` for app-owned side effects. Default overlap behavior is `skip`.

Schedule callbacks receive `(snapshot, controls, context)`. `context` includes `scheduleId`, `scheduledAt`, `firedAt`, `nextRunAt`, `overdueCount`, and `effectiveEveryMs`.

Schedules can define `onError(error, snapshot, controls, context)`. When omitted, schedule callback failures fall back to the timer or timer-group item `onError`.

## Use cases

- `/use-cases/`: choose by composition.
- `/use-cases/core/`: clock, stopwatch, absolute deadline, pausable duration countdown, OTP resend cooldown.
- `/use-cases/schedules/`: polling, autosave heartbeat checks, timing context, early cancel.
- `/use-cases/groups/`: auctions, checkout holds, toast auto-dismiss, upload rows, job dashboards.
- `/use-cases/composition/`: combine core, duration, schedules, groups, and diagnostics.

## Recipes index

Basic:
- `/recipes/basic/wall-clock/`: `new Date(timer.now)`.
- `/recipes/basic/stopwatch/`: render `timer.elapsedMilliseconds`.
- `/recipes/basic/absolute-countdown/`: `Math.max(0, expiresAt - timer.now)`.
- `/recipes/basic/pausable-countdown/`: `durationMs - timer.elapsedMilliseconds`.
- `/recipes/basic/otp-resend/`: resend button cooldown.
- `/recipes/basic/manual-controls/`: use `start`, `restart`, and `reset`.

Intermediate:
- `/recipes/intermediate/once-only-on-end/`: `onEnd`.
- `/recipes/intermediate/polling-schedule/`: `schedules`.
- `/recipes/intermediate/autosave-heartbeat/`: scheduled draft saves or presence pings.
- `/recipes/intermediate/poll-and-cancel/`: call `controls.cancel(reason)`.
- `/recipes/intermediate/backend-event-stop/`: call `timer.cancel(reason)` from a subscription.
- `/recipes/intermediate/debug-logs/`: opt in with `consoleTimerDiagnostics`.

Advanced:
- `/recipes/advanced/many-display-countdowns/`: one shared `useTimer`.
- `/recipes/advanced/timer-group/`: `useTimerGroup`.
- `/recipes/advanced/group-controls/`: `pauseAll` and `resumeAll`.
- `/recipes/advanced/checkout-holds/`: independent reservation holds.
- `/recipes/advanced/per-item-polling/`: item `schedules`.
- `/recipes/advanced/dynamic-items/`: `add`, `update`, `remove`.
- `/recipes/advanced/toast-auto-dismiss/`: runtime toast timers.

## Assumptions

- Schedule callbacks are JavaScript timers, not native background jobs.
- Faster schedules can wake the scheduler more often than `updateIntervalMs`.
- `autoStart` is mount-time for `useTimer` and `useScheduledTimer`; use controls for runtime changes.
- For `useTimerGroup({ items })`, update item definitions immutably.

## MCP

Local docs MCP server:

```json
{
  "mcpServers": {
    "react-timer-hook-docs": {
      "command": "npx",
      "args": ["-y", "@crup/react-timer-hook@latest"]
    }
  }
}
```

The package bundles the MCP server at node_modules/@crup/react-timer-hook/dist/mcp/server.js and exposes it through the react-timer-hook-mcp bin.

MCP tools:
- get_api_docs: Get API docs. Returns compact API notes for @crup/react-timer-hook.
- get_recipe: Get recipe. Returns guidance for a named recipe or use case.
- search_docs: Search docs. Searches API and recipe notes for a query.

## Boundaries

Use the hook for timer lifecycle, elapsed time, schedules, and controls. Keep UI display and data fetching in your app.