메인 콘텐츠로 건너뛰기

TypeScript 타입

Dropup에서 내보내는 모든 타입입니다.

타입 임포트​

import type {
  DropupFile,
  DropupState,
  DropupActions,
  DropupError,
  UseDropupOptions,
  UseDropupReturn,
  FileStatus,
  DropupStatus,
  ValidationRule,
  ValidationError,
  UploadConfig,
  CustomUploader,
  UploadOptions,
  UploadResult,
} from '@samithahansaka/dropup';

코어 타입​

DropupFile​

업로드 큐의 파일을 나타냅니다.

interface DropupFile {
  /** 고유 식별자 */
  id: string;

  /** 원본 브라우저 File 객체 */
  file: File;

  /** 파일 이름 */
  name: string;

  /** 파일 크기 (바이트) */
  size: number;

  /** MIME 타입 */
  type: string;

  /** 현재 업로드 상태 */
  status: FileStatus;

  /** 업로드 진행률 0-100 */
  progress: number;

  /** 이미지용 미리보기 URL (Object URL) */
  preview?: string;

  /** 업로드 성공 후 URL */
  uploadedUrl?: string;

  /** 원본 서버 응답 */
  response?: unknown;

  /** 실패 시 오류 세부 정보 */
  error?: DropupError;

  /** 커스텀 메타데이터 */
  meta?: Record<string, unknown>;
}

FileStatus​

가능한 파일 상태 값.

type FileStatus = 'idle' | 'uploading' | 'complete' | 'error' | 'paused';

DropupState​

드롭 영역의 현재 상태.

interface DropupState {
  /** 파일이 드래그 중인지 */
  isDragging: boolean;

  /** 드래그된 파일이 유효성 검사 통과 */
  isDragAccept: boolean;

  /** 드래그된 파일이 유효성 검사 실패 */
  isDragReject: boolean;

  /** 현재 업로드 중인 파일 있음 */
  isUploading: boolean;

  /** 모든 파일의 평균 진행률 (0-100) */
  progress: number;

  /** 전체 상태 */
  status: DropupStatus;
}

DropupStatus​

전체 업로드 상태.

type DropupStatus = 'idle' | 'uploading' | 'complete' | 'error';

DropupActions​

업로더를 제어하기 위한 사용 가능한 액션.

interface DropupActions {
  /** 파일 업로드 시작 */
  upload: (fileIds?: string[]) => void;

  /** 업로드 취소 */
  cancel: (fileId?: string) => void;

  /** 파일 제거 */
  remove: (fileId: string) => void;

  /** 모든 파일 제거 및 상태 초기화 */
  reset: () => void;

  /** 실패한 업로드 재시도 */
  retry: (fileIds?: string[]) => void;

  /** 프로그래밍 방식으로 파일 추가 */
  addFiles: (files: File[] | FileList) => void;

  /** 파일 메타데이터 업데이트 */
  updateFileMeta: (fileId: string, meta: Record<string, unknown>) => void;
}

DropupError​

실패한 업로드의 오류 객체.

interface DropupError {
  /** 오류 코드 */
  code: string;

  /** 사람이 읽을 수 있는 메시지 */
  message: string;

  /** 사용 가능한 경우 원본 오류 */
  cause?: Error;
}

옵션 타입​

UseDropupOptions​

훅의 설정 옵션.

interface UseDropupOptions {
  // 유효성 검사
  accept?: string | string[];
  maxSize?: number;
  minSize?: number;
  maxFiles?: number;
  maxWidth?: number;
  maxHeight?: number;
  minWidth?: number;
  minHeight?: number;
  customRules?: ValidationRule[];

  // 동작
  multiple?: boolean;
  disabled?: boolean;
  autoUpload?: boolean;
  generatePreviews?: boolean;

  // 업로드
  upload?: UploadConfig | CustomUploader;

  // 콜백
  onFilesAdded?: (files: DropupFile[]) => void;
  onFileRemoved?: (file: DropupFile) => void;
  onValidationError?: (errors: ValidationError[]) => void;
  onUploadStart?: (file: DropupFile) => void;
  onUploadProgress?: (file: DropupFile, progress: number) => void;
  onUploadComplete?: (file: DropupFile, response: unknown) => void;
  onUploadError?: (file: DropupFile, error: DropupError) => void;
  onAllComplete?: (files: DropupFile[]) => void;
}

UploadConfig​

URL 기반 업로드 설정.

interface UploadConfig {
  /** 업로드 엔드포인트 URL */
  url: string;

  /** HTTP 메서드 */
  method?: 'POST' | 'PUT' | 'PATCH';

  /** 요청 헤더 */
  headers?: Record<string, string>;

  /** 파일의 폼 필드 이름 */
  fieldName?: string;

  /** 자격 증명/쿠키 포함 */
  withCredentials?: boolean;

  /** 요청 타임아웃 (밀리초) */
  timeout?: number;

  /** 추가 폼 데이터 */
  data?: Record<string, unknown>;
}

CustomUploader​

커스텀 업로드 함수 타입.

type CustomUploader = (
  file: DropupFile,
  options: UploadOptions
) => Promise<UploadResult>;

UploadOptions​

커스텀 업로더에 전달되는 옵션.

interface UploadOptions {
  /** 취소용 Abort 시그널 */
  signal: AbortSignal;

  /** 진행률 콜백 */
  onProgress: (progress: number) => void;
}

UploadResult​

업로드에서 반환되는 결과.

interface UploadResult {
  /** 업로드된 파일 URL */
  url?: string;

  /** 원본 서버 응답 */
  response?: unknown;
}

유효성 검사 타입​

ValidationRule​

커스텀 유효성 검사 함수.

type ValidationRule = (file: File) =>
  | boolean
  | string
  | Promise<boolean | string>;

반환 값:

  • true - 유효성 검사 통과
  • false - 유효성 검사 실패 (일반 오류)
  • string - 커스텀 메시지와 함께 유효성 검사 실패

ValidationError​

파일의 유효성 검사 오류.

interface ValidationError {
  /** 유효성 검사에 실패한 파일 */
  file: File;

  /** 오류 메시지 배열 */
  errors: string[];
}

반환 타입​

UseDropupReturn​

훅의 전체 반환 타입.

interface UseDropupReturn {
  /** 파일 배열 */
  files: DropupFile[];

  /** 현재 상태 */
  state: DropupState;

  /** 사용 가능한 액션 */
  actions: DropupActions;

  /** 드롭 영역용 Props 게터 */
  getDropProps: <E extends HTMLElement = HTMLDivElement>(
    props?: React.HTMLAttributes<E>
  ) => DropZoneProps<E>;

  /** input 요소용 Props 게터 */
  getInputProps: (
    props?: React.InputHTMLAttributes<HTMLInputElement>
  ) => InputProps;

  /** 프로그래밍 방식으로 파일 대화상자 열기 */
  openFileDialog: () => void;
}

DropZoneProps​

getDropProps가 반환하는 Props.

interface DropZoneProps<E extends HTMLElement>
  extends React.HTMLAttributes<E> {
  onDragEnter: React.DragEventHandler<E>;
  onDragOver: React.DragEventHandler<E>;
  onDragLeave: React.DragEventHandler<E>;
  onDrop: React.DragEventHandler<E>;
  onClick: React.MouseEventHandler<E>;
  role: string;
  tabIndex: number;
}

InputProps​

getInputProps가 반환하는 Props.

interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
  type: 'file';
  accept?: string;
  multiple?: boolean;
  onChange: React.ChangeEventHandler<HTMLInputElement>;
  style: React.CSSProperties;
}

클라우드 타입​

S3UploaderConfig​

S3 업로더 설정.

interface S3UploaderConfig {
  getPresignedUrl: (file: DropupFile) => Promise<PresignedUrlResponse>;
}

interface PresignedUrlResponse {
  url: string;
  fields?: Record<string, string>;
}

GCSUploaderConfig​

Google Cloud Storage 업로더 설정.

interface GCSUploaderConfig {
  getSignedUrl: (file: DropupFile) => Promise<SignedUrlResponse>;
}

interface SignedUrlResponse {
  url: string;
  headers?: Record<string, string>;
}

AzureUploaderConfig​

Azure Blob Storage 업로더 설정.

interface AzureUploaderConfig {
  getSasUrl: (file: DropupFile) => Promise<SasUrlResponse>;
}

interface SasUrlResponse {
  url: string;
  headers?: Record<string, string>;
}

청크 업로드 타입​

ChunkedUploaderConfig​

청크 업로드 설정.

interface ChunkedUploaderConfig {
  /** 업로드 엔드포인트 URL */
  url: string;

  /** 청크 크기 (바이트, 기본값: 5MB) */
  chunkSize?: number;

  /** 최대 동시 청크 수 */
  concurrency?: number;

  /** 요청 헤더 */
  headers?: Record<string, string>;
}

이미지 처리 타입​

CompressOptions​

이미지 압축 옵션.

interface CompressOptions {
  /** 최대 너비 */
  maxWidth?: number;

  /** 최대 높이 */
  maxHeight?: number;

  /** 품질 0-1 (기본값: 0.8) */
  quality?: number;

  /** 출력 형식 */
  type?: 'image/jpeg' | 'image/png' | 'image/webp';
}

타입 유틸리티​

제네릭 타입​

// 파일 상태 추출
type IdleFile = DropupFile & { status: 'idle' };
type UploadingFile = DropupFile & { status: 'uploading' };
type CompletedFile = DropupFile & { status: 'complete' };
type FailedFile = DropupFile & { status: 'error' };

// 타입 가드 함수
function isIdle(file: DropupFile): file is IdleFile {
  return file.status === 'idle';
}

function isUploading(file: DropupFile): file is UploadingFile {
  return file.status === 'uploading';
}

function isComplete(file: DropupFile): file is CompletedFile {
  return file.status === 'complete';
}

function isFailed(file: DropupFile): file is FailedFile {
  return file.status === 'error';
}

타입 가드와 함께 사용​

const { files } = useDropup();

// 타입 안전성으로 필터링
const uploadingFiles = files.filter(isUploading);
// uploadingFiles는 UploadingFile[]

const completedFiles = files.filter(isComplete);
// completedFiles는 CompletedFile[]