@universal-uploader/react 1.0.0

package/dist/index.cjs

@@ -0,0 +1,237 @@
+'use strict';
+
+var uploadCore = require('@universal-uploader/core');
+var react = require('react');
+
+const INITIAL_UPLOAD_RESULT = {
+    ok: false,
+    total: 0,
+    message: undefined,
+    status: "idle",
+};
+const FALLBACK_UPLOAD_OPTIONS = {};
+/**
+ * A custom React hook for handling universal file uploads with streaming support and fallbacks.
+ * 스트리밍 지원 및 폴백 기능을 갖춘 범용 파일 업로드를 처리하기 위한 커스텀 React 훅입니다.
+ */
+function useUniversalUpload({ url, options, }) {
+    const [status, setStatus] = react.useState("idle");
+    const [error, setError] = react.useState(null);
+    const [result, setResult] = react.useState(INITIAL_UPLOAD_RESULT);
+    /**
+     * The previous request abort function.
+     * 이전의 요청 중단 함수입니다.
+     */
+    const prevReqAbortRef = react.useRef({
+        abort: () => null,
+        refresh: () => null,
+        pause: () => null,
+        resume: () => null,
+    });
+    /**
+     * The latest upload request ID.
+     * 가장 최근의 업로드 요청 ID입니다.
+     */
+    const latestUploadRequestIdRef = react.useRef(0);
+    /**
+     * The options object.
+     * deps에 포함되지 않는 옵션 객체입니다.
+     */
+    const optionRef = react.useRef(options ?? FALLBACK_UPLOAD_OPTIONS);
+    // eslint-disable-next-line react-hooks/refs
+    optionRef.current = options ?? FALLBACK_UPLOAD_OPTIONS;
+    /**
+     * Updates the upload result and status state.
+     * 업로드 결과 및 상태 스테이트를 업데이트합니다.
+     */
+    const updateUploadResult = react.useCallback((uploadResult) => {
+        setResult(uploadResult);
+        setStatus(uploadResult.status);
+        if (uploadResult.status === "error") {
+            setError((prevError) => prevError ?? new Error(uploadResult.message || "Upload failed"));
+        }
+    }, []);
+    /**
+     * Core upload logic that manages request lifecycle and status updates.
+     * 요청 수명 주기 및 상태 업데이트를 관리하는 핵심 업로드 로직입니다.
+     */
+    const upload = react.useCallback(async (file) => {
+        /**
+         * Increment the latest upload request ID.
+         * 가장 최근의 업로드 요청 ID를 증가시킵니다.
+         *
+         * Set the latest upload request ID to the current value.
+         * 가장 최근의 업로드 요청 ID를 현재 값으로 설정합니다.
+         *
+         * Check if the current request is the latest upload request.
+         * 현재 요청이 가장 최근의 업로드 요청인지 확인합니다.
+         */
+        latestUploadRequestIdRef.current += 1;
+        const latestUploadRequestId = latestUploadRequestIdRef.current;
+        const isLatestUploadRequest = () => latestUploadRequestIdRef.current === latestUploadRequestId;
+        /**
+         * If the previous request is still in progress, abort it.
+         * 이전의 요청이 아직 진행 중이라면 중단합니다.
+         */
+        prevReqAbortRef.current.abort();
+        /**
+         * Reset external progress UI before a new upload starts.
+         * 새 업로드가 시작되기 전에 외부 progress UI를 초기화합니다.
+         */
+        optionRef.current?.onProgress?.({ loaded: 0, total: 0, percentage: 0 });
+        setStatus("uploading");
+        setError(null);
+        setResult(INITIAL_UPLOAD_RESULT);
+        const { current: $options } = optionRef;
+        const { result: uploadResultPromise, actions: uploadActions } = await uploadCore({
+            url,
+            file,
+            options: {
+                ...$options,
+                onComplete: () => {
+                    $options.onComplete?.();
+                    if (isLatestUploadRequest()) {
+                        setStatus("success");
+                        setResult((prevResult) => ({
+                            ...prevResult,
+                            ok: true,
+                            status: "success",
+                        }));
+                    }
+                },
+                onError: (e) => {
+                    $options.onError?.(e);
+                    if (isLatestUploadRequest()) {
+                        setError(e);
+                        setStatus("error");
+                        setResult((prevResult) => ({
+                            ...prevResult,
+                            ok: false,
+                            status: "error",
+                        }));
+                    }
+                },
+                onAbort: (e) => {
+                    $options.onAbort?.(e);
+                    if (isLatestUploadRequest()) {
+                        setStatus("aborted");
+                        setResult((prevResult) => ({
+                            ...prevResult,
+                            ok: false,
+                            status: "aborted",
+                        }));
+                    }
+                },
+                onProgress: (args) => {
+                    $options.onProgress?.(args);
+                    if (isLatestUploadRequest()) {
+                        setStatus("uploading");
+                        setResult({
+                            ok: false,
+                            total: args.total,
+                            status: "uploading",
+                        });
+                    }
+                },
+                onRetry: () => {
+                    $options.onRetry?.();
+                    if (isLatestUploadRequest()) {
+                        setStatus("uploading");
+                        setResult(INITIAL_UPLOAD_RESULT);
+                        setError(null);
+                    }
+                },
+                onPause: () => {
+                    $options.onPause?.();
+                    if (isLatestUploadRequest()) {
+                        setStatus("paused");
+                        setResult((prevResult) => ({
+                            ...prevResult,
+                            ok: false,
+                            status: "paused",
+                        }));
+                    }
+                },
+                onResume: () => {
+                    $options.onResume?.();
+                    if (isLatestUploadRequest()) {
+                        setStatus("uploading");
+                        setResult((prevResult) => ({
+                            ...prevResult,
+                            status: "uploading",
+                        }));
+                    }
+                },
+            },
+        });
+        /**
+         * If the current request is not the latest upload request, abort the request.
+         * 현재 요청이 가장 최근의 업로드 요청이 아니라면 요청을 중단합니다.
+         */
+        if (!isLatestUploadRequest()) {
+            uploadActions.abort();
+            return;
+        }
+        // Set the previous request abort function to the current abort function.
+        // 이전의 요청 중단 함수를 현재의 요청 중단 함수로 설정합니다.
+        prevReqAbortRef.current = uploadActions;
+        const uploadResult = await uploadResultPromise;
+        /**
+         * If the current request is not the latest upload request, do not update the result status.
+         * 현재 요청이 가장 최근의 업로드 요청이 아니라면 결과 상태 업데이트를 하지 않고 반환합니다.
+         */
+        if (!isLatestUploadRequest()) {
+            return;
+        }
+        updateUploadResult(uploadResult);
+    }, [url, updateUploadResult]);
+    /**
+     * Executes the upload with error handling and optional re-throwing.
+     * 에러 핸들링 및 선택적 re-throw 기능을 포함하여 업로드를 실행합니다.
+     */
+    const uploadSafely = react.useCallback(async (file) => {
+        try {
+            await upload(file);
+        }
+        catch (e) {
+            setError(e);
+            setStatus("error");
+            setResult({ ...INITIAL_UPLOAD_RESULT, status: "error" });
+            const { current: $options } = optionRef;
+            const shouldThrow = typeof $options.throwOnError === "function"
+                ? $options.throwOnError(e)
+                : Boolean($options.throwOnError);
+            if (shouldThrow) {
+                throw e;
+            }
+        }
+    }, [upload]);
+    react.useEffect(() => {
+        return () => {
+            prevReqAbortRef.current.abort();
+        };
+    }, []);
+    react.useEffect(() => {
+        optionRef.current?.onUrlChange?.(url);
+    }, [url]);
+    react.useEffect(() => {
+        optionRef.current?.onMethodChange?.(optionRef.current.method);
+    }, [options?.method]);
+    return {
+        upload: uploadSafely,
+        /**
+         * Alias for upload — restarts upload after abort, error, or success.
+         * upload의 별칭 — 중단, 실패, 성공 이후 업로드를 다시 시작할 때 사용합니다.
+         */
+        retry: uploadSafely,
+        result,
+        status,
+        error,
+        abort: () => prevReqAbortRef.current.abort(),
+        pause: () => prevReqAbortRef.current.pause(),
+        resume: () => prevReqAbortRef.current.resume(),
+    };
+}
+
+exports.useUniversalUpload = useUniversalUpload;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/useUniversalUpload.tsx"],"sourcesContent":["import uploadCore, {\n  UploadResult,\n  UploadStatus,\n  UploadActions,\n} from \"@universal-uploader/core\";\nimport { UploadHookOptions } from \"./types\";\nimport { useCallback, useEffect, useRef, useState } from \"react\";\n\nconst INITIAL_UPLOAD_RESULT: Readonly<UploadResult> = {\n  ok: false,\n  total: 0,\n  message: undefined,\n  status: \"idle\",\n};\n\nconst FALLBACK_UPLOAD_OPTIONS: Readonly<UploadHookOptions> = {};\n\ninterface UseUniversalUploadArgs {\n  url: string;\n  options?: UploadHookOptions;\n}\n\n/**\n * A custom React hook for handling universal file uploads with streaming support and fallbacks.\n * 스트리밍 지원 및 폴백 기능을 갖춘 범용 파일 업로드를 처리하기 위한 커스텀 React 훅입니다.\n */\nexport default function useUniversalUpload({\n  url,\n  options,\n}: UseUniversalUploadArgs) {\n  const [status, setStatus] = useState<UploadStatus>(\"idle\");\n  const [error, setError] = useState<Error | null>(null);\n  const [result, setResult] = useState<UploadResult>(INITIAL_UPLOAD_RESULT);\n\n  /**\n   * The previous request abort function.\n   * 이전의 요청 중단 함수입니다.\n   */\n  const prevReqAbortRef = useRef<UploadActions>({\n    abort: () => null,\n    refresh: () => null,\n    pause: () => null,\n    resume: () => null,\n  });\n\n  /**\n   * The latest upload request ID.\n   * 가장 최근의 업로드 요청 ID입니다.\n   */\n  const latestUploadRequestIdRef = useRef(0);\n\n  /**\n   * The options object.\n   * deps에 포함되지 않는 옵션 객체입니다.\n   */\n  const optionRef = useRef<UploadHookOptions>(\n    options ?? FALLBACK_UPLOAD_OPTIONS,\n  );\n  // eslint-disable-next-line react-hooks/refs\n  optionRef.current = options ?? FALLBACK_UPLOAD_OPTIONS;\n\n  /**\n   * Updates the upload result and status state.\n   * 업로드 결과 및 상태 스테이트를 업데이트합니다.\n   */\n  const updateUploadResult = useCallback((uploadResult: UploadResult) => {\n    setResult(uploadResult);\n    setStatus(uploadResult.status);\n\n    if (uploadResult.status === \"error\") {\n      setError(\n        (prevError) =>\n          prevError ?? new Error(uploadResult.message || \"Upload failed\"),\n      );\n    }\n  }, []);\n\n  /**\n   * Core upload logic that manages request lifecycle and status updates.\n   * 요청 수명 주기 및 상태 업데이트를 관리하는 핵심 업로드 로직입니다.\n   */\n  const upload = useCallback(\n    async (file: File) => {\n      /**\n       * Increment the latest upload request ID.\n       * 가장 최근의 업로드 요청 ID를 증가시킵니다.\n       *\n       * Set the latest upload request ID to the current value.\n       * 가장 최근의 업로드 요청 ID를 현재 값으로 설정합니다.\n       *\n       * Check if the current request is the latest upload request.\n       * 현재 요청이 가장 최근의 업로드 요청인지 확인합니다.\n       */\n      latestUploadRequestIdRef.current += 1;\n      const latestUploadRequestId = latestUploadRequestIdRef.current;\n      const isLatestUploadRequest = () =>\n        latestUploadRequestIdRef.current === latestUploadRequestId;\n\n      /**\n       * If the previous request is still in progress, abort it.\n       * 이전의 요청이 아직 진행 중이라면 중단합니다.\n       */\n      prevReqAbortRef.current.abort();\n\n      /**\n       * Reset external progress UI before a new upload starts.\n       * 새 업로드가 시작되기 전에 외부 progress UI를 초기화합니다.\n       */\n      optionRef.current?.onProgress?.({ loaded: 0, total: 0, percentage: 0 });\n\n      setStatus(\"uploading\");\n      setError(null);\n      setResult(INITIAL_UPLOAD_RESULT);\n\n      const { current: $options } = optionRef;\n\n      const { result: uploadResultPromise, actions: uploadActions } =\n        await uploadCore({\n          url,\n          file,\n          options: {\n            ...$options,\n            onComplete: () => {\n              $options.onComplete?.();\n              if (isLatestUploadRequest()) {\n                setStatus(\"success\");\n                setResult((prevResult) => ({\n                  ...prevResult,\n                  ok: true,\n                  status: \"success\",\n                }));\n              }\n            },\n            onError: (e) => {\n              $options.onError?.(e);\n              if (isLatestUploadRequest()) {\n                setError(e);\n                setStatus(\"error\");\n                setResult((prevResult) => ({\n                  ...prevResult,\n                  ok: false,\n                  status: \"error\",\n                }));\n              }\n            },\n            onAbort: (e) => {\n              $options.onAbort?.(e);\n              if (isLatestUploadRequest()) {\n                setStatus(\"aborted\");\n                setResult((prevResult) => ({\n                  ...prevResult,\n                  ok: false,\n                  status: \"aborted\",\n                }));\n              }\n            },\n            onProgress: (args) => {\n              $options.onProgress?.(args);\n              if (isLatestUploadRequest()) {\n                setStatus(\"uploading\");\n                setResult({\n                  ok: false,\n                  total: args.total,\n                  status: \"uploading\",\n                });\n              }\n            },\n            onRetry: () => {\n              $options.onRetry?.();\n              if (isLatestUploadRequest()) {\n                setStatus(\"uploading\");\n                setResult(INITIAL_UPLOAD_RESULT);\n                setError(null);\n              }\n            },\n            onPause: () => {\n              $options.onPause?.();\n              if (isLatestUploadRequest()) {\n                setStatus(\"paused\");\n                setResult((prevResult) => ({\n                  ...prevResult,\n                  ok: false,\n                  status: \"paused\",\n                }));\n              }\n            },\n            onResume: () => {\n              $options.onResume?.();\n              if (isLatestUploadRequest()) {\n                setStatus(\"uploading\");\n                setResult((prevResult) => ({\n                  ...prevResult,\n                  status: \"uploading\",\n                }));\n              }\n            },\n          },\n        });\n\n      /**\n       * If the current request is not the latest upload request, abort the request.\n       * 현재 요청이 가장 최근의 업로드 요청이 아니라면 요청을 중단합니다.\n       */\n      if (!isLatestUploadRequest()) {\n        uploadActions.abort();\n        return;\n      }\n\n      // Set the previous request abort function to the current abort function.\n      // 이전의 요청 중단 함수를 현재의 요청 중단 함수로 설정합니다.\n      prevReqAbortRef.current = uploadActions;\n\n      const uploadResult = await uploadResultPromise;\n\n      /**\n       * If the current request is not the latest upload request, do not update the result status.\n       * 현재 요청이 가장 최근의 업로드 요청이 아니라면 결과 상태 업데이트를 하지 않고 반환합니다.\n       */\n      if (!isLatestUploadRequest()) {\n        return;\n      }\n\n      updateUploadResult(uploadResult);\n    },\n    [url, updateUploadResult],\n  );\n\n  /**\n   * Executes the upload with error handling and optional re-throwing.\n   * 에러 핸들링 및 선택적 re-throw 기능을 포함하여 업로드를 실행합니다.\n   */\n  const uploadSafely = useCallback(\n    async (file: File) => {\n      try {\n        await upload(file);\n      } catch (e) {\n        setError(e as Error);\n        setStatus(\"error\");\n        setResult({ ...INITIAL_UPLOAD_RESULT, status: \"error\" });\n\n        const { current: $options } = optionRef;\n\n        const shouldThrow =\n          typeof $options.throwOnError === \"function\"\n            ? $options.throwOnError(e)\n            : Boolean($options.throwOnError);\n\n        if (shouldThrow) {\n          throw e;\n        }\n      }\n    },\n    [upload],\n  );\n\n  useEffect(() => {\n    return () => {\n      prevReqAbortRef.current.abort();\n    };\n  }, []);\n\n  useEffect(() => {\n    optionRef.current?.onUrlChange?.(url);\n  }, [url]);\n\n  useEffect(() => {\n    optionRef.current?.onMethodChange?.(optionRef.current.method);\n  }, [options?.method]);\n\n  return {\n    upload: uploadSafely,\n    /**\n     * Alias for upload — restarts upload after abort, error, or success.\n     * upload의 별칭 — 중단, 실패, 성공 이후 업로드를 다시 시작할 때 사용합니다.\n     */\n    retry: uploadSafely,\n    result,\n    status,\n    error,\n    abort: () => prevReqAbortRef.current.abort(),\n    pause: () => prevReqAbortRef.current.pause(),\n    resume: () => prevReqAbortRef.current.resume(),\n  };\n}\n"],"names":["useState","useRef","useCallback","useEffect"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { UploadOptions, UploadMethod as UploadMethod$1, UploadResult, UploadStatus } from '@universal-uploader/core';
+
+/**
+ * Configuration options for the React hook.
+ * React 훅을 위한 구성 옵션입니다.
+ */
+interface UploadHookOptions extends UploadOptions {
+    /** Callback when the target URL changes. / URL이 변경될 때 호출되는 콜백. */
+    onUrlChange?: (url: string) => void;
+    /** Callback when the upload method changes. / 업로드 방식이 변경될 때 호출되는 콜백. */
+    onMethodChange?: (method: UploadOptions["method"]) => void;
+}
+type UploadMethod = UploadMethod$1;
+
+interface UseUniversalUploadArgs {
+    url: string;
+    options?: UploadHookOptions;
+}
+/**
+ * A custom React hook for handling universal file uploads with streaming support and fallbacks.
+ * 스트리밍 지원 및 폴백 기능을 갖춘 범용 파일 업로드를 처리하기 위한 커스텀 React 훅입니다.
+ */
+declare function useUniversalUpload({ url, options, }: UseUniversalUploadArgs): {
+    upload: (file: File) => Promise<void>;
+    /**
+     * Alias for upload — restarts upload after abort, error, or success.
+     * upload의 별칭 — 중단, 실패, 성공 이후 업로드를 다시 시작할 때 사용합니다.
+     */
+    retry: (file: File) => Promise<void>;
+    result: UploadResult;
+    status: UploadStatus;
+    error: Error | null;
+    abort: () => void;
+    pause: () => void;
+    resume: () => void;
+};
+
+export { useUniversalUpload };
+export type { UploadHookOptions, UploadMethod };

package/dist/index.js

@@ -0,0 +1,235 @@
+import uploadCore from '@universal-uploader/core';
+import { useState, useRef, useCallback, useEffect } from 'react';
+
+const INITIAL_UPLOAD_RESULT = {
+    ok: false,
+    total: 0,
+    message: undefined,
+    status: "idle",
+};
+const FALLBACK_UPLOAD_OPTIONS = {};
+/**
+ * A custom React hook for handling universal file uploads with streaming support and fallbacks.
+ * 스트리밍 지원 및 폴백 기능을 갖춘 범용 파일 업로드를 처리하기 위한 커스텀 React 훅입니다.
+ */
+function useUniversalUpload({ url, options, }) {
+    const [status, setStatus] = useState("idle");
+    const [error, setError] = useState(null);
+    const [result, setResult] = useState(INITIAL_UPLOAD_RESULT);
+    /**
+     * The previous request abort function.
+     * 이전의 요청 중단 함수입니다.
+     */
+    const prevReqAbortRef = useRef({
+        abort: () => null,
+        refresh: () => null,
+        pause: () => null,
+        resume: () => null,
+    });
+    /**
+     * The latest upload request ID.
+     * 가장 최근의 업로드 요청 ID입니다.
+     */
+    const latestUploadRequestIdRef = useRef(0);
+    /**
+     * The options object.
+     * deps에 포함되지 않는 옵션 객체입니다.
+     */
+    const optionRef = useRef(options ?? FALLBACK_UPLOAD_OPTIONS);
+    // eslint-disable-next-line react-hooks/refs
+    optionRef.current = options ?? FALLBACK_UPLOAD_OPTIONS;
+    /**
+     * Updates the upload result and status state.
+     * 업로드 결과 및 상태 스테이트를 업데이트합니다.
+     */
+    const updateUploadResult = useCallback((uploadResult) => {
+        setResult(uploadResult);
+        setStatus(uploadResult.status);
+        if (uploadResult.status === "error") {
+            setError((prevError) => prevError ?? new Error(uploadResult.message || "Upload failed"));
+        }
+    }, []);
+    /**
+     * Core upload logic that manages request lifecycle and status updates.
+     * 요청 수명 주기 및 상태 업데이트를 관리하는 핵심 업로드 로직입니다.
+     */
+    const upload = useCallback(async (file) => {
+        /**
+         * Increment the latest upload request ID.
+         * 가장 최근의 업로드 요청 ID를 증가시킵니다.
+         *
+         * Set the latest upload request ID to the current value.
+         * 가장 최근의 업로드 요청 ID를 현재 값으로 설정합니다.
+         *
+         * Check if the current request is the latest upload request.
+         * 현재 요청이 가장 최근의 업로드 요청인지 확인합니다.
+         */
+        latestUploadRequestIdRef.current += 1;
+        const latestUploadRequestId = latestUploadRequestIdRef.current;
+        const isLatestUploadRequest = () => latestUploadRequestIdRef.current === latestUploadRequestId;
+        /**
+         * If the previous request is still in progress, abort it.
+         * 이전의 요청이 아직 진행 중이라면 중단합니다.
+         */
+        prevReqAbortRef.current.abort();
+        /**
+         * Reset external progress UI before a new upload starts.
+         * 새 업로드가 시작되기 전에 외부 progress UI를 초기화합니다.
+         */
+        optionRef.current?.onProgress?.({ loaded: 0, total: 0, percentage: 0 });
+        setStatus("uploading");
+        setError(null);
+        setResult(INITIAL_UPLOAD_RESULT);
+        const { current: $options } = optionRef;
+        const { result: uploadResultPromise, actions: uploadActions } = await uploadCore({
+            url,
+            file,
+            options: {
+                ...$options,
+                onComplete: () => {
+                    $options.onComplete?.();
+                    if (isLatestUploadRequest()) {
+                        setStatus("success");
+                        setResult((prevResult) => ({
+                            ...prevResult,
+                            ok: true,
+                            status: "success",
+                        }));
+                    }
+                },
+                onError: (e) => {
+                    $options.onError?.(e);
+                    if (isLatestUploadRequest()) {
+                        setError(e);
+                        setStatus("error");
+                        setResult((prevResult) => ({
+                            ...prevResult,
+                            ok: false,
+                            status: "error",
+                        }));
+                    }
+                },
+                onAbort: (e) => {
+                    $options.onAbort?.(e);
+                    if (isLatestUploadRequest()) {
+                        setStatus("aborted");
+                        setResult((prevResult) => ({
+                            ...prevResult,
+                            ok: false,
+                            status: "aborted",
+                        }));
+                    }
+                },
+                onProgress: (args) => {
+                    $options.onProgress?.(args);
+                    if (isLatestUploadRequest()) {
+                        setStatus("uploading");
+                        setResult({
+                            ok: false,
+                            total: args.total,
+                            status: "uploading",
+                        });
+                    }
+                },
+                onRetry: () => {
+                    $options.onRetry?.();
+                    if (isLatestUploadRequest()) {
+                        setStatus("uploading");
+                        setResult(INITIAL_UPLOAD_RESULT);
+                        setError(null);
+                    }
+                },
+                onPause: () => {
+                    $options.onPause?.();
+                    if (isLatestUploadRequest()) {
+                        setStatus("paused");
+                        setResult((prevResult) => ({
+                            ...prevResult,
+                            ok: false,
+                            status: "paused",
+                        }));
+                    }
+                },
+                onResume: () => {
+                    $options.onResume?.();
+                    if (isLatestUploadRequest()) {
+                        setStatus("uploading");
+                        setResult((prevResult) => ({
+                            ...prevResult,
+                            status: "uploading",
+                        }));
+                    }
+                },
+            },
+        });
+        /**
+         * If the current request is not the latest upload request, abort the request.
+         * 현재 요청이 가장 최근의 업로드 요청이 아니라면 요청을 중단합니다.
+         */
+        if (!isLatestUploadRequest()) {
+            uploadActions.abort();
+            return;
+        }
+        // Set the previous request abort function to the current abort function.
+        // 이전의 요청 중단 함수를 현재의 요청 중단 함수로 설정합니다.
+        prevReqAbortRef.current = uploadActions;
+        const uploadResult = await uploadResultPromise;
+        /**
+         * If the current request is not the latest upload request, do not update the result status.
+         * 현재 요청이 가장 최근의 업로드 요청이 아니라면 결과 상태 업데이트를 하지 않고 반환합니다.
+         */
+        if (!isLatestUploadRequest()) {
+            return;
+        }
+        updateUploadResult(uploadResult);
+    }, [url, updateUploadResult]);
+    /**
+     * Executes the upload with error handling and optional re-throwing.
+     * 에러 핸들링 및 선택적 re-throw 기능을 포함하여 업로드를 실행합니다.
+     */
+    const uploadSafely = useCallback(async (file) => {
+        try {
+            await upload(file);
+        }
+        catch (e) {
+            setError(e);
+            setStatus("error");
+            setResult({ ...INITIAL_UPLOAD_RESULT, status: "error" });
+            const { current: $options } = optionRef;
+            const shouldThrow = typeof $options.throwOnError === "function"
+                ? $options.throwOnError(e)
+                : Boolean($options.throwOnError);
+            if (shouldThrow) {
+                throw e;
+            }
+        }
+    }, [upload]);
+    useEffect(() => {
+        return () => {
+            prevReqAbortRef.current.abort();
+        };
+    }, []);
+    useEffect(() => {
+        optionRef.current?.onUrlChange?.(url);
+    }, [url]);
+    useEffect(() => {
+        optionRef.current?.onMethodChange?.(optionRef.current.method);
+    }, [options?.method]);
+    return {
+        upload: uploadSafely,
+        /**
+         * Alias for upload — restarts upload after abort, error, or success.
+         * upload의 별칭 — 중단, 실패, 성공 이후 업로드를 다시 시작할 때 사용합니다.
+         */
+        retry: uploadSafely,
+        result,
+        status,
+        error,
+        abort: () => prevReqAbortRef.current.abort(),
+        pause: () => prevReqAbortRef.current.pause(),
+        resume: () => prevReqAbortRef.current.resume(),
+    };
+}
+
+export { useUniversalUpload };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/useUniversalUpload.tsx"],"sourcesContent":["import uploadCore, {\n  UploadResult,\n  UploadStatus,\n  UploadActions,\n} from \"@universal-uploader/core\";\nimport { UploadHookOptions } from \"./types\";\nimport { useCallback, useEffect, useRef, useState } from \"react\";\n\nconst INITIAL_UPLOAD_RESULT: Readonly<UploadResult> = {\n  ok: false,\n  total: 0,\n  message: undefined,\n  status: \"idle\",\n};\n\nconst FALLBACK_UPLOAD_OPTIONS: Readonly<UploadHookOptions> = {};\n\ninterface UseUniversalUploadArgs {\n  url: string;\n  options?: UploadHookOptions;\n}\n\n/**\n * A custom React hook for handling universal file uploads with streaming support and fallbacks.\n * 스트리밍 지원 및 폴백 기능을 갖춘 범용 파일 업로드를 처리하기 위한 커스텀 React 훅입니다.\n */\nexport default function useUniversalUpload({\n  url,\n  options,\n}: UseUniversalUploadArgs) {\n  const [status, setStatus] = useState<UploadStatus>(\"idle\");\n  const [error, setError] = useState<Error | null>(null);\n  const [result, setResult] = useState<UploadResult>(INITIAL_UPLOAD_RESULT);\n\n  /**\n   * The previous request abort function.\n   * 이전의 요청 중단 함수입니다.\n   */\n  const prevReqAbortRef = useRef<UploadActions>({\n    abort: () => null,\n    refresh: () => null,\n    pause: () => null,\n    resume: () => null,\n  });\n\n  /**\n   * The latest upload request ID.\n   * 가장 최근의 업로드 요청 ID입니다.\n   */\n  const latestUploadRequestIdRef = useRef(0);\n\n  /**\n   * The options object.\n   * deps에 포함되지 않는 옵션 객체입니다.\n   */\n  const optionRef = useRef<UploadHookOptions>(\n    options ?? FALLBACK_UPLOAD_OPTIONS,\n  );\n  // eslint-disable-next-line react-hooks/refs\n  optionRef.current = options ?? FALLBACK_UPLOAD_OPTIONS;\n\n  /**\n   * Updates the upload result and status state.\n   * 업로드 결과 및 상태 스테이트를 업데이트합니다.\n   */\n  const updateUploadResult = useCallback((uploadResult: UploadResult) => {\n    setResult(uploadResult);\n    setStatus(uploadResult.status);\n\n    if (uploadResult.status === \"error\") {\n      setError(\n        (prevError) =>\n          prevError ?? new Error(uploadResult.message || \"Upload failed\"),\n      );\n    }\n  }, []);\n\n  /**\n   * Core upload logic that manages request lifecycle and status updates.\n   * 요청 수명 주기 및 상태 업데이트를 관리하는 핵심 업로드 로직입니다.\n   */\n  const upload = useCallback(\n    async (file: File) => {\n      /**\n       * Increment the latest upload request ID.\n       * 가장 최근의 업로드 요청 ID를 증가시킵니다.\n       *\n       * Set the latest upload request ID to the current value.\n       * 가장 최근의 업로드 요청 ID를 현재 값으로 설정합니다.\n       *\n       * Check if the current request is the latest upload request.\n       * 현재 요청이 가장 최근의 업로드 요청인지 확인합니다.\n       */\n      latestUploadRequestIdRef.current += 1;\n      const latestUploadRequestId = latestUploadRequestIdRef.current;\n      const isLatestUploadRequest = () =>\n        latestUploadRequestIdRef.current === latestUploadRequestId;\n\n      /**\n       * If the previous request is still in progress, abort it.\n       * 이전의 요청이 아직 진행 중이라면 중단합니다.\n       */\n      prevReqAbortRef.current.abort();\n\n      /**\n       * Reset external progress UI before a new upload starts.\n       * 새 업로드가 시작되기 전에 외부 progress UI를 초기화합니다.\n       */\n      optionRef.current?.onProgress?.({ loaded: 0, total: 0, percentage: 0 });\n\n      setStatus(\"uploading\");\n      setError(null);\n      setResult(INITIAL_UPLOAD_RESULT);\n\n      const { current: $options } = optionRef;\n\n      const { result: uploadResultPromise, actions: uploadActions } =\n        await uploadCore({\n          url,\n          file,\n          options: {\n            ...$options,\n            onComplete: () => {\n              $options.onComplete?.();\n              if (isLatestUploadRequest()) {\n                setStatus(\"success\");\n                setResult((prevResult) => ({\n                  ...prevResult,\n                  ok: true,\n                  status: \"success\",\n                }));\n              }\n            },\n            onError: (e) => {\n              $options.onError?.(e);\n              if (isLatestUploadRequest()) {\n                setError(e);\n                setStatus(\"error\");\n                setResult((prevResult) => ({\n                  ...prevResult,\n                  ok: false,\n                  status: \"error\",\n                }));\n              }\n            },\n            onAbort: (e) => {\n              $options.onAbort?.(e);\n              if (isLatestUploadRequest()) {\n                setStatus(\"aborted\");\n                setResult((prevResult) => ({\n                  ...prevResult,\n                  ok: false,\n                  status: \"aborted\",\n                }));\n              }\n            },\n            onProgress: (args) => {\n              $options.onProgress?.(args);\n              if (isLatestUploadRequest()) {\n                setStatus(\"uploading\");\n                setResult({\n                  ok: false,\n                  total: args.total,\n                  status: \"uploading\",\n                });\n              }\n            },\n            onRetry: () => {\n              $options.onRetry?.();\n              if (isLatestUploadRequest()) {\n                setStatus(\"uploading\");\n                setResult(INITIAL_UPLOAD_RESULT);\n                setError(null);\n              }\n            },\n            onPause: () => {\n              $options.onPause?.();\n              if (isLatestUploadRequest()) {\n                setStatus(\"paused\");\n                setResult((prevResult) => ({\n                  ...prevResult,\n                  ok: false,\n                  status: \"paused\",\n                }));\n              }\n            },\n            onResume: () => {\n              $options.onResume?.();\n              if (isLatestUploadRequest()) {\n                setStatus(\"uploading\");\n                setResult((prevResult) => ({\n                  ...prevResult,\n                  status: \"uploading\",\n                }));\n              }\n            },\n          },\n        });\n\n      /**\n       * If the current request is not the latest upload request, abort the request.\n       * 현재 요청이 가장 최근의 업로드 요청이 아니라면 요청을 중단합니다.\n       */\n      if (!isLatestUploadRequest()) {\n        uploadActions.abort();\n        return;\n      }\n\n      // Set the previous request abort function to the current abort function.\n      // 이전의 요청 중단 함수를 현재의 요청 중단 함수로 설정합니다.\n      prevReqAbortRef.current = uploadActions;\n\n      const uploadResult = await uploadResultPromise;\n\n      /**\n       * If the current request is not the latest upload request, do not update the result status.\n       * 현재 요청이 가장 최근의 업로드 요청이 아니라면 결과 상태 업데이트를 하지 않고 반환합니다.\n       */\n      if (!isLatestUploadRequest()) {\n        return;\n      }\n\n      updateUploadResult(uploadResult);\n    },\n    [url, updateUploadResult],\n  );\n\n  /**\n   * Executes the upload with error handling and optional re-throwing.\n   * 에러 핸들링 및 선택적 re-throw 기능을 포함하여 업로드를 실행합니다.\n   */\n  const uploadSafely = useCallback(\n    async (file: File) => {\n      try {\n        await upload(file);\n      } catch (e) {\n        setError(e as Error);\n        setStatus(\"error\");\n        setResult({ ...INITIAL_UPLOAD_RESULT, status: \"error\" });\n\n        const { current: $options } = optionRef;\n\n        const shouldThrow =\n          typeof $options.throwOnError === \"function\"\n            ? $options.throwOnError(e)\n            : Boolean($options.throwOnError);\n\n        if (shouldThrow) {\n          throw e;\n        }\n      }\n    },\n    [upload],\n  );\n\n  useEffect(() => {\n    return () => {\n      prevReqAbortRef.current.abort();\n    };\n  }, []);\n\n  useEffect(() => {\n    optionRef.current?.onUrlChange?.(url);\n  }, [url]);\n\n  useEffect(() => {\n    optionRef.current?.onMethodChange?.(optionRef.current.method);\n  }, [options?.method]);\n\n  return {\n    upload: uploadSafely,\n    /**\n     * Alias for upload — restarts upload after abort, error, or success.\n     * upload의 별칭 — 중단, 실패, 성공 이후 업로드를 다시 시작할 때 사용합니다.\n     */\n    retry: uploadSafely,\n    result,\n    status,\n    error,\n    abort: () => prevReqAbortRef.current.abort(),\n    pause: () => prevReqAbortRef.current.pause(),\n    resume: () => prevReqAbortRef.current.resume(),\n  };\n}\n"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,12 @@
+import { UploadOptions, UploadMethod as UploadMethodType } from "@universal-uploader/core";
+/**
+ * Configuration options for the React hook.
+ * React 훅을 위한 구성 옵션입니다.
+ */
+export interface UploadHookOptions extends UploadOptions {
+    /** Callback when the target URL changes. / URL이 변경될 때 호출되는 콜백. */
+    onUrlChange?: (url: string) => void;
+    /** Callback when the upload method changes. / 업로드 방식이 변경될 때 호출되는 콜백. */
+    onMethodChange?: (method: UploadOptions["method"]) => void;
+}
+export type UploadMethod = UploadMethodType;

package/dist/useUniversalUpload.d.ts

@@ -0,0 +1,25 @@
+import { UploadResult, UploadStatus } from "@universal-uploader/core";
+import { UploadHookOptions } from "./types";
+interface UseUniversalUploadArgs {
+    url: string;
+    options?: UploadHookOptions;
+}
+/**
+ * A custom React hook for handling universal file uploads with streaming support and fallbacks.
+ * 스트리밍 지원 및 폴백 기능을 갖춘 범용 파일 업로드를 처리하기 위한 커스텀 React 훅입니다.
+ */
+export default function useUniversalUpload({ url, options, }: UseUniversalUploadArgs): {
+    upload: (file: File) => Promise<void>;
+    /**
+     * Alias for upload — restarts upload after abort, error, or success.
+     * upload의 별칭 — 중단, 실패, 성공 이후 업로드를 다시 시작할 때 사용합니다.
+     */
+    retry: (file: File) => Promise<void>;
+    result: UploadResult;
+    status: UploadStatus;
+    error: Error | null;
+    abort: () => void;
+    pause: () => void;
+    resume: () => void;
+};
+export {};

package/dist/useUniversalUpload.js

@@ -0,0 +1,158 @@
+import uploadCore from '@usu/core';
+import { useCallback, useEffect, useRef, useState } from 'react';
+const INITIAL_UPLOAD_RESULT = {
+    ok: false,
+    total: 0,
+    message: undefined,
+    status: 'idle',
+};
+export default function useUniversalUpload({ url, file, options }) {
+    const [status, setStatus] = useState('idle');
+    const [error, setError] = useState(null);
+    const [result, setResult] = useState(INITIAL_UPLOAD_RESULT);
+    /**
+     * The previous request abort function.
+     * 이전의 요청 중단 함수입니다.
+     */
+    const prevReqAbortRef = useRef({ abort: () => null, refresh: () => null });
+    /**
+     * The latest upload request ID.
+     * 가장 최근의 업로드 요청 ID입니다.
+     */
+    const latestUploadRequestIdRef = useRef(0);
+    /**
+     * The options object.
+     * deps에 포함되지 않는 옵션 객체입니다.
+     */
+    const optionRef = useRef(options);
+    // eslint-disable-next-line react-hooks/refs
+    optionRef.current = options;
+    const updateUploadResult = useCallback((uploadResult) => {
+        setResult(uploadResult);
+        setStatus(uploadResult.status);
+        if (uploadResult.status === 'error') {
+            setError((prevError) => prevError ?? new Error(uploadResult.message || 'Upload failed'));
+        }
+    }, []);
+    const upload = useCallback(async () => {
+        /**
+         * Increment the latest upload request ID.
+         * 가장 최근의 업로드 요청 ID를 증가시킵니다.
+         *
+         * Set the latest upload request ID to the current value.
+         * 가장 최근의 업로드 요청 ID를 현재 값으로 설정합니다.
+         *
+         * Check if the current request is the latest upload request.
+         * 현재 요청이 가장 최근의 업로드 요청인지 확인합니다.
+         */
+        latestUploadRequestIdRef.current += 1;
+        const latestUploadRequestId = latestUploadRequestIdRef.current;
+        const isLatestUploadRequest = () => latestUploadRequestIdRef.current === latestUploadRequestId;
+        /**
+         * If the previous request is still in progress, abort it.
+         * 이전의 요청이 아직 진행 중이라면 중단합니다.
+         */
+        prevReqAbortRef.current.abort();
+        setStatus('uploading');
+        setError(null);
+        setResult(INITIAL_UPLOAD_RESULT);
+        const { current: $options } = optionRef;
+        const { result: uploadResultPromise, actions: uploadActions } = await uploadCore({
+            url,
+            file,
+            options: {
+                ...$options,
+                onComplete: () => {
+                    $options.onComplete?.();
+                    if (isLatestUploadRequest()) {
+                        setStatus('success');
+                        setResult((prevResult) => ({ ...prevResult, ok: true, status: 'success' }));
+                    }
+                },
+                onError: (e) => {
+                    $options.onError?.(e);
+                    if (isLatestUploadRequest()) {
+                        setError(e);
+                        setStatus('error');
+                        setResult((prevResult) => ({ ...prevResult, ok: false, status: 'error' }));
+                    }
+                },
+                onAbort: (e) => {
+                    $options.onAbort?.(e);
+                    if (isLatestUploadRequest()) {
+                        setStatus('aborted');
+                        setResult((prevResult) => ({ ...prevResult, ok: false, status: 'aborted' }));
+                    }
+                },
+                onProgress: (args) => {
+                    $options.onProgress?.(args);
+                    if (isLatestUploadRequest()) {
+                        setStatus('uploading');
+                        setResult({ ok: false, total: args.percentage, status: 'uploading' });
+                    }
+                },
+                onRetry: () => {
+                    $options.onRetry?.();
+                    if (isLatestUploadRequest()) {
+                        setStatus('uploading');
+                        setResult(INITIAL_UPLOAD_RESULT);
+                        setError(null);
+                    }
+                },
+            },
+        });
+        /**
+         * If the current request is not the latest upload request, abort the request.
+         * 현재 요청이 가장 최근의 업로드 요청이 아니라면 요청을 중단합니다.
+         */
+        if (!isLatestUploadRequest()) {
+            uploadActions.abort();
+            return;
+        }
+        // Set the previous request abort function to the current abort function.
+        // 이전의 요청 중단 함수를 현재의 요청 중단 함수로 설정합니다.
+        prevReqAbortRef.current = uploadActions;
+        const uploadResult = await uploadResultPromise;
+        /**
+         * If the current request is not the latest upload request, do not update the result status.
+         * 현재 요청이 가장 최근의 업로드 요청이 아니라면 결과 상태 업데이트를 하지 않고 반환합니다.
+         */
+        if (!isLatestUploadRequest()) {
+            return;
+        }
+        updateUploadResult(uploadResult);
+    }, [url, file, updateUploadResult]);
+    const uploadSafely = useCallback(async () => {
+        try {
+            await upload();
+        }
+        catch (e) {
+            setError(e);
+            setStatus('error');
+            setResult({ ...INITIAL_UPLOAD_RESULT, status: 'error' });
+            const { current: $options } = optionRef;
+            const shouldThrow = typeof $options.throwOnError === 'function'
+                ? $options.throwOnError(e)
+                : Boolean($options.throwOnError);
+            if (shouldThrow) {
+                throw e;
+            }
+        }
+    }, [upload]);
+    useEffect(() => {
+        return () => {
+            prevReqAbortRef.current.abort();
+        };
+    }, []);
+    return {
+        upload: uploadSafely,
+        result,
+        status,
+        error,
+        abort: () => prevReqAbortRef.current.abort(),
+        refresh: async () => {
+            prevReqAbortRef.current.abort();
+            await uploadSafely();
+        },
+    };
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@universal-uploader/react",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "React hook wrapper for Universal Stream Uploader.",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": "^19.2.6"
+  },
+  "dependencies": {
+    "@universal-uploader/core": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jdy8739/universal-uploader.git",
+    "directory": "packages/react"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "rollup -c rollup.config.mjs",
+    "type-check": "tsc --noEmit"
+  }
+}