✨ feat: useDebounce hook 추가

✅ test: useDebounce 테스트 코드 추가

📝 docs: useDebounce JSDoc 작성

🩹 chore: 인자로 값이 아닌 콜백 함수를 받도록 수정

📝 docs: useDebounce JSDoc 내용 수정

✅ test: useDebounce 콜백 함수 지연 방식 맞게 테스트 코드 수정

🩹 chore: useDebounce 타입을 GenericFn을 사용하여 타입 안전성 개선

✅ test: useDebounce 훅 테스트 케이스 추가

Author: suhyeoonn

src/hooks/useDebounce.test.ts

@@ -0,0 +1,93 @@
+import useDebounce from './useDebounce';
+import { act, renderHook } from '@testing-library/react';
+
+let callback: jest.Mock;
+
+describe('useDebounce', () => {
+  beforeEach(() => {
+    callback = jest.fn();
+  });
+
+  beforeAll(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    callback.mockRestore();
+    jest.clearAllTimers();
+  });
+
+  afterAll(() => {
+    jest.useRealTimers();
+  });
+
+  test('콜백 함수가 반환되는지 확인', () => {
+    const { result } = renderHook(() => useDebounce(callback, 200));
+    expect(typeof result.current).toBe('function');
+  });
+
+  test('디바운스된 콜백 함수가 지연 후 호출되는지 확인', () => {
+    const { result } = renderHook(() => useDebounce(callback, 200));
+
+    jest.advanceTimersByTime(100);
+
+    act(() => {
+      result.current(); // 타이머 다시 시작
+    });
+
+    jest.advanceTimersByTime(100);
+    expect(callback).toHaveBeenCalledTimes(0);
+
+    jest.advanceTimersByTime(100);
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  test('연속적으로 호출되는 경우 마지막 호출만 실행되는지 확인', () => {
+    const { result } = renderHook(() => useDebounce(callback, 200));
+
+    act(() => {
+      result.current();
+    });
+
+    jest.advanceTimersByTime(100);
+    expect(callback).toHaveBeenCalledTimes(0);
+
+    act(() => {
+      result.current();
+    });
+
+    jest.advanceTimersByTime(100);
+    expect(callback).toHaveBeenCalledTimes(0);
+
+    jest.advanceTimersByTime(100); // 마지막 호출 시점으로 200ms 경과
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  test('지연 시간이 변경될 경우 타이머가 재설정되는지 확인', () => {
+    let delay = 200;
+
+    const { rerender, result } = renderHook(() => useDebounce(callback, delay));
+
+    act(() => {
+      result.current();
+    });
+
+    jest.advanceTimersByTime(100);
+    expect(callback).toHaveBeenCalledTimes(0);
+
+    act(() => {
+      delay = 500;
+      rerender();
+    });
+
+    act(() => {
+      result.current();
+    });
+
+    jest.advanceTimersByTime(499);
+    expect(callback).toHaveBeenCalledTimes(0);
+
+    jest.advanceTimersByTime(1); // 지연 시간 변경 후 500ms 경과
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+});

src/hooks/useDebounce.ts

@@ -0,0 +1,39 @@
+import { useCallback, useRef } from 'react';
+import { GenericFn } from '../types';
+
+/**
+ * 주어진 콜백 함수를 디바운스하여, 일정 시간(delay)동안 값이 변경되지 않을 때까지 호출을 지연시키는 훅
+ *
+ * @param {Function} callback - 디바운스하려는 콜백 함수
+ * @param {number} delay - 값이 변경된 후 적용될 때까지 기다릴 시간(밀리초)
+ *
+ * @returns {Function} - 디바운스된 콜백 함수
+ *
+ * @description
+ * `useDebounce` 훅은 주어진 콜백 함수가 일정 시간(`delay`) 동안 호출되지 않을 때까지 콜백 함수를 지연시킵니다.
+ * 이는 입력 필드와 같은 사용자 입력을 처리할 때 유용하며, 사용자가 입력을 멈춘 후에만
+ * 콜백 함수가 호출되도록 합니다. 이를 통해 불필요한 렌더링이나 API 호출을 줄일 수 있습니다.
+ **/
+
+const useDebounce = <T extends unknown[]>(
+  callback: GenericFn<T>,
+  delay: number
+) => {
+  const timerRef = useRef<number>();
+
+  const debouncedCallback = useCallback(
+    (...args: T) => {
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+      }
+      timerRef.current = window.setTimeout(() => {
+        callback(...args);
+      }, delay);
+    },
+    [callback, delay]
+  );
+
+  return debouncedCallback;
+};
+
+export default useDebounce;

src/types/index.ts

@@ -1 +1,3 @@
 export type Fn = () => void;
+
+export type GenericFn<T extends unknown[]> = (...args: T) => void;