uploadzx/dist/index.d.ts

Browser-only TypeScript upload library with tus integration for resumable uploads

interface UploadFile {
    id: string;
    file: File;
    fileHandle?: FileSystemFileHandle;
    name: string;
    size: number;
    type: string;
}
interface UploadProgress {
    fileId: string;
    bytesUploaded: number;
    bytesTotal: number;
    percentage: number;
    bytesPerSecond: number;
}
interface UploadState {
    fileId: string;
    status: 'pending' | 'uploading' | 'paused' | 'completed' | 'error' | 'cancelled';
    progress: UploadProgress;
    error?: Error;
    tusUrl?: string;
    file: File;
}
interface UploadOptions {
    endpoint: string;
    chunkSize?: number;
    retryDelays?: number[];
    metadata?: Record<string, string>;
    headers?: Record<string, string>;
    onInit?: () => void;
}
interface UploadEvents {
    onProgress?: (progress: UploadProgress) => void;
    onStateChange?: (state: UploadState) => void;
    onComplete?: (fileId: string, tusUrl: string) => void;
    onError?: (fileId: string, error: Error) => void;
    onCancel?: (fileId: string) => void;
}
interface FilePickerOptions {
    accept?: string;
    multiple?: boolean;
    useFileSystemAccess?: boolean;
}
interface StoredFileHandle {
    id: string;
    name: string;
    size: number;
    type: string;
    handle: FileSystemFileHandle;
    lastModified: number;
    tusUploadUrl?: string;
    bytesUploaded?: number;
}

declare class FilePicker {
    private options;
    constructor(options?: FilePickerOptions);
    private generateUUID;
    pickFiles(): Promise<UploadFile[]>;
    private pickWithFileSystemAccess;
    private pickWithInputAndMockHandles;
    private createMockFileHandle;
    private pickWithInput;
}

interface TusUploaderOptions {
    previousUploadUrl?: string;
    previousBytesUploaded?: number;
    trackSpeed?: boolean;
}
declare class TusUploader {
    private uploadFile;
    private options;
    private events;
    private upload?;
    private abortController;
    private state;
    private previousUploadUrl?;
    private trackSpeed;
    private lastProgressUpdate?;
    constructor(uploadFile: UploadFile, options: UploadOptions, events?: UploadEvents, tusOptions?: TusUploaderOptions);
    start(): Promise<void>;
    pause(): Promise<void>;
    resume(): Promise<void>;
    cancel(): Promise<void>;
    getState(): UploadState;
    getCurrentUploadUrl(): string | undefined;
    canResume(): boolean;
    private updateState;
    private updateProgress;
    private startTusUpload;
}

declare class FileHandleStore {
    private dbName;
    private version;
    private storeName;
    private safariStoreName;
    private isFileSystemAccessSupported;
    private openDB;
    storeFileHandle(fileHandle: FileSystemFileHandle, id: string): Promise<void>;
    private storeNativeFileHandle;
    private storeSafariFile;
    getFileHandle(id: string): Promise<StoredFileHandle | null>;
    private getNativeFileHandle;
    private getSafariFileAsHandle;
    private createMockFileHandle;
    getAllFileHandles(): Promise<StoredFileHandle[]>;
    private getAllNativeFileHandles;
    private getAllSafariFilesAsHandles;
    removeFileHandle(id: string): Promise<void>;
    updateFileHandleProgress(id: string, tusUploadUrl: string, bytesUploaded: number): Promise<void>;
    private updateNativeFileHandleProgress;
    private updateSafariFileHandleProgress;
    verifyPermission(fileHandle: FileSystemFileHandle): Promise<boolean>;
    getFileFromHandleByID(id: string): Promise<File | null>;
    private getSafariFileByID;
    clear(): Promise<void>;
}

interface QueueOptions extends UploadOptions {
    maxConcurrent?: number;
    autoStart?: boolean;
}
declare class UploadQueue {
    private options;
    private events;
    private uploaders;
    private unfinishedUploads;
    private queue;
    private activeUploads;
    private isInitialized;
    fileHandleStore: FileHandleStore;
    constructor(options: QueueOptions, events?: UploadEvents);
    private initialize;
    getIsInitialized(): boolean;
    addFiles(files: UploadFile[], tusOptions?: TusUploaderOptions): Promise<void>;
    startQueue(): Promise<void>;
    pauseAll(): Promise<void>;
    resumeAll(): Promise<void>;
    cancelAll(): Promise<void>;
    pauseUpload(fileId: string): Promise<void>;
    resumeUpload(fileId: string): Promise<void>;
    cancelUpload(fileId: string): Promise<void>;
    clearCompletedUploads(): void;
    getUploadState(fileId: string): UploadState | null;
    getAllStates(): UploadState[];
    getQueueLength(): number;
    getActiveCount(): number;
    getUnfinishedUploads(): Promise<StoredFileHandle[]>;
    restoreUnfinishedUpload(fileHandleOrId: StoredFileHandle | string, tusOpts?: TusUploaderOptions): Promise<void>;
    private updateStoredFileHandleProgress;
    private processQueue;
    private handleStateChange;
    private handleComplete;
    private handleError;
    private removeFromQueue;
    private getUnfinishedUploadsFromStore;
    private resumeUnfinishedUpload;
}

declare global {
    interface DataTransferItem {
        getAsFileSystemHandle?(): Promise<FileSystemHandle | null>;
    }
}
declare function formatFileSize(bytes: number): string;
declare function formatUploadSpeed(bytesPerSecond: number): string;
declare function generateFileId(): string;
declare function validateFile(file: File, options?: {
    maxSize?: number;
    allowedTypes?: string[];
}): string | null;
declare function isFileSystemAccessSupported(): boolean;
declare function isSafari(): boolean;
declare function getBrowserInfo(): {
    name: string;
    version: string;
    isFileSystemAccessSupported: boolean;
};
/**
 * Extracts file handles from drag and drop DataTransferItems
 * Falls back to creating mock handles for Safari
 */
declare function getFileHandlesFromDataTransfer(dataTransfer: DataTransfer): Promise<{
    file: File;
    handle?: FileSystemFileHandle;
}[]>;
/**
 * Extracts files and their handles from a drag event
 * Automatically handles Safari fallback
 * Works with both React DragEvent and native DragEvent
 */
declare function getFilesFromDragEvent(event: {
    dataTransfer: DataTransfer | null;
}): Promise<{
    file: File;
    handle?: FileSystemFileHandle;
}[]>;
declare function debounce<T extends (...args: any[]) => any>(func: T, wait: number): (...args: Parameters<T>) => void;

interface UploadzxOptions extends QueueOptions {
    filePickerOptions?: FilePickerOptions;
    tusOptions?: TusUploaderOptions;
}
declare class Uploadzx {
    private filePicker;
    private uploadQueue;
    private tusOptions?;
    constructor(options: UploadzxOptions, events?: UploadEvents);
    getIsInitialized(): boolean;
    pickAndUploadFiles(tusOptions?: TusUploaderOptions): Promise<void>;
    pickFiles(): Promise<UploadFile[]>;
    addFiles(files: any[], tusOptions?: TusUploaderOptions): Promise<void>;
    startUploads(): Promise<void>;
    pauseAll(): Promise<void>;
    resumeAll(): Promise<void>;
    cancelAll(): Promise<void>;
    pauseUpload(fileId: string): Promise<void>;
    resumeUpload(fileId: string): Promise<void>;
    cancelUpload(fileId: string): Promise<void>;
    restoreUnfinishedUpload(fileHandleOrId: StoredFileHandle | string, tusOpts?: TusUploaderOptions): Promise<void>;
    clearCompletedUploads(): Promise<void>;
    getUploadState(fileId: string): UploadState | null;
    getAllStates(): UploadState[];
    getQueueStats(): {
        queueLength: number;
        activeCount: number;
    };
    getUnfinishedUploads(): Promise<StoredFileHandle[]>;
}

export { FileHandleStore, FilePicker, type FilePickerOptions, type QueueOptions, type StoredFileHandle, TusUploader, type UploadEvents, type UploadFile, type UploadOptions, type UploadProgress, UploadQueue, type UploadState, Uploadzx, type UploadzxOptions, debounce, Uploadzx as default, formatFileSize, formatUploadSpeed, generateFileId, getBrowserInfo, getFileHandlesFromDataTransfer, getFilesFromDragEvent, isFileSystemAccessSupported, isSafari, validateFile };