@crup/react-timer-hook 0.0.1-alpha.11 → 0.0.1-alpha.12

package/README.md

@@ -1,6 +1,6 @@
 # @crup/react-timer-hook
 
-> ~1.2 kB timer core for React, with opt-in batteries for schedules, diagnostics, duration math, and many independent timers.
+> A lightweight React hooks library for building timers, stopwatches, and real-time clocks with minimal boilerplate.
 
 [![npm alpha](https://img.shields.io/npm/v/%40crup%2Freact-timer-hook/alpha?label=npm%20alpha&color=00b894)](https://www.npmjs.com/package/@crup/react-timer-hook?activeTab=versions)
 [![npm downloads](https://img.shields.io/npm/dm/%40crup%2Freact-timer-hook?color=0f766e)](https://www.npmjs.com/package/@crup/react-timer-hook)
@@ -17,7 +17,7 @@
 
 Timer hooks look simple until real apps need pause/resume semantics, Strict Mode cleanup, async callbacks, polling that does not overlap, and lists with dozens of independent timers.
 
-`@crup/react-timer-hook` starts with a tiny core and lets your app compose the heavier pieces only when it needs them:
+`@crup/react-timer-hook` starts with a ~1.2 kB timer core and lets your app compose the heavier pieces only when it needs them:
 
 - ⏱️ `useTimer()` from the root package for one lifecycle: stopwatch, countdown, clock, or custom flow.
 - 🔋 Batteries are optional: schedules, timer groups, duration helpers, and diagnostics live in subpath imports.
@@ -143,6 +143,85 @@ const timers = useTimerGroup({
 });
 ```
 
+## API tables
+
+### `useTimer()` settings
+
+| Key | Type | Required | Description |
+| --- | --- | --- | --- |
+| `autoStart` | `boolean` | No | Starts the lifecycle after mount. Defaults to `false`. |
+| `updateIntervalMs` | `number` | No | Render/update cadence in milliseconds. Defaults to `1000`. This does not define elapsed time; elapsed time is calculated from timestamps. Use a smaller value like `100` or `20` when the UI needs finer updates. |
+| `endWhen` | `(snapshot) => boolean` | No | Ends the lifecycle when it returns `true`. Use this for countdowns, timeouts, and custom stop conditions. |
+| `onEnd` | `(snapshot, controls) => void \| Promise<void>` | No | Called once per generation when `endWhen` ends the lifecycle. `restart()` creates a new generation. |
+
+### `useScheduledTimer()` settings
+
+Import from `@crup/react-timer-hook/schedules` when you need polling or scheduled side effects.
+
+| Key | Type | Required | Description |
+| --- | --- | --- | --- |
+| `autoStart` | `boolean` | No | Starts the lifecycle after mount. Defaults to `false`. |
+| `updateIntervalMs` | `number` | No | Render/update cadence in milliseconds. Defaults to `1000`. Scheduled callbacks can run on their own cadence. |
+| `endWhen` | `(snapshot) => boolean` | No | Ends the lifecycle when it returns `true`. |
+| `onEnd` | `(snapshot, controls) => void \| Promise<void>` | No | Called once per generation when `endWhen` ends the lifecycle. |
+| `schedules` | `TimerSchedule[]` | No | Scheduled side effects that run while the timer is active. Async overlap defaults to `skip`. |
+| `debug` | `TimerDebug` | No | Opt-in semantic diagnostics. No logs are emitted by default. |
+
+### `TimerSchedule`
+
+| Key | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | No | Stable identifier used in debug events and schedule context. Falls back to the array index. |
+| `everyMs` | `number` | Yes | Schedule cadence in milliseconds. Must be positive and finite. |
+| `leading` | `boolean` | No | Runs the schedule immediately when the timer starts or resumes into a new generation. Defaults to `false`. |
+| `overlap` | `'skip' \| 'allow'` | No | Controls async overlap. Defaults to `skip`, so a pending callback prevents another run. |
+| `callback` | `(snapshot, controls, context) => void \| Promise<void>` | Yes | Scheduled side effect. Receives timing context with `scheduledAt`, `firedAt`, `nextRunAt`, `overdueCount`, and `effectiveEveryMs`. |
+
+### `useTimerGroup()` settings
+
+Import from `@crup/react-timer-hook/group` when many keyed items need independent lifecycle control.
+
+| Key | Type | Required | Description |
+| --- | --- | --- | --- |
+| `updateIntervalMs` | `number` | No | Shared scheduler cadence for the group. Defaults to `1000`. |
+| `items` | `TimerGroupItem[]` | No | Initial/synced timer item definitions. Each item has its own lifecycle state. |
+| `debug` | `TimerDebug` | No | Opt-in semantic diagnostics for group lifecycle and schedule events. |
+
+### `TimerGroupItem`
+
+| Key | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | Yes | Stable key for the item. Duplicate IDs throw. |
+| `autoStart` | `boolean` | No | Starts the item automatically when it is added or synced. Defaults to `false`. |
+| `endWhen` | `(snapshot) => boolean` | No | Ends that item when it returns `true`. |
+| `onEnd` | `(snapshot, controls) => void \| Promise<void>` | No | Called once per item generation when that item ends naturally. |
+| `schedules` | `TimerSchedule[]` | No | Per-item schedules with the same contract as `useScheduledTimer()`. |
+
+### Values and controls
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `status` | `'idle' \| 'running' \| 'paused' \| 'ended' \| 'cancelled'` | Current lifecycle state. |
+| `now` | `number` | Wall-clock timestamp from `Date.now()`. Use for clocks and absolute deadlines. |
+| `tick` | `number` | Number of render/update ticks produced in the current generation. |
+| `startedAt` | `number \| null` | Wall-clock timestamp when the current generation started. |
+| `pausedAt` | `number \| null` | Wall-clock timestamp for the current pause, or `null`. |
+| `endedAt` | `number \| null` | Wall-clock timestamp when `endWhen` ended the lifecycle. |
+| `cancelledAt` | `number \| null` | Wall-clock timestamp when `cancel()` ended the lifecycle early. |
+| `cancelReason` | `string \| null` | Optional reason passed to `cancel(reason)`. |
+| `elapsedMilliseconds` | `number` | Active elapsed duration calculated from monotonic time, excluding paused time. |
+| `isIdle` | `boolean` | Convenience flag for `status === 'idle'`. |
+| `isRunning` | `boolean` | Convenience flag for `status === 'running'`. |
+| `isPaused` | `boolean` | Convenience flag for `status === 'paused'`. |
+| `isEnded` | `boolean` | Convenience flag for `status === 'ended'`. |
+| `isCancelled` | `boolean` | Convenience flag for `status === 'cancelled'`. |
+| `start()` | `function` | Starts an idle timer. No-op if it is already started. |
+| `pause()` | `function` | Pauses a running timer. |
+| `resume()` | `function` | Resumes a paused timer from the paused elapsed value. |
+| `reset(options?)` | `function` | Resets to idle and zero elapsed time. Pass `{ autoStart: true }` to reset directly into running. |
+| `restart()` | `function` | Starts a new running generation from zero elapsed time. |
+| `cancel(reason?)` | `function` | Terminal early stop. Does not call `onEnd`. |
+
 ## Bundle size
 
 The core import stays small. Extra capabilities are opt-in batteries.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@crup/react-timer-hook",
-  "version": "0.0.1-alpha.11",
-  "description": "React timer lifecycle hooks for countdowns, stopwatches, schedules, and many independent timers.",
+  "version": "0.0.1-alpha.12",
+  "description": "A lightweight React hooks library for building timers, stopwatches, and real-time clocks with minimal boilerplate.",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",