✨ feat: [URH-14] useTimer 머지 (#33)

[URH-14] useTimer 신규

Author: jeongbaebang

src/hooks/useAsyncTasks.ts

@@ -6,6 +6,8 @@ import {
   PromiseCircularityError,
 } from 'async-wave';
 
+import { delayExecution } from '../utils';
+
 type Task<R> = R | ((input: R) => R | Promise<R> | void | Promise<void>);
 
 type HookOptionProps = {
@@ -95,14 +97,14 @@ const generateTaskHandlers = <R>(
 
       dispatch({ type: ActionType.LOADING });
       options?.initialLazyDelay &&
-        (await delayExecution(options.initialLazyDelay));
+        (await delayExecution(options.initialLazyDelay).start());
       onBefore?.();
     },
     async onSuccess(payload: R) {
       if (!isMountedRef.current) return;
 
       options?.successLazyDelay &&
-        (await delayExecution(options.successLazyDelay));
+        (await delayExecution(options.successLazyDelay).start());
       dispatch({ type: ActionType.SUCCESS, payload });
       onSuccess?.(payload);
     },
@@ -169,13 +171,4 @@ function reducer<R>(state: TaskState<R>, action: TaskAction<R>): TaskState<R> {
   }
 }
 
-/**
- * delayExecution 함수
- * @param {number} ms - 지연 시간 (밀리초)
- * @returns {Promise<void>} 주어진 시간만큼 지연된 후 resolve되는 프로미스
- */
-const delayExecution = (ms: number) => {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-};
-
 export default useAsyncTasks;

src/hooks/useTimer.test.tsx

@@ -0,0 +1,142 @@
+import {
+  renderHook,
+  act,
+  render,
+  screen,
+  fireEvent,
+} from '@testing-library/react';
+import { useState } from 'react';
+import '@testing-library/jest-dom';
+
+import useTimer from './useTimer';
+
+let callback: jest.Mock;
+
+beforeEach(() => {
+  jest.useFakeTimers();
+  callback = jest.fn();
+});
+
+afterEach(() => {
+  jest.clearAllTimers();
+  jest.restoreAllMocks();
+});
+
+afterAll(() => {
+  jest.useRealTimers();
+});
+
+const delay = 3000;
+
+describe('useTimer hook spec', () => {
+  test('start 메서드를 호출하면 타이머가 시작되고, 지정된 시간이 경과한 후 콜백이 호출되어야 한다.', async () => {
+    const spySetTimeout = jest.spyOn(globalThis, 'setTimeout');
+    const { result } = renderHook(() => useTimer(callback, delay));
+
+    act(() => {
+      result.current.start();
+    });
+    jest.advanceTimersByTime(delay);
+    // 비동기 작업을 포함하는 테스트에서 모든 작업이 완료될 때까지 정확히 기다리도록 보장
+    await act(async () => {});
+
+    expect(spySetTimeout).toHaveBeenCalledTimes(1);
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  test('cancel 메서드를 호출하면 타이머가 중단되고, 콜백이 호출되지 않아야 한다.', async () => {
+    const spyClearTimeout = jest.spyOn(globalThis, 'clearTimeout');
+    const { result } = renderHook(() => useTimer(callback, delay));
+
+    act(() => {
+      result.current.start();
+      result.current.cancel();
+    });
+    await act(async () => {});
+
+    expect(callback).toHaveBeenCalledTimes(0);
+    expect(spyClearTimeout).toHaveBeenCalledTimes(1);
+  });
+
+  test('타이머가 완료된 후에는 최신 콜백만을 실행해야 한다.', async () => {
+    const initialCallback = jest.fn();
+    const updatedCallback = jest.fn();
+    const { result, rerender } = renderHook(
+      ({ callback }) => useTimer(callback, delay),
+      {
+        initialProps: { callback: initialCallback },
+      }
+    );
+
+    rerender({ callback: updatedCallback });
+    act(() => {
+      result.current.start();
+    });
+    jest.advanceTimersByTime(delay);
+    await act(async () => {});
+
+    expect(initialCallback).not.toHaveBeenCalled();
+    expect(updatedCallback).toHaveBeenCalledTimes(1);
+  });
+
+  test('언마운트할 때 타이머가 정리되어야 하며, 따라서 콜백이 호출되지 않아야 한다.', async () => {
+    const spySetTimeout = jest.spyOn(globalThis, 'setTimeout');
+    const spyClearTimeout = jest.spyOn(globalThis, 'clearTimeout');
+    const { result, unmount } = renderHook(() => useTimer(callback, delay));
+
+    act(() => {
+      result.current.start();
+    });
+    unmount();
+    jest.advanceTimersByTime(delay);
+    await act(async () => {});
+
+    expect(callback).not.toHaveBeenCalled();
+    expect(spySetTimeout).toHaveBeenCalledTimes(1);
+    expect(spyClearTimeout).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('useTimer를 사용한 컴포넌트 테스트', () => {
+  const TestComponent = () => {
+    const [count, setCount] = useState(0);
+    const { start, cancel } = useTimer(() => {
+      setCount(1234);
+    }, delay);
+
+    return (
+      <div>
+        <p aria-label="count-display">{count}</p>
+        <button onClick={start}>start</button>
+        <button onClick={cancel}>cancel</button>
+      </div>
+    );
+  };
+
+  test('타이머가 진행된 이후 값이 반영되어야 한다.', async () => {
+    const spySetTimeout = jest.spyOn(globalThis, 'setTimeout');
+
+    render(<TestComponent />);
+
+    fireEvent.click(screen.getByText('start'));
+    jest.advanceTimersByTime(delay);
+    await act(async () => {});
+
+    expect(screen.getByLabelText('count-display')).toHaveTextContent('1234');
+    expect(spySetTimeout).toHaveBeenCalledTimes(1);
+  });
+
+  test('타이머가 취소된 경우 값이 변경되지 말아야 한다.', async () => {
+    const spyClearTimeout = jest.spyOn(globalThis, 'clearTimeout');
+
+    render(<TestComponent />);
+
+    fireEvent.click(screen.getByText('start'));
+    fireEvent.click(screen.getByText('cancel'));
+    jest.advanceTimersByTime(delay);
+    await act(async () => {});
+
+    expect(screen.getByLabelText('count-display')).toHaveTextContent('0');
+    expect(spyClearTimeout).toHaveBeenCalledTimes(1);
+  });
+});

src/hooks/useTimer.ts

@@ -0,0 +1,63 @@
+import { useCallback, useEffect, useRef } from 'react';
+
+import { type CancelToken, delayExecution } from '../utils';
+import useUnmountEffect from './useUnmountEffect';
+
+type Callback = () => void;
+
+/**
+ * 일정 시간(ms) 후에 지정된 콜백 함수를 실행하는 타이머 훅.
+ *
+ * @param {function} callback 타이머가 완료된 후 실행할 콜백 함수.
+ * @param {number} ms 지연 시간(밀리초). 양의 정수로 지정.
+ *
+ * @returns {object}
+ *  - `start`: 타이머를 시작하는 함수.
+ *  - `cancel`: 현재 활성화된 타이머를 취소하는 함수.
+ *
+ * @description
+ * - 이 훅은 주어진 시간(ms)이 지난 후 콜백 함수를 실행하는 타이머를 제공합니다.
+ * - `start` 함수를 호출하면 타이머가 시작되며, 지정된 시간이 지나면 콜백 함수가 호출됩니다.
+ * - `cancel` 함수를 호출하면 현재 활성화된 타이머를 취소할 수 있습니다.
+ * - 콜백 함수가 변경될 때마다 참조를 업데이트합니다.
+ * - 컴포넌트가 언마운트될 때 타이머를 정리합니다.
+ */
+const useTimer = (callback: Callback, ms: number) => {
+  const callbackRef = useRef<Callback>(callback);
+  const timerRef = useRef<ReturnType<typeof delayExecution> | null>(null);
+  const cancelTokenRef = useRef<CancelToken>({ isCancelled: false });
+
+  const clearActiveTimer = () => {
+    if (timerRef.current) {
+      cancelTokenRef.current.isCancelled = true;
+
+      timerRef.current.clear();
+    }
+  };
+
+  const startHandler = useCallback(() => {
+    clearActiveTimer(); // 기존 타이머 취소
+
+    (async () => {
+      cancelTokenRef.current = { isCancelled: false };
+      timerRef.current = delayExecution(ms);
+
+      await timerRef.current.start(cancelTokenRef.current);
+      callbackRef.current();
+    })();
+  }, [ms]);
+
+  const cancelHandler = useCallback(() => {
+    clearActiveTimer();
+  }, []);
+
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  useUnmountEffect(clearActiveTimer);
+
+  return { start: startHandler, cancel: cancelHandler };
+};
+
+export default useTimer;

src/utils/delayExecution.test.ts

@@ -0,0 +1,73 @@
+import { delayExecution, type CancelToken } from './delayExecution';
+
+describe('delayExecution', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.clearAllTimers();
+    jest.restoreAllMocks();
+  });
+
+  const delay = 3000;
+
+  test('명시된 시간 후 "started"로 이행해야 한다.', async () => {
+    const spySetTimeout = jest.spyOn(globalThis, 'setTimeout');
+    const { start } = delayExecution(delay);
+    const startPromise = start();
+
+    jest.advanceTimersByTime(delay);
+
+    await expect(startPromise).resolves.toBe('completed');
+    expect(spySetTimeout).toHaveBeenCalledTimes(1);
+  });
+
+  test('취소된 경우 "cancelled"로 이행해야 한다.', async () => {
+    const { start } = delayExecution(delay);
+    const cancelToken: CancelToken = { isCancelled: true };
+    const startPromise = start(cancelToken);
+
+    jest.advanceTimersByTime(delay);
+
+    await expect(startPromise).resolves.toBe('cancelled');
+  });
+
+  test('clear가 호출되면 타임아웃을 해제해야 한다.', () => {
+    const spyClearTimeout = jest.spyOn(globalThis, 'clearTimeout');
+    const { start, clear } = delayExecution(delay);
+
+    start();
+    clear();
+
+    expect(spyClearTimeout).toHaveBeenCalledTimes(1);
+  });
+
+  test('잘못된 cancel token 제공 시 에러가 발생해야 한다.', async () => {
+    const { start } = delayExecution(delay);
+
+    await expect(
+      start({ isCancelled: null } as unknown as CancelToken)
+    ).rejects.toThrow('Invalid cancel token provided');
+    await expect(start({} as CancelToken)).rejects.toThrow(
+      'Invalid cancel token provided'
+    );
+  });
+
+  test('이전 타임아웃이 남아있는 경우 에러가 발생해야 한다.', async () => {
+    const { start } = delayExecution(delay);
+
+    start(); // 첫 번째 시작
+
+    // 이전 타임아웃이 해제되기 전에 다시 시작 시도
+    await expect(start()).rejects.toThrow('Previous timeout is still pending');
+  });
+
+  test('내부에서 예외가 발생하는 경우 rejected 상태에 도달해야 한다.', async () => {
+    (globalThis.setTimeout as unknown) = undefined; // 예외 테스트
+
+    const { start } = delayExecution(delay);
+
+    await expect(start()).rejects.toThrow();
+  });
+});

src/utils/delayExecution.ts

@@ -0,0 +1,69 @@
+export interface CancelToken {
+  isCancelled: boolean;
+}
+
+type Status = 'completed' | 'cancelled';
+
+/**
+ * 지연 함수
+ * @param ms 대기할 시간(밀리초).
+ *
+ * @returns start, clear 시작 및 정리 함수.
+ *
+ * @description
+ * - 지정된 시간(ms) 동안 대기한 후 Promise를 해결합니다.
+ * - 작업은 CancelToken을 사용하여 중간에 취소될 수 있습니다.
+ *
+ * @example
+ * ```ts
+ * await delayExecution(1000).start(); // <-- 1초 지연
+ * task();
+ * ```
+ */
+export const delayExecution = (ms: number) => {
+  let timeoutId: NodeJS.Timeout | undefined;
+  const defaultCancelToken: CancelToken = { isCancelled: false };
+
+  /**
+   * 지연 시작 함수
+   * @param cancelToken 작업을 취소할 수 있는 토큰.
+   *
+   * @returns Promise 작업이 완료되면 'completed', 취소되면 ‘cancelled’로 해결되는 Promise.
+   *
+   * @description
+   * 주어진 시간(ms) 동안 대기한 후, 상태에 따라 Promise를 해결하거나 취소합니다.
+   */
+  const startHandler = (cancelToken: CancelToken = defaultCancelToken) => {
+    return new Promise<Status>((resolve, reject) => {
+      if (!cancelToken || typeof cancelToken.isCancelled !== 'boolean') {
+        return reject(new ReferenceError('Invalid cancel token provided'));
+      }
+
+      if (timeoutId !== undefined) {
+        return reject(new Error('Previous timeout is still pending'));
+      }
+
+      if (cancelToken.isCancelled) {
+        clearHandler();
+        return resolve('cancelled'); // Promise를 resolve하여, 대기 상태에서 벗어나게 처리
+      }
+
+      timeoutId = setTimeout(() => {
+        return resolve('completed');
+      }, ms);
+    });
+  };
+
+  const clearHandler = () => {
+    if (timeoutId !== undefined) {
+      clearTimeout(timeoutId);
+
+      timeoutId = undefined; // 타이머 ID 초기화
+    }
+  };
+
+  return {
+    start: startHandler,
+    clear: clearHandler,
+  };
+};

src/utils/index.ts

@@ -0,0 +1 @@
+export { delayExecution, type CancelToken } from './delayExecution';