The Three Hidden Bugs Lurking in Your Debounce Hook for Two Years

These bugs survive code review and basic testing because they only surface under specific timing conditions—rapid navigation, filter changes during a debounce window, or clear-button interactions. Once a codebase grows large enough, those edge cases become inevitable, and the resulting state corruption or stale-data requests are notoriously hard to reproduce and debug.

A widely used `useDebounce` implementation, copied from the web and dropped into a React project, hid three distinct bugs that survived two years of production use. The first is a missing cleanup on component unmount, which lets callbacks fire after a component is gone and triggers React state-update warnings. The second is a stale closure: the callback captured on first render never updates, so any state it closes over—like a search category filter—remains frozen at its initial value. The third is the absence of a cancel method, which means a queued debounce call cannot be interrupted; clearing a search box, for example, gets overwritten 300ms later when the pending callback fires.

The fixes are straightforward but mandatory. Clean up timers in a `useEffect` return function. Store the latest callback in a `ref` and update it on every render, then call `callbackRef.current` inside the timeout. Expose a `cancel` function that clears the timer and nulls the ref. The same three bugs apply to throttle Hooks, with the added decision of whether to use leading or trailing execution semantics. Utility functions that "just work" are the easiest places to bury landmines because no one re-examines code that hasn't visibly broken.