@use-raf/timer 0.0.2

package/README.md

@@ -0,0 +1,108 @@
+# @use-raf/timer
+
+A React hook for creating frame-synchronized timers using `requestAnimationFrame`.
+
+## Installation
+
+```bash
+npm install @use-raf/timer
+```
+
+## Usage
+
+```tsx
+import { useRafTimer } from '@use-raf/timer'
+
+const Demo = () => {
+  const { isActive, elapsed, start, stop, reset } = useRafTimer({
+    duration: 5000, // 5 seconds
+    onComplete: () => console.log('Timer completed!'),
+  })
+
+  return (
+    <div>
+      <p>Elapsed: {Math.floor(elapsed)}ms</p>
+      <p>Status: {isActive ? 'Running' : 'Stopped'}</p>
+      <button onClick={start} disabled={isActive}>Start</button>
+      <button onClick={stop} disabled={!isActive}>Stop</button>
+      <button onClick={reset}>Reset</button>
+    </div>
+  )
+}
+```
+
+With throttled updates:
+
+```tsx
+const Demo = () => {
+  const { elapsed } = useRafTimer({
+    duration: 10000,
+    throttle: 100, // Update every 100ms
+    onUpdate: (elapsed) => {
+      console.log(`Elapsed: ${elapsed}ms`)
+    },
+  })
+}
+```
+
+## API
+
+### `useRafTimer(options)`
+
+**Parameters:**
+
+- `duration: number` - Timer duration in milliseconds
+- `immediate?: boolean` - Start timer on mount (default: `false`)
+- `throttle?: number` - Minimum milliseconds between updates (default: `0`)
+- `onUpdate?: (elapsed: number) => void` - Called on each frame with elapsed time
+- `onComplete?: () => void` - Called when timer completes
+
+**Returns:**
+
+- `isActive: boolean` - Whether the timer is running
+- `elapsed: number` - Current elapsed time in milliseconds
+- `start: () => void` - Start the timer
+- `stop: () => void` - Pause the timer
+- `reset: () => void` - Stop and reset elapsed time to 0
+- `sink: () => void` - Stop the timer and trigger `onComplete`
+
+## Combining with `useProgress`
+
+The `useProgress` hook calculates normalized progress (0-1) from elapsed time:
+
+```tsx
+import { useRafTimer, useProgress } from '@use-raf/timer'
+
+const ProgressDemo = () => {
+  const duration = 5000
+
+  const { elapsed, start, stop, reset } = useRafTimer({ duration })
+  const { progress } = useProgress({
+    elapsed,
+    duration,
+    precision: 2, // Round to 2 decimal places
+  })
+
+  return (
+    <div>
+      <div style={{ width: `${progress * 100}%`, height: 20, background: 'blue' }} />
+      <p>Progress: {(progress * 100).toFixed(0)}%</p>
+      <button onClick={start}>Start</button>
+      <button onClick={stop}>Stop</button>
+      <button onClick={reset}>Reset</button>
+    </div>
+  )
+}
+```
+
+### `useProgress(options)`
+
+**Parameters:**
+
+- `elapsed: number` - Current elapsed time in milliseconds
+- `duration: number` - Total duration in milliseconds
+- `precision?: number` - Number of decimal places to round to (default: `4`)
+
+**Returns:**
+
+- `progress: number` - Progress value between 0 and 1

package/dist/index.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Options for configuring the progress calculation.
+ */
+interface ProgressProps {
+    /** Current elapsed time in milliseconds */
+    elapsed: number;
+    /** Total duration in milliseconds */
+    duration: number;
+    /** Number of decimal places to round to (default: 4) */
+    precision?: number;
+}
+/**
+ * Return value of the useProgress hook.
+ */
+interface ProgressReturn {
+    /** Progress value between 0 and 1 */
+    progress: number;
+}
+/**
+ * A React hook that calculates normalized progress (0-1) from elapsed time and duration.
+ *
+ * @param options - Configuration options for progress calculation
+ * @returns Object containing the normalized progress value
+ *
+ * @example
+ * ```tsx
+ * const { progress } = useProgress({
+ *   elapsed: 2500,
+ *   duration: 5000,
+ * })
+ * // progress === 0.5
+ * ```
+ *
+ * @example
+ * With custom precision:
+ * ```tsx
+ * const { progress } = useProgress({
+ *   elapsed: 1234,
+ *   duration: 5000,
+ *   precision: 2,
+ * })
+ * // progress === 0.24
+ * ```
+ */
+declare const useProgress: ({ elapsed, duration, precision, }: ProgressProps) => ProgressReturn;
+
+interface RafTimerProps {
+    /**
+     * Timer duration in milliseconds.
+     */
+    duration: number;
+    /**
+     * Whether to start the timer immediately on mount.
+     * @default false
+     */
+    immediate?: boolean;
+    /**
+     * Minimum time in milliseconds between updates.
+     * Use 0 for no throttling (updates every frame).
+     * @default 0
+     */
+    throttle?: number;
+    /**
+     * Optional callback invoked on each frame with elapsed time.
+     */
+    onUpdate?: (elapsed: number) => void;
+    /**
+     * Optional callback invoked when the timer completes.
+     */
+    onComplete?: () => void;
+}
+interface RafTimerReturn {
+    /**
+     * Whether the timer is currently running.
+     */
+    isActive: boolean;
+    /**
+     * Current elapsed time in milliseconds.
+     */
+    elapsed: number;
+    /**
+     * Starts or resumes the timer.
+     * Safe to call multiple times.
+     */
+    start: () => void;
+    /**
+     * Pauses the timer.
+     * Safe to call multiple times.
+     */
+    stop: () => void;
+    /**
+     * Stops the timer and resets elapsed time to 0.
+     */
+    reset: () => void;
+    /**
+     * Stops the timer and triggers the onComplete callback.
+     */
+    sink: () => void;
+}
+/**
+ * A React hook for creating a frame-synchronized timer.
+ *
+ * Provides manual control over a timer with optional throttling and completion callbacks.
+ * The timer tracks elapsed time and can be started, stopped, or reset at any time.
+ *
+ * @param options - Configuration options for the timer behavior
+ * @returns Object with timer state and control functions
+ *
+ * @example
+ * ```tsx
+ * const { isActive, elapsed, start, stop, reset } = useRafTimer({
+ *   duration: 5000,
+ *   onComplete: () => console.log('Timer completed!')
+ * })
+ *
+ * // Start the timer
+ * start()
+ *
+ * // Stop when needed
+ * stop()
+ *
+ * // Reset to 0
+ * reset()
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With throttled updates
+ * useRafTimer({
+ *   duration: 10000,
+ *   throttle: 100, // Update every 100ms
+ *   onUpdate: (elapsed) => {
+ *     console.log(`Elapsed: ${elapsed}ms`)
+ *   }
+ * })
+ * ```
+ */
+declare const useRafTimer: ({ duration, immediate, throttle, onUpdate, onComplete, }: RafTimerProps) => RafTimerReturn;
+
+export { type ProgressProps, type ProgressReturn, type RafTimerProps, type RafTimerReturn, useProgress, useRafTimer };

package/dist/index.js

@@ -0,0 +1,2 @@
+import{useRafLoop as N}from"@use-raf/loop";import{setTimeoutFrame as C}from"@use-raf/skd";import{useCallback as f,useEffect as g,useRef as b,useState as x}from"react";var F=({duration:r,immediate:e=!1,throttle:t=0,onUpdate:s,onComplete:m})=>{let n=b({onUpdate:s,onComplete:m});g(()=>{n.current={onUpdate:s,onComplete:m}});let u=b(0),[T,E]=x(u.current),p=f(o=>{u.current=o,E(o),n.current.onUpdate?.(o)},[]),d=b(),i=f((o,P)=>{let c=u.current+P;p(c),d.current=o},[p]),[l,M]=x(!1),{stop:a,start:k}=N(i,{immediate:e,throttle:t,setActive:M}),R=f(()=>{a(),n.current.onComplete?.()},[a]);g(()=>{if(!l)return;let o=r-u.current;return C(c=>{let v=d.current||c,A=c-v;i(c,A),R()},o)},[l,r,R,i]);let h=f(()=>{a(),p(0)},[a,p]);return{isActive:l,elapsed:T,start:k,stop:a,reset:h,sink:R}};import{useMemo as I}from"react";var[S,_]=[Number.MIN_SAFE_INTEGER,Number.MAX_SAFE_INTEGER],y=(r=S,e=_)=>t=>Math.max(r,Math.min(t,e)),L=y(0,1),z=(r,e=0)=>{let s=10**Math.max(0,e-e%1);return Math.floor(r*s)/s},G=({elapsed:r,duration:e,precision:t=4})=>({progress:I(()=>{if(e===0)return 1;let m=r/e,n=L(m);return z(n,t)},[r,e,t])});export{G as useProgress,F as useRafTimer};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/raf-timer.hook.ts","../src/progress.hook.ts"],"sourcesContent":["import type { RafLoopCallback } from '@use-raf/loop'\nimport { useRafLoop } from '@use-raf/loop'\nimport { setTimeoutFrame } from '@use-raf/skd'\nimport { useCallback, useEffect, useRef, useState } from 'react'\n\nexport interface RafTimerProps {\n  /**\n   * Timer duration in milliseconds.\n   */\n  duration: number\n  /**\n   * Whether to start the timer immediately on mount.\n   * @default false\n   */\n  immediate?: boolean\n  /**\n   * Minimum time in milliseconds between updates.\n   * Use 0 for no throttling (updates every frame).\n   * @default 0\n   */\n  throttle?: number\n  /**\n   * Optional callback invoked on each frame with elapsed time.\n   */\n  onUpdate?: (elapsed: number) => void\n  /**\n   * Optional callback invoked when the timer completes.\n   */\n  onComplete?: () => void\n}\n\nexport interface RafTimerReturn {\n  /**\n   * Whether the timer is currently running.\n   */\n  isActive: boolean\n  /**\n   * Current elapsed time in milliseconds.\n   */\n  elapsed: number\n  /**\n   * Starts or resumes the timer.\n   * Safe to call multiple times.\n   */\n  start: () => void\n  /**\n   * Pauses the timer.\n   * Safe to call multiple times.\n   */\n  stop: () => void\n  /**\n   * Stops the timer and resets elapsed time to 0.\n   */\n  reset: () => void\n  /**\n   * Stops the timer and triggers the onComplete callback.\n   */\n  sink: () => void\n}\n\n/**\n * A React hook for creating a frame-synchronized timer.\n *\n * Provides manual control over a timer with optional throttling and completion callbacks.\n * The timer tracks elapsed time and can be started, stopped, or reset at any time.\n *\n * @param options - Configuration options for the timer behavior\n * @returns Object with timer state and control functions\n *\n * @example\n * ```tsx\n * const { isActive, elapsed, start, stop, reset } = useRafTimer({\n *   duration: 5000,\n *   onComplete: () => console.log('Timer completed!')\n * })\n *\n * // Start the timer\n * start()\n *\n * // Stop when needed\n * stop()\n *\n * // Reset to 0\n * reset()\n * ```\n *\n * @example\n * ```tsx\n * // With throttled updates\n * useRafTimer({\n *   duration: 10000,\n *   throttle: 100, // Update every 100ms\n *   onUpdate: (elapsed) => {\n *     console.log(`Elapsed: ${elapsed}ms`)\n *   }\n * })\n * ```\n */\nexport const useRafTimer = ({\n  duration,\n  immediate = false,\n  throttle = 0,\n  onUpdate,\n  onComplete,\n}: RafTimerProps): RafTimerReturn => {\n  const callbacksRef = useRef({ onUpdate, onComplete })\n  useEffect(() => {\n    callbacksRef.current = { onUpdate, onComplete }\n  })\n\n  const elapsedRef = useRef(0)\n  const [elapsed, setElapsedState] = useState(elapsedRef.current)\n  const setElapsed = useCallback((v: number) => {\n    elapsedRef.current = v\n    setElapsedState(v)\n    callbacksRef.current.onUpdate?.(v)\n  }, [])\n\n  const frameTimestamp = useRef<number>()\n  const onFrame = useCallback<RafLoopCallback>(\n    (timestamp, delta) => {\n      const elapsed = elapsedRef.current + delta\n      setElapsed(elapsed)\n      frameTimestamp.current = timestamp\n    },\n    [setElapsed],\n  )\n  const [isActive, setActive] = useState(false)\n  const { stop, start } = useRafLoop(onFrame, { immediate, throttle, setActive })\n\n  const finalize = useCallback(() => {\n    stop()\n    callbacksRef.current.onComplete?.()\n  }, [stop])\n\n  useEffect(() => {\n    if (!isActive) {\n      return\n    }\n\n    const left = duration - elapsedRef.current\n    const cancel = setTimeoutFrame((timestamp) => {\n      const last = frameTimestamp.current || timestamp\n      const delta = timestamp - last\n      onFrame(timestamp, delta)\n      finalize()\n    }, left)\n\n    return cancel\n  }, [isActive, duration, finalize, onFrame])\n\n  const reset = useCallback(() => {\n    stop()\n    setElapsed(0)\n  }, [stop, setElapsed])\n\n  return {\n    isActive,\n    elapsed,\n    start,\n    stop,\n    reset,\n    sink: finalize,\n  }\n}\n","import { useMemo } from 'react'\n\nconst [MIN, MAX] = [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]\n\nconst clamp =\n  (left = MIN, right = MAX) =>\n  (x: number) =>\n    Math.max(left, Math.min(x, right))\nconst normalize = clamp(0, 1)\n\nconst trim = (x: number, precision = 0) => {\n  const p = Math.max(0, precision - (precision % 1))\n  const mult = 10 ** p\n  return Math.floor(x * mult) / mult\n}\n\n/**\n * Options for configuring the progress calculation.\n */\nexport interface ProgressProps {\n  /** Current elapsed time in milliseconds */\n  elapsed: number\n  /** Total duration in milliseconds */\n  duration: number\n  /** Number of decimal places to round to (default: 4) */\n  precision?: number\n}\n\n/**\n * Return value of the useProgress hook.\n */\nexport interface ProgressReturn {\n  /** Progress value between 0 and 1 */\n  progress: number\n}\n\n/**\n * A React hook that calculates normalized progress (0-1) from elapsed time and duration.\n *\n * @param options - Configuration options for progress calculation\n * @returns Object containing the normalized progress value\n *\n * @example\n * ```tsx\n * const { progress } = useProgress({\n *   elapsed: 2500,\n *   duration: 5000,\n * })\n * // progress === 0.5\n * ```\n *\n * @example\n * With custom precision:\n * ```tsx\n * const { progress } = useProgress({\n *   elapsed: 1234,\n *   duration: 5000,\n *   precision: 2,\n * })\n * // progress === 0.24\n * ```\n */\nexport const useProgress = ({\n  elapsed,\n  duration,\n  precision = 4,\n}: ProgressProps): ProgressReturn => {\n  const progress = useMemo(() => {\n    if (duration === 0) {\n      return 1\n    }\n    const t = elapsed / duration\n    const p = normalize(t)\n\n    return trim(p, precision)\n  }, [elapsed, duration, precision])\n\n  return { progress }\n}\n"],"mappings":"AACA,OAAS,cAAAA,MAAkB,gBAC3B,OAAS,mBAAAC,MAAuB,eAChC,OAAS,eAAAC,EAAa,aAAAC,EAAW,UAAAC,EAAQ,YAAAC,MAAgB,QA+FlD,IAAMC,EAAc,CAAC,CAC1B,SAAAC,EACA,UAAAC,EAAY,GACZ,SAAAC,EAAW,EACX,SAAAC,EACA,WAAAC,CACF,IAAqC,CACnC,IAAMC,EAAeR,EAAO,CAAE,SAAAM,EAAU,WAAAC,CAAW,CAAC,EACpDR,EAAU,IAAM,CACdS,EAAa,QAAU,CAAE,SAAAF,EAAU,WAAAC,CAAW,CAChD,CAAC,EAED,IAAME,EAAaT,EAAO,CAAC,EACrB,CAACU,EAASC,CAAe,EAAIV,EAASQ,EAAW,OAAO,EACxDG,EAAad,EAAae,GAAc,CAC5CJ,EAAW,QAAUI,EACrBF,EAAgBE,CAAC,EACjBL,EAAa,QAAQ,WAAWK,CAAC,CACnC,EAAG,CAAC,CAAC,EAECC,EAAiBd,EAAe,EAChCe,EAAUjB,EACd,CAACkB,EAAWC,IAAU,CACpB,IAAMP,EAAUD,EAAW,QAAUQ,EACrCL,EAAWF,CAAO,EAClBI,EAAe,QAAUE,CAC3B,EACA,CAACJ,CAAU,CACb,EACM,CAACM,EAAUC,CAAS,EAAIlB,EAAS,EAAK,EACtC,CAAE,KAAAmB,EAAM,MAAAC,CAAM,EAAIzB,EAAWmB,EAAS,CAAE,UAAAX,EAAW,SAAAC,EAAU,UAAAc,CAAU,CAAC,EAExEG,EAAWxB,EAAY,IAAM,CACjCsB,EAAK,EACLZ,EAAa,QAAQ,aAAa,CACpC,EAAG,CAACY,CAAI,CAAC,EAETrB,EAAU,IAAM,CACd,GAAI,CAACmB,EACH,OAGF,IAAMK,EAAOpB,EAAWM,EAAW,QAQnC,OAPeZ,EAAiBmB,GAAc,CAC5C,IAAMQ,EAAOV,EAAe,SAAWE,EACjCC,EAAQD,EAAYQ,EAC1BT,EAAQC,EAAWC,CAAK,EACxBK,EAAS,CACX,EAAGC,CAAI,CAGT,EAAG,CAACL,EAAUf,EAAUmB,EAAUP,CAAO,CAAC,EAE1C,IAAMU,EAAQ3B,EAAY,IAAM,CAC9BsB,EAAK,EACLR,EAAW,CAAC,CACd,EAAG,CAACQ,EAAMR,CAAU,CAAC,EAErB,MAAO,CACL,SAAAM,EACA,QAAAR,EACA,MAAAW,EACA,KAAAD,EACA,MAAAK,EACA,KAAMH,CACR,CACF,ECpKA,OAAS,WAAAI,MAAe,QAExB,GAAM,CAACC,EAAKC,CAAG,EAAI,CAAC,OAAO,iBAAkB,OAAO,gBAAgB,EAE9DC,EACJ,CAACC,EAAOH,EAAKI,EAAQH,IACpBI,GACC,KAAK,IAAIF,EAAM,KAAK,IAAIE,EAAGD,CAAK,CAAC,EAC/BE,EAAYJ,EAAM,EAAG,CAAC,EAEtBK,EAAO,CAACF,EAAWG,EAAY,IAAM,CAEzC,IAAMC,EAAO,IADH,KAAK,IAAI,EAAGD,EAAaA,EAAY,CAAE,EAEjD,OAAO,KAAK,MAAMH,EAAII,CAAI,EAAIA,CAChC,EAgDaC,EAAc,CAAC,CAC1B,QAAAC,EACA,SAAAC,EACA,UAAAJ,EAAY,CACd,KAWS,CAAE,SAVQT,EAAQ,IAAM,CAC7B,GAAIa,IAAa,EACf,MAAO,GAET,IAAMC,EAAIF,EAAUC,EACdE,EAAIR,EAAUO,CAAC,EAErB,OAAON,EAAKO,EAAGN,CAAS,CAC1B,EAAG,CAACG,EAASC,EAAUJ,CAAS,CAAC,CAEf","names":["useRafLoop","setTimeoutFrame","useCallback","useEffect","useRef","useState","useRafTimer","duration","immediate","throttle","onUpdate","onComplete","callbacksRef","elapsedRef","elapsed","setElapsedState","setElapsed","v","frameTimestamp","onFrame","timestamp","delta","isActive","setActive","stop","start","finalize","left","last","reset","useMemo","MIN","MAX","clamp","left","right","x","normalize","trim","precision","mult","useProgress","elapsed","duration","t","p"]}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@use-raf/timer",
+  "version": "0.0.2",
+  "description": "React frame-synchronized timer hook",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "react",
+    "hook",
+    "requestAnimationFrame",
+    "raf",
+    "animation",
+    "interval",
+    "timer",
+    "schedule",
+    "setTimer",
+    "progress",
+    "countdown"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check",
+    "lint:fix": "biome check --write"
+  },
+  "peerDependencies": {
+    "react": ">=16.14"
+  },
+  "dependencies": {
+    "@use-raf/loop": "workspace:*",
+    "@use-raf/skd": "workspace:*"
+  },
+  "author": "einouqo",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/einouqo/use-raf"
+  },
+  "bugs": {
+    "url": "https://github.com/einouqo/use-raf/issues"
+  },
+  "license": "MIT"
+}