Introduction
In my last side project, I needed to debounce a callback. I ended up writing a custom hook to do so. In this post, I'll explain how it works. The tricky part is grasping why we need the callback ref.
import { useCallback, useEffect, useRef } from 'react'
export function useDebounceCallback<Args extends Array<unknown>>(
callback: (...args: Args) => void,
delay: number
): (...args: Args) => void {
const timeoutRef = useRef<NodeJS.Timeout | null>(null)
const callbackRef = useRef(callback)
useEffect(() => {
callbackRef.current = callback
}, [callback])
const debouncedCallback = useCallback(
(...args: Args) => {
if (timeoutRef.current) {
clearTimeout(timeoutRef.current)
}
timeoutRef.current = setTimeout(() => {
callbackRef.current(...args)
}, delay)
},
[delay]
)
useEffect(() => {
return () => {
if (timeoutRef.current) {
clearTimeout(timeoutRef.current)
}
}
}, [])
return debouncedCallback
}
What is a closure?
First, we need to understand what a closure is.
A closure is when a function "remembers" the variables from its outer scope, even when executed later. It captures these variables at the time the function is created. This is a fundamental feature of JavaScript.
Here is an example:
function outer() {
let x = 1;
return function inner() {
console.log(x);
};
}
const fn = outer();
fn();
Okay? Why does it matter?
Here is a clearer example why closures are important:
let x = 1;
const fn = () => console.log(x);
x = 2;
setTimeout(fn, 1000);
When calling fn later, it will still remember the value of x from the outer scope. Even if x is changed later.
Closures and React
Here is a basic React example:
function MyComponent() {
const [count, setCount] = useState(0);
const logCount = () => console.log(count);
setTimeout(logCount, 1000);
}
A more interesting example:
function MyComponent() {
const [count, setCount] = useState(0);
const debouncedLog = useCallback(() => {
setTimeout(() => {
console.log(count);
}, 1000);
}, []);
}
Here, I hope it's starting to click. If count was e.g. 5 at the time useCallback was run, it will always log 5. You can tell setTimeout to execute an hour later. It's still going to log 5 (even if the value is 1000 by then).
Why? Because that's what it "remembers".
The callback ref pattern
const debouncedCallback = useCallback(
(...args: Args) => {
if (timeoutRef.current) {
clearTimeout(timeoutRef.current);
}
timeoutRef.current = setTimeout(() => {
callbackRef.current(...args);
}, delay);
},
[delay]
);
Looking back the previous examples, you might go "this is impossible to update".
Well, it's not. Refs are just mutable objects. In this case, the closure will capture callbackRef's reference.
So when callbackRef.current is called, it looks at the REFERENCE of callbackRef and THEN gets redirected to the current property of callbackRef.
The current field ALWAYS holds the latest callback.
useEffect(() => {
callbackRef.current = newCallback;
}, [callback]);
To be very explicit, setTimeout works as it always does. It creates a closure over callbackRef's reference.
But Tiger, why is it not closing over .current field?
That's a good question.
The key is in how the code is written.
setTimeout(() => {
callbackRef.current(...args);
}, delay);
const currentCallback = callbackRef.current;
setTimeout(() => {
currentCallback(...args);
}, delay);
The second bit here GETS the value of callbackRef.current before the closure is created. Therefore, a closure will be created over this specific value.
When you write callbackRef.current(...args), you're writing ONE expression that:
First gets the reference (callbackRef)
Then follows that reference
Then gets the .current property and uses it
All at execution time!
Recap with final example
const callbackRef = { current: originalCallback };
callbackRef.current = newCallback;
const currentCallback = callbackRef.current;
By Value vs By Reference
If you've a hard time understanding the concept of "reference", I recommend reading this: By value vs By Reference in JavaScript.
