@wlindabla/file_uploader 1.0.0 → 2.0.0

package/dist/cjs/core/index.d.ts

@@ -0,0 +1,267 @@
+import { EventDispatcherInterface } from '@wlindabla/event_dispatcher';
+import { UploadOptions, UploadEndpoints, UploadState, ResumeData } from '../types/index.js';
+import { UploadResumeCacheInterface } from '../cache/index.js';
+import '@wlindabla/http_client';
+
+/**
+ * ChunkedFileUploader
+ *
+ * A production-ready, event-driven chunked file upload engine for Browser and Node.js.
+ *
+ * Designed and developed by **AGBOKOUDJO Franck** at
+ * **INTERNATIONALES WEB APPS & SERVICES**, this class provides a robust,
+ * framework-agnostic solution for uploading large files to a remote server
+ * by splitting them into smaller chunks and sending them in parallel with
+ * configurable concurrency control.
+ *
+ * ---
+ *
+ * ### How It Works
+ *
+ * The upload process follows a strict three-phase lifecycle:
+ *
+ * 1. **Initialization** — A session is opened with the server via the `init` endpoint.
+ *    The file is identified by its name, size, type, and a SHA-256 hash of its
+ *    first megabyte. The server returns a unique `mediaId` that identifies the session.
+ *
+ * 2. **Chunk Upload** — The file is sliced into fixed-size chunks and uploaded
+ *    concurrently using `p-limit`. Each chunk carries its index, the total number
+ *    of chunks, and the session `mediaId`. Failed chunks are retried automatically
+ *    with exponential backoff up to `maxRetries` attempts.
+ *
+ * 3. **Finalization** — Once all chunks are successfully uploaded, the `finalize`
+ *    endpoint is called to instruct the server to assemble the chunks into the
+ *    final file.
+ *
+ * ---
+ *
+ * ### Event-Driven Architecture
+ *
+ * This class follows the **Symfony EventDispatcher pattern** via
+ * `@wlindabla/event_dispatcher`. Every meaningful moment in the upload
+ * lifecycle emits a typed event that your application can listen to:
+ *
+ * ```
+ * IDLE → INITIALIZING → UPLOADING → FINALIZING → COMPLETED
+ *                ↓            ↓
+ *             FAILED        PAUSED ↔ UPLOADING
+ *                              ↓
+ *                          CANCELLED
+ * ```
+ *
+ * All event name constants are centralized in {@link HttpFileUploaderEvents}.
+ *
+ * ---
+ *
+ * ### Subscriber Registration (Required)
+ *
+ * Before calling `.upload()`, you **must** register the two built-in subscribers
+ * on your dispatcher. They handle the HTTP communication for the init and finalize phases:
+ *
+ * ```typescript
+ * // Browser
+ * const dispatcher = new BrowserEventDispatcher(document);
+ * dispatcher.addSubscriber(new InitializeUploadSubscriber(dispatcher));
+ * dispatcher.addSubscriber(new FinalizeUploadSubscriber(dispatcher));
+ *
+ * // Node.js
+ * const dispatcher = new NodeEventDispatcher();
+ * dispatcher.addSubscriber(new InitializeUploadSubscriber(dispatcher));
+ * dispatcher.addSubscriber(new FinalizeUploadSubscriber(dispatcher));
+ * ```
+ *
+ * ---
+ *
+ * ### Fluent Builder API
+ *
+ * The class exposes a fluent API to configure the upload before starting:
+ *
+ * ```typescript
+ * const uploader = new ChunkedFileUploader(dispatcher, cache, options);
+ *
+ * await uploader
+ *   .withFile(file)
+ *   .withEndpoints({
+ *     init:     'https://api.example.com/upload/init',
+ *     upload:   'https://api.example.com/upload/chunk',
+ *     finalize: 'https://api.example.com/upload/finalize'
+ *   })
+ *   .upload();
+ * ```
+ *
+ * ---
+ *
+ * ### Resumable Uploads
+ *
+ * When `autoSave: true` is set in options, the upload progress is persisted
+ * after each successful chunk via the {@link UploadResumeCacheInterface}.
+ * A failed or interrupted upload can be resumed later:
+ *
+ * ```typescript
+ * const resumeData = await uploader.loadResumeData(file.name);
+ *
+ * if (resumeData) {
+ *   await uploader
+ *     .withFile(file)
+ *     .withEndpoints(endpoints)
+ *     .resumeUpload(resumeData);
+ * }
+ * ```
+ *
+ * ---
+ *
+ * ### Concurrency
+ *
+ * Multiple chunks can be uploaded simultaneously. The `concurrency` option
+ * controls how many parallel uploads are active at any given time.
+ * The default value is `3`, which provides a good balance between speed
+ * and server/network load:
+ *
+ * ```typescript
+ * // Upload 5 chunks in parallel
+ * new ChunkedFileUploader(dispatcher, cache, { concurrency: 5 });
+ * ```
+ *
+ * ---
+ *
+ * ### Pause, Resume and Cancel
+ *
+ * The upload can be paused, resumed, or cancelled at any time:
+ *
+ * ```typescript
+ * uploader.pause();   // Pauses after the current chunk finishes
+ * uploader.resume();  // Resumes from where it was paused
+ * uploader.cancel();  // Aborts immediately via AbortController
+ * ```
+ *
+ * ---
+ *
+ * ### Cache
+ *
+ * The library does **not** provide a built-in cache implementation to stay
+ * lightweight and environment-agnostic. You must implement
+ * {@link UploadResumeCacheInterface} with your preferred storage backend
+ * (localStorage, IndexedDB, Redis, filesystem, etc.).
+ *
+ * ---
+ *
+ * @author    AGBOKOUDJO Franck <internationaleswebservices@gmail.com>
+ * @company   INTERNATIONALES WEB APPS & SERVICES
+ * @phone     +229 0167 25 18 86
+ * @linkedin  https://www.linkedin.com/in/internationales-web-apps-services-120520193/
+ * @github    https://github.com/Agbokoudjo/file_uploader
+ *
+ * @version   1.0.0
+ * @since     1.0.0
+ * @license   MIT
+ *
+ * @see {@link HttpFileUploaderEvents}        All event name constants
+ * @see {@link UploadResumeCacheInterface}    Cache interface to implement
+ * @see {@link InitializeUploadSubscriber}    Handles the init HTTP phase
+ * @see {@link FinalizeUploadSubscriber}      Handles the finalize HTTP phase
+ * @see {@link UploadOptions}                 Full configuration reference
+ * @see {@link https://github.com/Agbokoudjo/file_uploader | GitHub Repository}
+ */
+declare class ChunkedFileUploader {
+    private readonly _uploadEventDispatcher;
+    private readonly uploadResumeData;
+    private options;
+    private _file;
+    private _endpoints;
+    private isPaused;
+    private startTime;
+    private uploadedBytes;
+    private abortController;
+    private state;
+    private totalChunks;
+    private percentage;
+    private uploadedChunks;
+    private lastUploadedChunkIndex;
+    constructor(_uploadEventDispatcher: EventDispatcherInterface | undefined, //or new NodeJSEventDispatcher() if you have an environment NodeJs
+    uploadResumeData: UploadResumeCacheInterface, options: UploadOptions);
+    /**
+     * Starts the chunked file upload process.
+     *
+     * @throws {Error} If file or endpoints are not set
+     * @throws {InitializeUploadFailureException} If server initialization fails
+     * @throws {FileUploadChunkError} If a chunk fails after all retries
+     *
+     * @example
+     * ```typescript
+     * const uploader = new ChunkedFileUploader(dispatcher, cache, options);
+     *
+     * uploader
+     *   .withFile(file)
+     *   .withEndpoints({ init, upload, finalize });
+     *
+     * await uploader.upload();
+     * ```
+     */
+    upload(): Promise<void>;
+    withFile(file: File): this;
+    withEndpoints(endpoints: UploadEndpoints): this;
+    private get endPointOptions();
+    private get file();
+    /**
+     * Upload all chunks with concurrency control using p-limit
+     *
+     * @param file - File to upload
+     * @param chunkSize - Size of each chunk
+     * @param fileId - Server file ID
+     * @param fileHash - File hash
+     * @param maxRetries - Max retry attempts per chunk
+     * @param concurrency - Number of concurrent uploads (default: 3)
+     */
+    private uploadChunksWithConcurrency;
+    /**
+     * Process a single chunk: slice, upload with retry, and save progress.
+     *
+     * @param file - The file being uploaded
+     * @param currentChunkIndex - Index of the current chunk (0-based)
+     * @param chunkSize - Size of each chunk in bytes
+     * @param fileId - Server-provided file/session ID
+     * @param fileHash - SHA-256 hash of the file
+     * @param maxRetries - Maximum number of retry attempts
+     *
+     * @throws {UploadCancelledException} If upload is cancelled
+     * @throws {FileUploadChunkError} If chunk upload fails after all retries
+     */
+    private processChunk;
+    private uploadChunkWithRetry;
+    private uploadChunk;
+    private createChunkAbortSignal;
+    private notifyProgress;
+    private sleep;
+    /**
+     * Save current upload progress to cache for resume capability
+     *
+     * @param fileId - Server-provided file/session ID
+     * @param chunkSize - Size of each chunk in bytes
+     * @returns Saved resume data
+     */
+    private saveResumeData;
+    private setState;
+    getState(): UploadState;
+    private handleUploadFailure;
+    cancel(): void;
+    pause(): void;
+    resume(): void;
+    /**
+    * Load previously saved resume data
+    *
+    * @param fileName - Name of the file to resume
+    * @returns Resume data or null if not found
+    */
+    loadResumeData(fileName: string): Promise<ResumeData | null>;
+    /**
+    * Resume upload from saved state
+    *
+    * @param resumeData - Previously saved resume data
+    * @returns Upload result
+    */
+    resumeUpload(resumeData: ResumeData): Promise<void>;
+    private updateProgress;
+    private finalizeUpload;
+}
+
+export { ChunkedFileUploader };