Merge pull request #92 from frontend-opensource-project/URH-105/use-async-tasks

[URH-105] useAsyncTasks 문서 작성 & 버그 픽스

Author: bicochan

docs/pages/hooks/_meta.json

@@ -1,4 +1,5 @@
 {
+  "useAsyncTasks": "useAsyncTasks",
   "useClipboard": "useClipboard",
   "useConfirm": "useConfirm",
   "useDebounce": "useDebounce",
@@ -7,12 +8,16 @@
   "useDetectDevice": "useDetectDevice",
   "useGeolocation": "useGeolocation",
   "useHover": "useHover",
+  "useIntersectionObserver": "useIntersectionObserver",
   "useInterval": "useInterval",
   "useKeyCombination": "useKeyCombination",
+  "useKeyDown": "useKeyDown",
+  "useLocalStorage": "useLocalStorage",
   "useLongPress": "useLongPress",
+  "useMockData": "useMockData",
   "useMousePosition": "useMousePosition",
-  "useIntersectionObserver": "useIntersectionObserver",
   "useOnlineStatus": "useOnlineStatus",
+  "useOutsideClick": "useOutsideClick",
   "usePrefersColorScheme": "usePrefersColorScheme",
   "usePreventCopy": "usePreventCopy",
   "useScrollLock": "useScrollLock",
@@ -22,11 +27,7 @@
   "useToggle": "useToggle",
   "useTranslation": "useTranslation",
   "useUnmountEffect": "useUnmountEffect",
-  "useOutsideClick": "useOutsideClick",
-  "useKeyDown": "useKeyDown",
-  "useMockData": "useMockData",
   "useWorker": "useWorker",
-  "useLocalStorage": "useLocalStorage",
   "_template": {
     "display": "hidden"
   }

docs/pages/hooks/useAsyncTasks.mdx

@@ -0,0 +1,68 @@
+# useAsyncTasks
+
+## Introduce
+
+비동기 작업 리스트와 옵션을 받아 로딩 상태, 데이터, 오류 등을 관리하며, 컴포넌트 언마운트 시 상태 업데이트를 방지합니다.
+
+```tsx
+interface UseAsyncTasksProps<R> {
+  tasks: Task<R>[];
+  options?: Options<R>;
+}
+
+interface UseAsyncTasksReturns<R> {
+  isLoading: boolean;
+  data: R | null;
+  error: Error | null;
+  isError: boolean;
+  reset: () => void;
+}
+
+const useAsyncTasks = <R>(tasks: Task<R>[], options: Options<R>): UseAsyncTasksReturns<R> => { ... }
+```
+
+### Props
+
+- `tasks` : 실행할 비동기 작업들의 배열입니다. 비동기 함수 외에도 일반 함수, 원시 데이터 등을 전달할 수 있습니다.
+
+### Returns
+
+- `isLoading` : 현재 비동기 작업이 진행 중인지 여부를 나타내는 불리언 값입니다.
+- `data` : 성공적으로 완료된 작업의 결과를 담고 있는 데이터입니다.
+- `error` : 작업 중 발생한 오류 정보를 포함합니다.
+- `isError` : 오류가 발생했는지 여부를 나타내는 불리언 값입니다.
+- `reset` : 이전 상태를 초기화하여 초기 상태로 되돌리는 함수입니다.
+
+## Examples
+
+```tsx copy filename="TestComponent.tsx"
+const fetchUsers = async () => {
+  const response = await fetch(`https://jsonplaceholder.typicode.com/users`);
+  if (!response.ok) throw new Error('사용자 목록을 가져오지 못했습니다.');
+  return response.json();
+};
+
+const TestComponent = () => {
+  const { isLoading, data, error, isError, reset } = useAsyncTasks<
+    { id: string; name: string }[]
+  >([fetchUsers], {
+    onSuccess: () => console.log('사용자 목록을 성공적으로 가져왔습니다!'),
+    onError: (err) => console.error('오류:', err),
+  });
+
+  return (
+    <div>
+      <button onClick={reset}>재로드</button>
+      {isLoading && <p>로딩 중...</p>}
+      {isError && <p>오류: {error?.message}</p>}
+      {data && (
+        <ul>
+          {data.map((user) => (
+            <li key={user.id}>{user.name}</li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+};
+```

src/hooks/useAsyncTasks/reducer.ts

@@ -9,14 +9,20 @@ export function reducer<R>(
       return { ...state, isLoading: true, error: null };
     case ACTION_TYPES.SUCCESS:
       return {
+        ...state,
         isLoading: false,
         data: action.payload,
         error: null,
       };
     case ACTION_TYPES.ERROR:
       return { ...state, isLoading: false, error: action.payload };
     case ACTION_TYPES.RESET:
-      return { isLoading: false, data: null, error: null };
+      return {
+        isLoading: false,
+        data: null,
+        error: null,
+        resetTrigger: state.resetTrigger + 1,
+      };
     default:
       throw new Error('Unhandled task action type');
   }

src/hooks/useAsyncTasks/type.ts

@@ -36,6 +36,7 @@ export interface TaskState<R> {
   isLoading: boolean;
   data: R | null;
   error: PromiseCircularityError | null;
+  resetTrigger: number;
 }
 
 export type TaskAction<R> =

src/hooks/useAsyncTasks/useAsyncTasks.ts

@@ -6,26 +6,38 @@ import {
   PromiseCircularityError,
 } from 'async-wave';
 import { delayExecution } from '@/utils';
+
 import { Task, Options, StateInfo, TaskAction, ACTION_TYPES } from './type';
 import { reducer } from './reducer';
 
 /**
- * useAsyncTasks
+ * useAsyncTasks: 비동기 작업 리스트와 옵션을 받아 상태 정보를 관리하는 훅
+ *
  * @param {Task<R>[]} tasks - 비동기 작업 리스트
- * @param {Options<R>} options - 비동기 작업 옵션
+ *   - 실행할 비동기 작업들을 담은 배열입니다.
+ * @param {Options<R>} [options={}] - 비동기 작업 옵션
+ *   - 비동기 작업 실행 중 설정할 옵션. 선택적이며 기본값은 빈 객체입니다.
+ *
  * @returns {StateInfo<R>} 비동기 작업 상태 정보를 반환
+ *   - 작업의 로딩 상태, 데이터, 오류 정보를 포함합니다.
+ *   - 추가적으로 `isError` 속성을 통해 오류 여부를 확인할 수 있고, `reset` 메서드를 통해 상태를 초기화할 수 있습니다.
+ *
+ * @description
+ * - 비동기 작업을 관리하며, 작업의 상태 정보(로딩, 데이터, 오류)를 제공합니다.
+ * - 컴포넌트 언마운트 시, 비동기 작업이 완료된 후 상태 업데이트를 방지합니다.
+ * - `reset` 메서드를 호출하여 상태를 초기화할 수 있습니다.
  */
 const useAsyncTasks = <R>(tasks: Task<R>[], options: Options<R>) => {
   const isMountedRef = useRef(false); // 컴포넌트가 언마운트된 후 비동기 작업이 완료될 때 상태 업데이트를 방지
   const [state, dispatch] = useReducer(reducer<R>, {
     isLoading: false,
     data: null,
     error: null,
+    resetTrigger: 0,
   });
 
   useEffect(() => {
     isMountedRef.current = true;
-
     (async () => {
       await asyncWave<R>(
         [...tasks],
@@ -37,16 +49,15 @@ const useAsyncTasks = <R>(tasks: Task<R>[], options: Options<R>) => {
       isMountedRef.current = false;
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
+  }, [state.resetTrigger]);
 
   const stateInfo: StateInfo<R> = useMemo(
     () => ({
       ...state,
       isError: Boolean(state.error),
       reset() {
-        dispatch({
-          type: ACTION_TYPES.RESET,
-        });
+        dispatch({ type: ACTION_TYPES.RESET });
+        isMountedRef.current = false;
       },
     }),
     [state]