@crup/react-timer-hook 0.0.1 → 0.0.3

package/README.md

@@ -2,7 +2,7 @@
 
 > 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](https://img.shields.io/npm/v/%40crup%2Freact-timer-hook?label=npm&color=00b894)](https://www.npmjs.com/package/@crup/react-timer-hook)
 [![npm downloads](https://img.shields.io/npm/dm/%40crup%2Freact-timer-hook?color=0f766e)](https://www.npmjs.com/package/@crup/react-timer-hook)
 [![CI](https://github.com/crup/react-timer-hook/actions/workflows/ci.yml/badge.svg)](https://github.com/crup/react-timer-hook/actions/workflows/ci.yml)
 [![Docs](https://github.com/crup/react-timer-hook/actions/workflows/docs.yml/badge.svg)](https://github.com/crup/react-timer-hook/actions/workflows/docs.yml)
@@ -29,11 +29,9 @@ Timers get messy when a product needs pause and resume, countdowns tied to serve
 
 ## Install
 
-The project is currently in alpha while the API receives feedback.
-
 ```sh
-npm install @crup/react-timer-hook@alpha
-pnpm add @crup/react-timer-hook@alpha
+npm install @crup/react-timer-hook@latest
+pnpm add @crup/react-timer-hook@latest
 ```
 
 Runtime requirements: Node 18+ and React 18+.
@@ -259,6 +257,7 @@ The default import stays small. Add the other pieces only when that screen needs
 | 📡 Schedules | `@crup/react-timer-hook/schedules` | Polling, cadence callbacks, overdue timing context | 8.62 kB | 3.02 kB | 2.78 kB |
 | 🧩 Duration | `@crup/react-timer-hook/duration` | `days`, `hours`, `minutes`, `seconds`, `milliseconds` | 318 B | 224 B | 192 B |
 | 🔎 Diagnostics | `@crup/react-timer-hook/diagnostics` | Optional lifecycle and schedule event logging | 105 B | 115 B | 90 B |
+| 🤖 MCP docs server | `react-timer-hook-mcp` | Optional local docs context for MCP clients and coding agents | 3.80 kB | 1.63 kB | 1.40 kB |
 
 CI writes a size summary to the GitHub Actions UI and posts bundle-size reports on pull requests.
 
@@ -271,17 +270,34 @@ Agents and docs-aware IDEs can use:
 
 Optional local MCP docs server:
 
+Use `npx` if the package is not installed in the current project:
+
 ```json
 {
   "mcpServers": {
     "react-timer-hook-docs": {
-      "command": "node",
-      "args": ["/absolute/path/to/react-timer-hook/mcp/server.mjs"]
+      "command": "npx",
+      "args": ["-y", "@crup/react-timer-hook@latest"]
     }
   }
 }
 ```
 
+If the package is installed locally, npm also creates a bin shim in `node_modules/.bin`:
+
+```json
+{
+  "mcpServers": {
+    "react-timer-hook-docs": {
+      "command": "./node_modules/.bin/react-timer-hook-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+The same bundled and minified server is available at `node_modules/@crup/react-timer-hook/dist/mcp/server.js`.
+
 It exposes:
 
 ```txt

package/dist/mcp/server.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import{createInterface as m}from"readline";import{readFileSync as p}from"fs";var n=f(),d=`# @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:
+- @crup/react-timer-hook: useTimer(options) for one timer lifecycle.
+- @crup/react-timer-hook/group: useTimerGroup(options) for many keyed independent lifecycles with one shared scheduler.
+- @crup/react-timer-hook/schedules: useScheduledTimer(options) for schedule-enabled timers with timing context.
+- @crup/react-timer-hook/duration: durationParts(milliseconds) for duration display helper values.
+- @crup/react-timer-hook/diagnostics: consoleTimerDiagnostics(options) for optional event logging.
+
+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.
+- Keep formatting, timezone, retries, and business rules in userland.
+
+Schedules:
+- Use useScheduledTimer() from @crup/react-timer-hook/schedules.
+- Schedules are opt-in 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.
+
+Recipes:
+- Wall clock: new Date(timer.now).
+- Stopwatch: render timer.elapsedMilliseconds.
+- Absolute countdown: Math.max(0, expiresAt - timer.now).
+- Pausable countdown: durationMs - timer.elapsedMilliseconds.
+- OTP resend: disable the resend button until elapsedMilliseconds reaches the cooldown.
+- Polling: use schedules with overlap: "skip".
+- Many independent timers: use useTimerGroup().
+`,l={"react-timer-hook://package":{name:"Package",mimeType:"application/json",text:JSON.stringify({name:n.name,version:n.version,docs:"https://crup.github.io/react-timer-hook/",install:`npm install ${n.name}@latest`},null,2)},"react-timer-hook://api":{name:"API",mimeType:"text/markdown",text:d},"react-timer-hook://recipes":{name:"Recipes",mimeType:"text/markdown",text:["# Recipes","","- Countdown: derive remaining time with Math.max(0, expiresAt - timer.now).","- Stopwatch: render timer.elapsedMilliseconds.","- Clock: render new Date(timer.now) with user-owned formatting.","- Polling: import useScheduledTimer from @crup/react-timer-hook/schedules.","- Many timers: import useTimerGroup from @crup/react-timer-hook/group."].join(`
+`)}},h=m({input:process.stdin,output:process.stdout,terminal:!1});h.on("line",e=>{if(!e.trim())return;let t;try{t=JSON.parse(e)}catch{return}let{id:r,method:i,params:s}=t;if(i==="initialize"){c(r,{protocolVersion:"2024-11-05",serverInfo:{name:"react-timer-hook-docs",version:n.version},capabilities:{resources:{}}});return}if(i==="resources/list"){c(r,{resources:Object.entries(l).map(([o,a])=>({uri:o,name:a.name,mimeType:a.mimeType}))});return}if(i==="resources/read"){let o=l[s?.uri];if(!o){u(r,-32004,`Unknown resource: ${s?.uri??"missing uri"}`);return}c(r,{contents:[{uri:s.uri,mimeType:o.mimeType,text:o.text}]});return}u(r,-32601,`Method not found: ${i}`)});function c(e,t){process.stdout.write(`${JSON.stringify({jsonrpc:"2.0",id:e,result:t})}
+`)}function u(e,t,r){process.stdout.write(`${JSON.stringify({jsonrpc:"2.0",id:e,error:{code:t,message:r}})}
+`)}function f(){for(let e of["../../package.json","../package.json"])try{return JSON.parse(p(new URL(e,import.meta.url),"utf8"))}catch{}return{name:"@crup/react-timer-hook",version:"0.0.0"}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crup/react-timer-hook",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "A lightweight React hooks library for building timers, stopwatches, and real-time clocks with minimal boilerplate.",
   "homepage": "https://crup.github.io/react-timer-hook/",
   "repository": {
@@ -13,6 +13,9 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "react-timer-hook-mcp": "./dist/mcp/server.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -38,6 +41,9 @@
       "types": "./dist/diagnostics.d.ts",
       "import": "./dist/diagnostics.js",
       "require": "./dist/diagnostics.cjs"
+    },
+    "./mcp/server": {
+      "import": "./dist/mcp/server.js"
     }
   },
   "files": [
@@ -112,6 +118,7 @@
     "docs:dev": "NO_UPDATE_NOTIFIER=1 docusaurus start docs-site",
     "docs:preview": "NO_UPDATE_NOTIFIER=1 docusaurus serve docs-site/build",
     "mcp:docs": "node mcp/server.mjs",
+    "mcp:check": "node scripts/check-mcp-server.mjs",
     "readme:check": "node scripts/check-readme.mjs",
     "release": "changeset publish",
     "size": "node scripts/size-report.mjs",