Add useRafDebounce hook

Author: trashpanda001

.mise.toml

@@ -2,5 +2,5 @@
 PRETTIER_EXPERIMENTAL_CLI = "1"
 
 [tools]
-node = "22.21.0"
-pnpm = "10.19.0"
+node = "24.11.0"
+pnpm = "10.20.0"

package.json

@@ -1,12 +1,12 @@
 {
   "name": "@trashpanda001/helpers",
   "description": "Helpers for my projects.",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "type": "module",
   "engines": {
-    "node": "^22.0.0"
+    "node": ">=22.0.0"
   },
-  "packageManager": "pnpm@10.19.0",
+  "packageManager": "pnpm@10.20.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -61,7 +61,7 @@
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.0",
     "@types/luxon": "^3.7.1",
-    "@types/node": "^22.18.12",
+    "@types/node": "^24.9.1",
     "@types/react": "^19.2.2",
     "@types/react-dom": "^19.2.2",
     "@types/string-natural-compare": "^3.0.4",

pnpm-lock.yaml

@@ -15,6 +15,7 @@ export { useIsMounted } from "./use-is-mounted.js"
 export { useIsPageVisible } from "./use-is-page-visible.js"
 export { useIsPortrait } from "./use-is-portrait.js"
 export { useMediaQuery } from "./use-media-query.js"
+export { useRafDebounce } from "./use-raf-debounce.js"
 export { useResizeObserver } from "./use-resize-observer.js"
 export { useToggle } from "./use-toggle.js"
 export { useViewport, type ViewportInfo } from "./use-viewport.js"

src/react/index.ts

@@ -0,0 +1,66 @@
+import { act, renderHook } from "@testing-library/react"
+import { useRafDebounce } from "@trashpanda001/helpers/react"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+
+describe("useRafDebounce", () => {
+  let rafCallbacks: Map<number, FrameRequestCallback>
+  let cancelledHandles: number[]
+  let nextHandle: number
+
+  beforeEach(() => {
+    nextHandle = 1
+    rafCallbacks = new Map()
+    cancelledHandles = []
+
+    const stubbedRequestAnimationFrame: typeof requestAnimationFrame = (callback) => {
+      const handle = nextHandle++
+      rafCallbacks.set(handle, callback)
+      return handle
+    }
+
+    const stubbedCancelAnimationFrame: typeof cancelAnimationFrame = (handle) => {
+      cancelledHandles.push(handle)
+      rafCallbacks.delete(handle)
+    }
+
+    vi.stubGlobal("requestAnimationFrame", stubbedRequestAnimationFrame)
+    vi.stubGlobal("cancelAnimationFrame", stubbedCancelAnimationFrame)
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it("only executes the latest invocation on the next animation frame", () => {
+    const callback = vi.fn<(value: string) => void>()
+    const { result } = renderHook(() => useRafDebounce(callback))
+
+    act(() => {
+      result.current("first")
+    })
+
+    const handlesAfterFirst = [...rafCallbacks.keys()]
+    expect(handlesAfterFirst).toHaveLength(1)
+    const firstHandle = handlesAfterFirst[0]!
+
+    act(() => {
+      result.current("second")
+    })
+
+    const handles = [...rafCallbacks.keys()]
+    expect(handles).toHaveLength(1)
+    const latestHandle = handles[0]!
+
+    expect(cancelledHandles).toContain(firstHandle)
+    expect(callback).not.toHaveBeenCalled()
+
+    act(() => {
+      const frame = rafCallbacks.get(latestHandle)
+      expect(frame).toBeDefined()
+      frame?.(16 as DOMHighResTimeStamp)
+    })
+
+    expect(callback).toHaveBeenCalledTimes(1)
+    expect(callback).toHaveBeenCalledWith("second")
+  })
+})

src/react/use-raf-debounce.test.ts

@@ -0,0 +1,34 @@
+import { useCallback, useRef } from "react"
+
+/**
+ * Debounces a callback using requestAnimationFrame to sync with display refresh rate.
+ *
+ * This is ideal for high-frequency events like scroll, resize, or mousemove that need
+ * to update the UI. Instead of running on every event (which can be 1000+ times/sec),
+ * the callback runs at the display refresh rate (60fps/120fps).
+ *
+ * @param callback - Function to debounce
+ * @returns Debounced function that runs at display refresh rate
+ *
+ * @example
+ * ```tsx
+ * const debouncedScroll = useRafDebounce(() => {
+ *   updateScrollPosition()
+ * })
+ *
+ * window.addEventListener('scroll', debouncedScroll, { passive: true })
+ * window.removeEventListener('scroll', debouncedScroll)
+ * ```
+ */
+export function useRafDebounce<T extends unknown[]>(callback: (...args: T) => void): (...args: T) => void {
+  const handleRef = useRef(0)
+  return useCallback(
+    (...args: T) => {
+      cancelAnimationFrame(handleRef.current)
+      handleRef.current = requestAnimationFrame((_time: DOMHighResTimeStamp) => {
+        callback(...args)
+      })
+    },
+    [callback],
+  )
+}