[250520 TIL] useDebounce 훅 개선

🧩 문제정의

React에서 디바운스 기능이 필요한 상황에 대응하기 위해 직접 커스텀 훅 useDebounce를 만들어 사용하고 있었습니다.
기본적으로 useCallback과 useRef만으로 구현했기 때문에 간단하고 직관적이었으나,
콜백이 최신 상태를 반영하지 않거나 props로 전달 시 리렌더링을 유발하는 등의 숨겨진 안정성 문제가 있었습니다.

원래 코드

import { useCallback, useRef } from "react";

type Debounce<T extends unknown[]> = (...args: T) => void;

export const useDebounce = <T extends unknown[]>(
    func: (...args: T) => void,
    delay: number,
): Debounce<T> => {
    const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);

    return useCallback(
        (...args: T) => {
            if (timerRef.current !== null) {
                clearTimeout(timerRef.current);
            }
            timerRef.current = setTimeout(() => {
                func(...args);
            }, delay);
        },
        [func, delay],
    );
};

---

🛠 해결과정

🔍 오픈소스 코드 분석

Next.js 기반 대시보드 오픈소스 프로젝트에서
useDebouncedCallback과 useCallbackRef라는 조합이 더 안정적이고 범용적인 형태로 사용되고 있는 것을 발견했습니다.

🔁 주요 개선점

1. 명확한 네이밍
   • useDebounce → useDebouncedCallback으로 변경하여 역할을 보다 명확히 표현
   • func → callback으로 의미를 명확히 드러냄
2. useCallbackRef 도입
   • callback을 ref로 고정하여 최신 상태를 유지하면서도 불필요한 re-render를 막음
   • 내부적으로 useMemo로 클로저를 고정하여 prop으로 전달해도 안전함
3. 타입 안정성 강화
   • <T extends unknown[]> → <T extends (...args: never[]) => unknown> 변경
   • 전달받는 함수 전체를 제네릭 타입으로 제한하여 Parameters<T>와 ReturnType<T>를 더 정확히 사용할 수 있게 함

개선된 코드

// use-callback-ref.ts

/**
* 콜백을 참조로 변환하여 prop으로 전달될 때 리렌더링을 방지하거나, 
* deps로 전달될 때 효과를 재실행하지 않도록 하는 커스텀훅
*/
export function useCallbackRef<T extends (...args: never[]) => unknown>(
    callback: T | undefined
): T {
    const callbackRef = useRef(callback);

    useEffect(() => {
        callbackRef.current = callback;
    });

    // https://github.com/facebook/react/issues/19240 
    // useCallback이 아닌 useMemo를 쓰는 이유는 위 링크 참고
    return useMemo(
        () => ((...args) => callbackRef.current?.(...args)) as T,
        []
    );
}

// use-debounced-callback.ts
import { useCallbackRef } from '@/hooks/use-callback-ref';

export function useDebouncedCallback<T extends (...args: never[]) => unknown>(
    callback: T,
    delay: number
) {
    const handleCallback = useCallbackRef(callback);
    const debounceTimerRef = useRef(0);

    useEffect(() => {
        return () => clearTimeout(debounceTimerRef.current);
    }, []);

    return useCallback((...args: Parameters<T>) => {
        clearTimeout(debounceTimerRef.current);
        debounceTimerRef.current = setTimeout(
            () => handleCallback(...args),
            delay
        );
    }, [handleCallback, delay]);
}

---

💡 배운점 & 인사이트

• 단순히 동작하는 코드와 안전하게 동작하는 코드의 차이를 실감할 수 있었습니다.
• useCallbackRef와 같은 추상화는 코드 재사용성과 안정성을 동시에 높이는 좋은 패턴임을 알게 되었습니다.
• 제네릭 타입 설계에서 never[]를 활용한 함수 타입 제약은 타입 추론 정확도를 높이고 실수를 방지할 수 있었습니다.
• 직접 만든 간단한 훅도, 오픈소스의 관용적인 패턴과 비교해보며 개선 여지를 탐색해보는 습관이 중요하다는 것을 다시 한 번 깨달았습니다.