uploader-sdk 1.0.0

package/dist/index.js

@@ -0,0 +1,407 @@
+const DEFAULT_DB_NAME = 'upload_sdk_db';
+const DEFAULT_STORE_NAME = 'files';
+export function createUploadError(code, message, options) {
+    const err = new Error(message);
+    err.code = code;
+    err.retriable = options?.retriable;
+    err.cause = options?.cause;
+    return err;
+}
+export class UploadSDK {
+    constructor(config) {
+        this.adapters = new Map();
+        this.allowExtensions = null;
+        this.pausedFileIds = new Set();
+        this.canceledFileIds = new Set();
+        this.activeControllers = new Map();
+        this.dbName = config?.dbName ?? DEFAULT_DB_NAME;
+        this.storeName = config?.storeName ?? DEFAULT_STORE_NAME;
+    }
+    registerAdapter(name, adapter) {
+        this.adapters.set(name, adapter);
+    }
+    setExtensionRules(rules) {
+        this.allowExtensions = rules.allowExtensions
+            ? new Set(rules.allowExtensions.map((ext) => this.normalizeExtension(ext)))
+            : null;
+    }
+    pauseUpload(fileId) {
+        this.pausedFileIds.add(fileId);
+        const controller = this.activeControllers.get(fileId);
+        if (controller) {
+            controller.abort();
+        }
+    }
+    resumeUpload(fileId) {
+        this.pausedFileIds.delete(fileId);
+    }
+    async cancelUpload(fileId) {
+        this.canceledFileIds.add(fileId);
+        this.pausedFileIds.delete(fileId);
+        const controller = this.activeControllers.get(fileId);
+        if (controller) {
+            controller.abort();
+        }
+        await this.cleanupAllAdapterSessions(fileId, 'canceled');
+        await this.removeStoredFileById(fileId);
+    }
+    async saveFilesToIndexedDB(files) {
+        const saved = [];
+        const rejected = [];
+        const recordsToWrite = [];
+        for (const file of files) {
+            if (!this.isFileAllowed(file.name)) {
+                rejected.push(file.name);
+                continue;
+            }
+            const data = await file.arrayBuffer();
+            const id = this.buildFileId(file);
+            const record = {
+                id,
+                name: file.name,
+                type: file.type,
+                lastModified: file.lastModified,
+                data,
+                size: file.size,
+            };
+            recordsToWrite.push(record);
+            saved.push(file.name);
+        }
+        if (!recordsToWrite.length) {
+            return { saved, rejected };
+        }
+        const db = await this.openDB();
+        const tx = db.transaction(this.storeName, 'readwrite');
+        const store = tx.objectStore(this.storeName);
+        for (const record of recordsToWrite) {
+            await this.requestToPromise(store.put(record));
+        }
+        await this.txComplete(tx);
+        db.close();
+        return { saved, rejected };
+    }
+    async listStoredFiles() {
+        const db = await this.openDB();
+        const tx = db.transaction(this.storeName, 'readonly');
+        const store = tx.objectStore(this.storeName);
+        const records = (await this.requestToPromise(store.getAll()));
+        await this.txComplete(tx);
+        db.close();
+        return records.map((r) => ({ id: r.id, name: r.name, size: r.size, type: r.type }));
+    }
+    async clearStoredFiles() {
+        const db = await this.openDB();
+        const tx = db.transaction(this.storeName, 'readwrite');
+        const store = tx.objectStore(this.storeName);
+        await this.requestToPromise(store.clear());
+        await this.txComplete(tx);
+        db.close();
+    }
+    async uploadFiles(adapterName, options = {}) {
+        const adapter = this.adapters.get(adapterName);
+        if (!adapter) {
+            throw createUploadError('ADAPTER_NOT_FOUND', `Adapter not found: ${adapterName}`);
+        }
+        const db = await this.openDB();
+        const tx = db.transaction(this.storeName, 'readonly');
+        const store = tx.objectStore(this.storeName);
+        const records = (await this.requestToPromise(store.getAll()));
+        await this.txComplete(tx);
+        db.close();
+        const files = await this.prepareUploadItems(records, options);
+        await this.uploadWithConcurrency(files, adapter, options);
+    }
+    async uploadSelectedFiles(adapterName, fileIds, options = {}) {
+        const adapter = this.adapters.get(adapterName);
+        if (!adapter) {
+            throw createUploadError('ADAPTER_NOT_FOUND', `Adapter not found: ${adapterName}`);
+        }
+        if (!fileIds.length) {
+            return;
+        }
+        const idSet = new Set(fileIds);
+        const db = await this.openDB();
+        const tx = db.transaction(this.storeName, 'readonly');
+        const store = tx.objectStore(this.storeName);
+        const records = (await this.requestToPromise(store.getAll()));
+        await this.txComplete(tx);
+        db.close();
+        const selectedRecords = records.filter((record) => idSet.has(record.id));
+        const files = await this.prepareUploadItems(selectedRecords, options);
+        await this.uploadWithConcurrency(files, adapter, options);
+    }
+    async uploadWithConcurrency(items, adapter, options) {
+        const parallel = Math.max(1, options.parallel ?? 3);
+        const retry = Math.max(0, options.retry ?? 2);
+        const retryDelayMs = Math.max(0, options.retryDelayMs ?? 300);
+        let nextIndex = 0;
+        const worker = async () => {
+            while (true) {
+                const current = nextIndex;
+                nextIndex += 1;
+                if (current >= items.length) {
+                    return;
+                }
+                const item = items[current];
+                if (this.canceledFileIds.has(item.id)) {
+                    continue;
+                }
+                const canProceed = await this.waitIfPaused(item.id);
+                if (!canProceed || this.canceledFileIds.has(item.id)) {
+                    continue;
+                }
+                await this.uploadSingleWithRetry(item.id, item.file, adapter, retry, retryDelayMs, options);
+                await this.removeStoredFileById(item.id);
+                this.canceledFileIds.delete(item.id);
+            }
+        };
+        const workers = Array.from({ length: Math.min(parallel, items.length) }, () => worker());
+        await Promise.all(workers);
+    }
+    async uploadSingleWithRetry(fileId, file, adapter, retry, retryDelayMs, options) {
+        let attempts = 0;
+        while (attempts <= retry) {
+            if (this.canceledFileIds.has(fileId)) {
+                return;
+            }
+            const canProceed = await this.waitIfPaused(fileId);
+            if (!canProceed) {
+                return;
+            }
+            const controller = new AbortController();
+            this.activeControllers.set(fileId, controller);
+            try {
+                // Mark file as started before network progress events arrive.
+                options.onProgress?.(0, file.name, { fileId });
+                let reportedByAdapter = false;
+                const reportProgress = (progress) => {
+                    reportedByAdapter = true;
+                    const bounded = Math.max(0, Math.min(100, progress));
+                    options.onProgress?.(bounded, file.name, { fileId });
+                };
+                const adapterResult = await adapter.uploadFile(file, {
+                    fileId,
+                    fileName: file.name,
+                    fileSize: file.size,
+                    fileType: file.type,
+                    signal: controller.signal,
+                    attempt: attempts,
+                    onProgress: reportProgress,
+                });
+                const normalized = typeof adapterResult === 'string'
+                    ? { url: adapterResult }
+                    : {
+                        url: adapterResult.url,
+                        assetId: adapterResult.assetId,
+                        key: adapterResult.key,
+                        verified: adapterResult.verified,
+                    };
+                if (!reportedByAdapter) {
+                    options.onProgress?.(100, file.name, { fileId });
+                }
+                else {
+                    // Ensure final state is always 100 even if adapter reports a lower terminal value.
+                    options.onProgress?.(100, file.name, { fileId });
+                }
+                options.onComplete?.(file.name, normalized.url, { fileId });
+                options.onCompleteDetailed?.(file.name, normalized, { fileId });
+                return;
+            }
+            catch (error) {
+                const aborted = this.isAbortError(error);
+                const pausedAbort = this.pausedFileIds.has(fileId) && this.isAbortError(error);
+                if (pausedAbort) {
+                    // Do not consume retries for deliberate pause interruption.
+                    continue;
+                }
+                const canceledAbort = this.canceledFileIds.has(fileId) && aborted;
+                if (canceledAbort) {
+                    // Cancellation is user-intentional; do not retry or report as error.
+                    return;
+                }
+                attempts += 1;
+                const err = this.normalizeUploadError(error);
+                const willRetry = attempts <= retry;
+                if (willRetry) {
+                    options.onRetry?.(err, file.name, {
+                        attempt: attempts,
+                        maxRetries: retry,
+                        fileId,
+                    });
+                }
+                else {
+                    await this.cleanupAdapterSession(adapter, fileId, 'final-failure');
+                    options.onFinalError?.(err, file.name, { fileId });
+                    options.onError?.(err, file.name, { fileId });
+                    throw err;
+                }
+                await this.sleep(retryDelayMs);
+            }
+            finally {
+                this.activeControllers.delete(fileId);
+            }
+        }
+    }
+    async waitIfPaused(fileId) {
+        while (this.pausedFileIds.has(fileId)) {
+            if (this.canceledFileIds.has(fileId)) {
+                return false;
+            }
+            await this.sleep(150);
+        }
+        return true;
+    }
+    async prepareUploadItems(records, options) {
+        const items = [];
+        for (const record of records) {
+            items.push({
+                id: record.id,
+                file: new File([record.data], record.name, {
+                    type: record.type,
+                    lastModified: record.lastModified,
+                }),
+            });
+        }
+        return items;
+    }
+    async removeStoredFileById(id) {
+        const db = await this.openDB();
+        const tx = db.transaction(this.storeName, 'readwrite');
+        const store = tx.objectStore(this.storeName);
+        await this.requestToPromise(store.delete(id));
+        await this.txComplete(tx);
+        db.close();
+    }
+    isFileAllowed(fileName) {
+        const ext = this.extractExtension(fileName);
+        if (!ext) {
+            return this.allowExtensions === null;
+        }
+        if (this.allowExtensions && !this.allowExtensions.has(ext)) {
+            return false;
+        }
+        return true;
+    }
+    extractExtension(fileName) {
+        const idx = fileName.lastIndexOf('.');
+        if (idx < 0 || idx === fileName.length - 1) {
+            return null;
+        }
+        return this.normalizeExtension(fileName.slice(idx + 1));
+    }
+    normalizeExtension(ext) {
+        return ext.replace(/^\./, '').trim().toLowerCase();
+    }
+    buildFileId(_file) {
+        const uuid = globalThis.crypto?.randomUUID?.();
+        if (uuid) {
+            return uuid;
+        }
+        return `f_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+    }
+    openDB() {
+        return new Promise((resolve, reject) => {
+            const req = indexedDB.open(this.dbName, 1);
+            req.onupgradeneeded = () => {
+                const db = req.result;
+                if (!db.objectStoreNames.contains(this.storeName)) {
+                    db.createObjectStore(this.storeName, { keyPath: 'id' });
+                }
+            };
+            req.onsuccess = () => resolve(req.result);
+            req.onerror = () => reject(req.error ?? new Error('Failed to open IndexedDB'));
+        });
+    }
+    requestToPromise(request) {
+        return new Promise((resolve, reject) => {
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error ?? new Error('IndexedDB request failed'));
+        });
+    }
+    txComplete(tx) {
+        return new Promise((resolve, reject) => {
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error ?? new Error('IndexedDB transaction failed'));
+            tx.onabort = () => reject(tx.error ?? new Error('IndexedDB transaction aborted'));
+        });
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    isAbortError(error) {
+        if (!error || typeof error !== 'object') {
+            return false;
+        }
+        const maybe = error;
+        return maybe.name === 'AbortError';
+    }
+    normalizeUploadError(error) {
+        if (error && typeof error === 'object' && 'code' in error) {
+            return error;
+        }
+        if (this.isAbortError(error)) {
+            return createUploadError('UPLOAD_ABORTED', 'Upload aborted', {
+                retriable: false,
+                cause: error,
+            });
+        }
+        const message = error && typeof error === 'object' && 'message' in error
+            ? String(error.message || 'Upload failed')
+            : 'Upload failed';
+        return createUploadError('UPLOAD_FAILED', message, {
+            retriable: true,
+            cause: error,
+        });
+    }
+    async cleanupAdapterSession(adapter, fileId, reason) {
+        if (!adapter.cleanupUploadSession) {
+            return;
+        }
+        try {
+            await adapter.cleanupUploadSession(fileId, { reason });
+        }
+        catch {
+            // Cleanup is best-effort and should not mask primary upload errors.
+        }
+    }
+    async cleanupAllAdapterSessions(fileId, reason) {
+        const tasks = [];
+        for (const adapter of this.adapters.values()) {
+            tasks.push(this.cleanupAdapterSession(adapter, fileId, reason));
+        }
+        await Promise.all(tasks);
+    }
+}
+export function createUploadClient(config) {
+    return new UploadSDK(config);
+}
+export function registerStorageAdapter(client, name, adapter) {
+    client.registerAdapter(name, adapter);
+}
+export function setFileExtensionRules(client, rules) {
+    client.setExtensionRules(rules);
+}
+export async function addFiles(client, files) {
+    return client.saveFilesToIndexedDB(files);
+}
+export async function listFiles(client) {
+    return client.listStoredFiles();
+}
+export async function clearFiles(client) {
+    await client.clearStoredFiles();
+}
+export async function uploadFiles(client, adapterName, options = {}) {
+    await client.uploadFiles(adapterName, options);
+}
+export async function uploadSelectedFiles(client, adapterName, fileIds, options = {}) {
+    await client.uploadSelectedFiles(adapterName, fileIds, options);
+}
+export function pauseFileUpload(client, fileId) {
+    client.pauseUpload(fileId);
+}
+export function resumeFileUpload(client, fileId) {
+    client.resumeUpload(fileId);
+}
+export async function cancelFileUpload(client, fileId) {
+    await client.cancelUpload(fileId);
+}

package/dist/presigned-s3-adapter.d.ts

@@ -0,0 +1,34 @@
+import type { StorageAdapter, UploadResult } from './index';
+export type PresignedS3AdapterConfig = {
+    apiBaseUrl: string;
+    multipartThresholdBytes?: number;
+    multipartPartSizeBytes?: number;
+};
+type UploadRuntimeOptions = {
+    fileId?: string;
+    onProgress?: (progress: number) => void;
+    signal?: AbortSignal;
+};
+export declare class PresignedS3Adapter implements StorageAdapter {
+    private apiBaseUrl;
+    private multipartThresholdBytes;
+    private multipartPartSizeBytes;
+    constructor(config: PresignedS3AdapterConfig);
+    uploadFile(file: File, options?: UploadRuntimeOptions): Promise<UploadResult>;
+    cleanupUploadSession(fileId: string, _meta?: {
+        reason: 'canceled' | 'final-failure';
+    }): Promise<void>;
+    private abortMultipartWithRetry;
+    private uploadSimple;
+    private getSessionKey;
+    private loadSession;
+    private saveSession;
+    private clearSession;
+    private computeUploadedBytes;
+    private uploadMultipart;
+    private waitForPartEtag;
+    private fetchPartEtag;
+    private putWithProgress;
+}
+export declare function createPresignedS3Adapter(config: PresignedS3AdapterConfig): PresignedS3Adapter;
+export {};