@chunkflowjs/core 0.0.1-alpha.1

package/dist/index.mjs

@@ -0,0 +1,1988 @@
+import { ConcurrencyController, UploadStorage, calculateChunkHash, calculateFileHash, calculateSpeed, createEventBus, estimateRemainingTime, sliceFile } from "@chunkflowjs/shared";
+
+//#region src/chunk-size-adjuster.ts
+/**
+* ChunkSizeAdjuster dynamically adjusts chunk sizes based on upload performance.
+* Uses a simple binary strategy: doubles size when fast, halves when slow.
+*
+* @example
+* ```typescript
+* const adjuster = new ChunkSizeAdjuster({
+*   initialSize: 1024 * 1024, // 1MB
+*   minSize: 256 * 1024,       // 256KB
+*   maxSize: 10 * 1024 * 1024, // 10MB
+*   targetTime: 3000           // 3 seconds
+* });
+*
+* // After uploading a chunk
+* const uploadTimeMs = 1500;
+* const newSize = adjuster.adjust(uploadTimeMs);
+* ```
+*/
+var ChunkSizeAdjuster = class {
+	currentSize;
+	options;
+	constructor(options) {
+		this.currentSize = options.initialSize;
+		this.options = {
+			targetTime: 3e3,
+			...options
+		};
+		if (this.options.minSize > this.options.maxSize) throw new Error("minSize cannot be greater than maxSize");
+		if (this.options.initialSize < this.options.minSize || this.options.initialSize > this.options.maxSize) throw new Error("initialSize must be between minSize and maxSize");
+		if (this.options.targetTime <= 0) throw new Error("targetTime must be positive");
+	}
+	/**
+	* Adjusts the chunk size based on the upload time of the previous chunk.
+	* Uses a simple binary strategy:
+	* - If upload is fast (< 50% of target time): double the chunk size
+	* - If upload is slow (> 150% of target time): halve the chunk size
+	* - Otherwise: keep the current size
+	*
+	* @param uploadTimeMs - The time taken to upload the previous chunk in milliseconds
+	* @returns The new chunk size in bytes
+	*/
+	adjust(uploadTimeMs) {
+		if (uploadTimeMs < 0) throw new Error("uploadTimeMs cannot be negative");
+		const { targetTime, minSize, maxSize } = this.options;
+		if (uploadTimeMs < targetTime * .5) this.currentSize = Math.min(this.currentSize * 2, maxSize);
+		else if (uploadTimeMs > targetTime * 1.5) this.currentSize = Math.max(this.currentSize / 2, minSize);
+		return this.currentSize;
+	}
+	/**
+	* Gets the current chunk size without adjusting it.
+	*
+	* @returns The current chunk size in bytes
+	*/
+	getCurrentSize() {
+		return this.currentSize;
+	}
+	/**
+	* Resets the chunk size to the initial size.
+	* Useful when starting a new upload or after an error.
+	*/
+	reset() {
+		this.currentSize = this.options.initialSize;
+	}
+};
+
+//#endregion
+//#region src/chunk-size-adjuster-tcp.ts
+let CongestionState = /* @__PURE__ */ function(CongestionState) {
+	CongestionState["SLOW_START"] = "slow_start";
+	CongestionState["CONGESTION_AVOIDANCE"] = "congestion_avoidance";
+	CongestionState["FAST_RECOVERY"] = "fast_recovery";
+	return CongestionState;
+}({});
+/**
+* TCP-inspired chunk size adjuster with proper slow start and congestion avoidance
+*
+* Algorithm:
+* 1. Slow Start: Exponential growth (double size) until ssthresh
+* 2. Congestion Avoidance: Linear growth (add increment) after ssthresh
+* 3. Fast Recovery: On congestion, set ssthresh = currentSize / 2, reduce size
+*
+* @example
+* ```typescript
+* const adjuster = new TCPChunkSizeAdjuster({
+*   initialSize: 256 * 1024,      // 256KB (like TCP initial cwnd)
+*   minSize: 256 * 1024,           // 256KB
+*   maxSize: 10 * 1024 * 1024,     // 10MB
+*   targetTime: 3000,              // 3 seconds
+*   initialSsthresh: 5 * 1024 * 1024 // 5MB
+* });
+*
+* // After each chunk upload
+* const newSize = adjuster.adjust(uploadTimeMs);
+* ```
+*/
+var TCPChunkSizeAdjuster = class {
+	currentSize;
+	ssthresh;
+	state;
+	options;
+	consecutiveFastUploads = 0;
+	consecutiveSlowUploads = 0;
+	constructor(options) {
+		this.currentSize = options.initialSize;
+		this.options = {
+			targetTime: 3e3,
+			initialSsthresh: options.initialSsthresh ?? options.maxSize / 2,
+			...options
+		};
+		this.ssthresh = this.options.initialSsthresh;
+		this.state = CongestionState.SLOW_START;
+		this.validate();
+	}
+	validate() {
+		const { minSize, maxSize, initialSize, targetTime, initialSsthresh } = this.options;
+		if (minSize > maxSize) throw new Error("minSize cannot be greater than maxSize");
+		if (initialSize < minSize || initialSize > maxSize) throw new Error("initialSize must be between minSize and maxSize");
+		if (targetTime <= 0) throw new Error("targetTime must be positive");
+		if (initialSsthresh < minSize || initialSsthresh > maxSize) throw new Error("initialSsthresh must be between minSize and maxSize");
+	}
+	/**
+	* Adjusts chunk size based on upload performance using TCP-like algorithm
+	*
+	* @param uploadTimeMs - Time taken to upload the previous chunk
+	* @returns New chunk size in bytes
+	*/
+	adjust(uploadTimeMs) {
+		if (uploadTimeMs < 0) throw new Error("uploadTimeMs cannot be negative");
+		const { targetTime, minSize, maxSize } = this.options;
+		const ratio = uploadTimeMs / targetTime;
+		if (ratio < .5) {
+			this.consecutiveFastUploads++;
+			this.consecutiveSlowUploads = 0;
+			this.handleFastUpload();
+		} else if (ratio > 1.5) {
+			this.consecutiveSlowUploads++;
+			this.consecutiveFastUploads = 0;
+			this.handleSlowUpload();
+		} else {
+			this.consecutiveFastUploads = 0;
+			this.consecutiveSlowUploads = 0;
+		}
+		this.currentSize = Math.max(minSize, Math.min(this.currentSize, maxSize));
+		return this.currentSize;
+	}
+	handleFastUpload() {
+		const { maxSize } = this.options;
+		switch (this.state) {
+			case CongestionState.SLOW_START:
+				const newSize = this.currentSize * 2;
+				if (newSize >= this.ssthresh) {
+					this.currentSize = this.ssthresh;
+					this.state = CongestionState.CONGESTION_AVOIDANCE;
+				} else this.currentSize = Math.min(newSize, maxSize);
+				break;
+			case CongestionState.CONGESTION_AVOIDANCE:
+				const increment = Math.max(this.options.minSize, Math.floor(this.currentSize * .1));
+				this.currentSize = Math.min(this.currentSize + increment, maxSize);
+				break;
+			case CongestionState.FAST_RECOVERY:
+				this.state = CongestionState.CONGESTION_AVOIDANCE;
+				break;
+		}
+	}
+	handleSlowUpload() {
+		const { minSize } = this.options;
+		this.ssthresh = Math.max(minSize, Math.floor(this.currentSize / 2));
+		this.currentSize = this.ssthresh;
+		this.state = CongestionState.FAST_RECOVERY;
+	}
+	/**
+	* Gets the current chunk size
+	*/
+	getCurrentSize() {
+		return this.currentSize;
+	}
+	/**
+	* Gets the current slow start threshold
+	*/
+	getSsthresh() {
+		return this.ssthresh;
+	}
+	/**
+	* Gets the current congestion state
+	*/
+	getState() {
+		return this.state;
+	}
+	/**
+	* Resets to initial state
+	*/
+	reset() {
+		this.currentSize = this.options.initialSize;
+		this.ssthresh = this.options.initialSsthresh;
+		this.state = CongestionState.SLOW_START;
+		this.consecutiveFastUploads = 0;
+		this.consecutiveSlowUploads = 0;
+	}
+	/**
+	* Gets statistics about the adjuster's behavior
+	*/
+	getStats() {
+		return {
+			currentSize: this.currentSize,
+			ssthresh: this.ssthresh,
+			state: this.state,
+			consecutiveFastUploads: this.consecutiveFastUploads,
+			consecutiveSlowUploads: this.consecutiveSlowUploads
+		};
+	}
+};
+
+//#endregion
+//#region src/upload-task.ts
+/**
+* UploadTask class
+*
+* Manages a single file upload with support for:
+* - Chunked upload with dynamic chunk size adjustment
+* - Hash calculation and verification (instant upload/resume)
+* - Concurrent chunk uploads with retry
+* - Progress tracking and persistence
+* - Pause/resume/cancel operations
+* - Event-driven lifecycle
+*
+* @example
+* ```typescript
+* const task = new UploadTask({
+*   file: myFile,
+*   requestAdapter: myAdapter,
+*   chunkSize: 1024 * 1024, // 1MB
+*   concurrency: 3,
+* });
+*
+* // Listen to events
+* task.on('progress', ({ progress, speed }) => {
+*   console.log(`Progress: ${progress}%, Speed: ${speed} bytes/s`);
+* });
+*
+* task.on('success', ({ fileUrl }) => {
+*   console.log(`Upload complete: ${fileUrl}`);
+* });
+*
+* // Start upload
+* await task.start();
+* ```
+*/
+var UploadTask = class {
+	/** Unique task identifier */
+	id;
+	/** File being uploaded */
+	file;
+	/** Current upload status */
+	status;
+	/** Current upload progress */
+	progress;
+	/** Array of chunk information */
+	chunks;
+	/** Upload token from server */
+	uploadToken;
+	/** Calculated file hash */
+	fileHash;
+	/** Event bus for lifecycle events */
+	eventBus;
+	/** Concurrency controller for chunk uploads */
+	concurrencyController;
+	/** Storage for persisting upload progress */
+	storage;
+	/** Request adapter for API calls */
+	requestAdapter;
+	/** Upload task options with defaults */
+	options;
+	/** Upload start timestamp */
+	startTime;
+	/** Upload end timestamp */
+	endTime;
+	/** Chunk size adjuster for dynamic sizing */
+	chunkSizeAdjuster;
+	/** Flag to indicate if upload should be cancelled (e.g., instant upload) */
+	shouldCancelUpload;
+	/**
+	* Creates a new UploadTask
+	*
+	* @param options - Upload task configuration options
+	*/
+	constructor(options) {
+		this.id = options.resumeTaskId ?? this.generateTaskId();
+		this.file = options.file;
+		this.status = "idle";
+		this.progress = {
+			uploadedBytes: 0,
+			totalBytes: options.file.size,
+			percentage: 0,
+			speed: 0,
+			remainingTime: 0,
+			uploadedChunks: 0,
+			totalChunks: 0
+		};
+		this.chunks = [];
+		if (options.resumeUploadToken) this.uploadToken = {
+			token: options.resumeUploadToken,
+			fileId: "",
+			chunkSize: options.chunkSize ?? 1024 * 1024,
+			expiresAt: Date.now() + 1440 * 60 * 1e3
+		};
+		else this.uploadToken = null;
+		this.fileHash = null;
+		this.eventBus = createEventBus();
+		this.requestAdapter = options.requestAdapter;
+		this.options = {
+			file: options.file,
+			requestAdapter: options.requestAdapter,
+			chunkSize: options.chunkSize ?? 1024 * 1024,
+			concurrency: options.concurrency ?? 3,
+			retryCount: options.retryCount ?? 3,
+			retryDelay: options.retryDelay ?? 1e3,
+			autoStart: options.autoStart ?? false,
+			resumeTaskId: options.resumeTaskId ?? "",
+			resumeUploadToken: options.resumeUploadToken ?? "",
+			resumeUploadedChunks: options.resumeUploadedChunks ?? [],
+			chunkSizeStrategy: options.chunkSizeStrategy ?? "tcp-like",
+			initialSsthresh: options.initialSsthresh ?? 5 * 1024 * 1024
+		};
+		this.concurrencyController = new ConcurrencyController({ limit: this.options.concurrency });
+		this.storage = new UploadStorage();
+		this.startTime = 0;
+		this.endTime = null;
+		this.chunkSizeAdjuster = null;
+		this.shouldCancelUpload = false;
+	}
+	/**
+	* Generates a unique task ID
+	* Uses timestamp and random string for uniqueness
+	*
+	* @returns Unique task identifier
+	*/
+	generateTaskId() {
+		return `task_${Date.now().toString(36)}_${Math.random().toString(36).substring(2, 9)}`;
+	}
+	/**
+	* Gets the current upload status
+	*
+	* @returns Current upload status
+	*/
+	getStatus() {
+		return this.status;
+	}
+	/**
+	* Gets the current upload progress
+	* Returns a copy to prevent external modification
+	*
+	* @returns Current upload progress
+	*/
+	getProgress() {
+		return { ...this.progress };
+	}
+	/**
+	* Gets the upload duration in milliseconds
+	* Returns null if upload hasn't completed
+	*
+	* @returns Upload duration or null
+	*/
+	getDuration() {
+		if (this.endTime === null) return null;
+		return this.endTime - this.startTime;
+	}
+	/**
+	* Subscribes to upload events
+	*
+	* @param event - Event name to listen to
+	* @param handler - Event handler function
+	*
+	* @example
+	* ```typescript
+	* task.on('progress', ({ progress, speed }) => {
+	*   console.log(`${progress}% at ${speed} bytes/s`);
+	* });
+	* ```
+	*/
+	on(event, handler) {
+		this.eventBus.on(event, handler);
+	}
+	/**
+	* Unsubscribes from upload events
+	*
+	* @param event - Event name to stop listening to
+	* @param handler - Event handler function to remove
+	*/
+	off(event, handler) {
+		this.eventBus.off(event, handler);
+	}
+	/**
+	* Creates chunk information array based on negotiated chunk size
+	* Divides the file into chunks and creates ChunkInfo objects for each
+	*
+	* @param chunkSize - Size of each chunk in bytes (negotiated with server)
+	* @returns Array of ChunkInfo objects
+	*
+	* @remarks
+	* - Chunks are created sequentially from start to end of file
+	* - Last chunk may be smaller than chunkSize
+	* - Hash field is initially empty and will be calculated during upload
+	* - Validates: Requirement 2.1 (chunk size based splitting)
+	*
+	* @internal This method will be used in task 5.3
+	*/
+	createChunks(chunkSize) {
+		const chunks = [];
+		const totalChunks = Math.ceil(this.file.size / chunkSize);
+		for (let i = 0; i < totalChunks; i++) {
+			const start = i * chunkSize;
+			const end = Math.min(start + chunkSize, this.file.size);
+			chunks.push({
+				index: i,
+				hash: "",
+				size: end - start,
+				start,
+				end
+			});
+		}
+		return chunks;
+	}
+	/**
+	* Starts the upload process
+	*
+	* Workflow:
+	* 1. Create file on server and get upload token
+	* 2. Split file into chunks based on negotiated chunk size
+	* 3. Start concurrent chunk upload
+	*
+	* @throws Error if upload is already in progress or completed
+	*
+	* @remarks
+	* - Validates: Requirements 1.1, 1.2, 2.2, 5.1, 5.2, 5.3, 20.1, 20.2, 20.3, 20.5
+	* - Sets status to 'uploading'
+	* - Emits 'start' event
+	* - Creates chunks based on negotiated size
+	* - Initiates concurrent upload with retry
+	*/
+	async start() {
+		if (this.status !== "idle") throw new Error(`Cannot start upload: current status is ${this.status}`);
+		try {
+			await this.initializeStorage();
+			this.status = "uploading";
+			this.startTime = Date.now();
+			this.eventBus.emit("start", {
+				taskId: this.id,
+				file: this.file
+			});
+			const isResume = this.options.resumeUploadToken && this.options.resumeUploadedChunks;
+			let negotiatedChunkSize;
+			if (isResume) {
+				negotiatedChunkSize = this.uploadToken.chunkSize;
+				console.info(`Resuming upload for task ${this.id}: ${this.options.resumeUploadedChunks.length} chunks already uploaded`);
+			} else {
+				const createResponse = await this.requestAdapter.createFile({
+					fileName: this.file.name,
+					fileSize: this.file.size,
+					fileType: this.file.type,
+					preferredChunkSize: this.options.chunkSize
+				});
+				this.uploadToken = createResponse.uploadToken;
+				negotiatedChunkSize = createResponse.negotiatedChunkSize;
+			}
+			this.chunks = this.createChunks(negotiatedChunkSize);
+			this.progress.totalChunks = this.chunks.length;
+			if (isResume && this.options.resumeUploadedChunks) {
+				const uploadedChunks = this.options.resumeUploadedChunks;
+				let uploadedBytes = 0;
+				for (const chunkIndex of uploadedChunks) if (chunkIndex < this.chunks.length) {
+					const chunk = this.chunks[chunkIndex];
+					chunk.uploaded = true;
+					uploadedBytes += chunk.size;
+				}
+				this.progress.uploadedChunks = uploadedChunks.length;
+				this.progress.uploadedBytes = uploadedBytes;
+				this.progress.percentage = uploadedBytes / this.file.size * 100;
+				console.info(`Resume progress: ${this.progress.percentage.toFixed(1)}% (${uploadedChunks.length}/${this.chunks.length} chunks)`);
+			}
+			const strategy = this.options.chunkSizeStrategy;
+			const minSize = 256 * 1024;
+			const maxSize = 10 * 1024 * 1024;
+			const targetTime = 3e3;
+			if (typeof strategy === "object") this.chunkSizeAdjuster = strategy;
+			else if (strategy === "tcp-like") this.chunkSizeAdjuster = new TCPChunkSizeAdjuster({
+				initialSize: negotiatedChunkSize,
+				minSize,
+				maxSize,
+				targetTime,
+				initialSsthresh: this.options.initialSsthresh
+			});
+			else this.chunkSizeAdjuster = new ChunkSizeAdjuster({
+				initialSize: negotiatedChunkSize,
+				minSize,
+				maxSize,
+				targetTime
+			});
+			await Promise.all([this.startUpload(), this.calculateAndVerifyHash()]);
+			if (this.status === "paused") {
+				console.info(`Upload paused at ${this.progress.percentage.toFixed(1)}%`);
+				return;
+			}
+			if (this.status === "cancelled" || this.shouldCancelUpload) return;
+			if (this.status === "success") {
+				console.info("Instant upload already completed");
+				return;
+			}
+			if (this.status === "uploading" && this.fileHash) try {
+				const chunkHashes = this.chunks.map((chunk) => chunk.hash);
+				const verifyResponse = await this.requestAdapter.verifyHash({
+					fileHash: this.fileHash,
+					chunkHashes,
+					uploadToken: this.uploadToken.token
+				});
+				if (verifyResponse.fileExists && verifyResponse.fileUrl) {
+					this.status = "success";
+					this.endTime = Date.now();
+					this.progress.uploadedBytes = this.file.size;
+					this.progress.uploadedChunks = this.chunks.length;
+					this.progress.percentage = 100;
+					this.eventBus.emit("success", {
+						taskId: this.id,
+						fileUrl: verifyResponse.fileUrl
+					});
+					return;
+				}
+			} catch (error) {
+				console.warn("Hash verification failed:", error);
+			}
+			else if (this.status === "uploading" && !this.fileHash) console.warn("No fileHash available, skipping hash verification");
+			if (this.status === "uploading" && !this.shouldCancelUpload) {
+				const mergeResponse = await this.requestAdapter.mergeFile({
+					uploadToken: this.uploadToken.token,
+					fileHash: this.fileHash || "",
+					chunkHashes: this.chunks.map((chunk) => chunk.hash)
+				});
+				if (mergeResponse.success) {
+					this.status = "success";
+					this.endTime = Date.now();
+					this.eventBus.emit("success", {
+						taskId: this.id,
+						fileUrl: mergeResponse.fileUrl
+					});
+				} else throw new Error("Merge failed: response.success is false");
+			}
+		} catch (error) {
+			if (this.status !== "paused" && this.status !== "cancelled") {
+				this.status = "error";
+				this.endTime = Date.now();
+				this.eventBus.emit("error", {
+					taskId: this.id,
+					error
+				});
+			}
+			throw error;
+		}
+	}
+	/**
+	* Starts concurrent chunk upload with priority for first chunks
+	*
+	* Uploads all chunks with concurrency control and dynamic chunk size adjustment.
+	* Uses the concurrency controller to limit parallel uploads.
+	* Implements priority upload for the first few chunks to get quick feedback.
+	*
+	* @remarks
+	* - Validates: Requirements 5.1, 5.2, 5.3, 17.5, 20.1, 20.2, 20.3
+	* - Respects concurrency limits
+	* - Tracks upload time for dynamic chunk size adjustment
+	* - Stops if status changes (pause/cancel) or shouldCancelUpload is set
+	* - Prioritizes first 3 chunks for quick server feedback
+	*
+	* @internal
+	*/
+	async startUpload() {
+		const chunksToUpload = this.chunks.filter((chunk) => !chunk.uploaded);
+		if (chunksToUpload.length === 0) {
+			console.info("All chunks already uploaded, skipping upload phase");
+			return;
+		}
+		const priorityChunkCount = Math.min(3, chunksToUpload.length);
+		const priorityChunks = chunksToUpload.slice(0, priorityChunkCount);
+		const remainingChunks = chunksToUpload.slice(priorityChunkCount);
+		const priorityPromises = priorityChunks.map((chunk) => {
+			return this.concurrencyController.run(async () => {
+				if (this.status !== "uploading" || this.shouldCancelUpload) return;
+				const chunkStartTime = Date.now();
+				await this.uploadChunkWithRetry(chunk);
+				const chunkUploadTime = Date.now() - chunkStartTime;
+				if (this.chunkSizeAdjuster) this.chunkSizeAdjuster.adjust(chunkUploadTime);
+			});
+		});
+		const remainingPromises = remainingChunks.map((chunk) => {
+			return this.concurrencyController.run(async () => {
+				if (this.status !== "uploading" || this.shouldCancelUpload) return;
+				const chunkStartTime = Date.now();
+				await this.uploadChunkWithRetry(chunk);
+				const chunkUploadTime = Date.now() - chunkStartTime;
+				if (this.chunkSizeAdjuster) this.chunkSizeAdjuster.adjust(chunkUploadTime);
+			});
+		});
+		await Promise.all([...priorityPromises, ...remainingPromises]);
+	}
+	/**
+	* Uploads a single chunk with retry logic
+	*
+	* Implements exponential backoff retry strategy for failed uploads.
+	* Calculates chunk hash before upload for verification.
+	* Updates progress after successful upload.
+	*
+	* @param chunk - Chunk information to upload
+	* @throws Error if all retries are exhausted
+	*
+	* @remarks
+	* - Validates: Requirements 20.1, 20.2, 20.3, 20.5
+	* - Retries up to configured retry count
+	* - Uses exponential backoff delay
+	* - Emits chunkSuccess or chunkError events
+	* - Updates progress and persists to storage
+	* - Skips upload if shouldCancelUpload is set (instant upload)
+	*
+	* @internal
+	*/
+	async uploadChunkWithRetry(chunk) {
+		let retries = 0;
+		let lastError = null;
+		while (retries <= this.options.retryCount) try {
+			if (this.status !== "uploading" || this.shouldCancelUpload) return;
+			const blob = sliceFile(this.file, chunk.start, chunk.end);
+			const chunkHash = await calculateChunkHash(blob);
+			chunk.hash = chunkHash;
+			await this.requestAdapter.uploadChunk({
+				uploadToken: this.uploadToken.token,
+				chunkIndex: chunk.index,
+				chunkHash,
+				chunk: blob
+			});
+			chunk.uploaded = true;
+			await this.updateProgress(chunk);
+			this.eventBus.emit("chunkSuccess", {
+				taskId: this.id,
+				chunkIndex: chunk.index
+			});
+			return;
+		} catch (error) {
+			lastError = error;
+			retries++;
+			this.eventBus.emit("chunkError", {
+				taskId: this.id,
+				chunkIndex: chunk.index,
+				error: lastError
+			});
+			if (retries > this.options.retryCount) throw new Error(`Failed to upload chunk ${chunk.index} after ${this.options.retryCount} retries: ${lastError.message}`);
+			const delay = this.options.retryDelay * Math.pow(2, retries - 1);
+			await this.delay(delay);
+		}
+		if (lastError) throw lastError;
+	}
+	/**
+	* Updates upload progress after a chunk is successfully uploaded
+	*
+	* Calculates:
+	* - Uploaded bytes and percentage
+	* - Upload speed
+	* - Estimated remaining time
+	*
+	* Emits progress event with updated information.
+	* Persists progress to IndexedDB for resume functionality.
+	*
+	* @param chunk - The chunk that was just uploaded
+	*
+	* @remarks
+	* - Validates: Requirements 4.1, 6.3, 6.4 (progress tracking and persistence)
+	* - Updates all progress metrics
+	* - Emits progress event
+	* - Persists to IndexedDB for resume capability
+	*
+	* @internal
+	*/
+	async updateProgress(chunk) {
+		if (chunk.progressCounted) {
+			console.warn(`Chunk ${chunk.index} progress already counted, skipping update`);
+			return;
+		}
+		chunk.progressCounted = true;
+		this.progress.uploadedBytes += chunk.size;
+		this.progress.uploadedChunks++;
+		if (this.progress.uploadedBytes > this.file.size) {
+			console.warn(`Progress overflow detected: ${this.progress.uploadedBytes} > ${this.file.size}, capping to file size`);
+			this.progress.uploadedBytes = this.file.size;
+		}
+		if (this.progress.uploadedChunks > this.progress.totalChunks) {
+			console.warn(`Chunk count overflow detected: ${this.progress.uploadedChunks} > ${this.progress.totalChunks}, capping to total chunks`);
+			this.progress.uploadedChunks = this.progress.totalChunks;
+		}
+		this.progress.percentage = Math.min(100, this.progress.uploadedBytes / this.file.size * 100);
+		const elapsedTime = Date.now() - this.startTime;
+		this.progress.speed = calculateSpeed(this.progress.uploadedBytes, elapsedTime);
+		const remainingBytes = this.file.size - this.progress.uploadedBytes;
+		this.progress.remainingTime = estimateRemainingTime(remainingBytes, this.progress.speed);
+		this.eventBus.emit("progress", {
+			taskId: this.id,
+			progress: this.progress.percentage,
+			speed: this.progress.speed
+		});
+		await this.persistProgress();
+	}
+	/**
+	* Delays execution for a specified time
+	* Used for retry backoff
+	*
+	* @param ms - Milliseconds to delay
+	* @returns Promise that resolves after the delay
+	*
+	* @internal
+	*/
+	delay(ms) {
+		return new Promise((resolve) => setTimeout(resolve, ms));
+	}
+	/**
+	* Calculates file hash and verifies with server for instant upload
+	*
+	* This method runs in parallel with chunk upload to optimize performance.
+	* It implements the following features:
+	* - Calculate file hash using Web Worker or requestIdleCallback (non-blocking)
+	* - Send hash verification request to server
+	* - Handle instant upload (秒传) when file already exists
+	* - Handle partial instant upload (skip existing chunks)
+	*
+	* @remarks
+	* - Validates: Requirements 3.1, 3.2, 3.3, 3.4, 3.5
+	* - Emits hashProgress events during calculation
+	* - Emits hashComplete event when calculation finishes
+	* - If file exists on server, cancels ongoing upload and emits success
+	* - If some chunks exist, marks them as uploaded to skip them
+	*
+	* @internal
+	*/
+	async calculateAndVerifyHash() {
+		try {
+			this.fileHash = await calculateFileHash(this.file, (progress) => {
+				this.eventBus.emit("hashProgress", {
+					taskId: this.id,
+					progress
+				});
+			});
+			this.eventBus.emit("hashComplete", {
+				taskId: this.id,
+				hash: this.fileHash
+			});
+			if (!this.uploadToken) return;
+			const verifyResponse = await this.requestAdapter.verifyHash({
+				fileHash: this.fileHash,
+				uploadToken: this.uploadToken.token
+			});
+			if (verifyResponse.fileExists && verifyResponse.fileUrl) {
+				if (this.status === "paused" || this.status === "cancelled") return;
+				this.shouldCancelUpload = true;
+				this.status = "success";
+				this.endTime = Date.now();
+				this.progress.uploadedBytes = this.file.size;
+				this.progress.uploadedChunks = this.chunks.length;
+				this.progress.percentage = 100;
+				this.eventBus.emit("success", {
+					taskId: this.id,
+					fileUrl: verifyResponse.fileUrl
+				});
+				return;
+			}
+			if (verifyResponse.existingChunks && verifyResponse.existingChunks.length > 0) this.skipExistingChunks(verifyResponse.existingChunks);
+		} catch (error) {
+			console.warn("Hash calculation/verification failed:", error);
+		}
+	}
+	/**
+	* Skips existing chunks by marking them as uploaded
+	*
+	* This is used for partial instant upload when some chunks already exist on server.
+	* Updates progress to reflect the skipped chunks.
+	*
+	* @param existingChunkIndices - Array of chunk indices that already exist on server
+	*
+	* @remarks
+	* - Validates: Requirement 3.5, 17.4 (partial instant upload)
+	* - Updates progress for skipped chunks
+	* - Emits chunkSuccess events for skipped chunks
+	*
+	* @internal
+	*/
+	skipExistingChunks(existingChunkIndices) {
+		for (const chunkIndex of existingChunkIndices) {
+			const chunk = this.chunks[chunkIndex];
+			if (!chunk) continue;
+			chunk.uploaded = true;
+			chunk.progressCounted = true;
+			this.progress.uploadedBytes += chunk.size;
+			this.progress.uploadedChunks++;
+			this.progress.percentage = this.progress.uploadedBytes / this.file.size * 100;
+			this.eventBus.emit("chunkSuccess", {
+				taskId: this.id,
+				chunkIndex: chunk.index
+			});
+		}
+		this.eventBus.emit("progress", {
+			taskId: this.id,
+			progress: this.progress.percentage,
+			speed: this.progress.speed
+		});
+	}
+	/**
+	* Initializes the IndexedDB storage for progress persistence
+	*
+	* Creates the initial upload record in IndexedDB.
+	* If storage is not available, logs a warning but continues upload.
+	*
+	* @remarks
+	* - Validates: Requirement 4.1 (persist progress to IndexedDB)
+	* - Gracefully handles storage unavailability
+	* - Creates initial record with empty uploaded chunks
+	*
+	* @internal
+	*/
+	async initializeStorage() {
+		try {
+			await this.storage.init();
+			const record = {
+				taskId: this.id,
+				fileInfo: {
+					name: this.file.name,
+					size: this.file.size,
+					type: this.file.type,
+					lastModified: this.file.lastModified
+				},
+				uploadedChunks: [],
+				uploadToken: this.uploadToken?.token || "",
+				createdAt: Date.now(),
+				updatedAt: Date.now()
+			};
+			await this.storage.saveRecord(record);
+		} catch (error) {}
+	}
+	/**
+	* Persists current upload progress to IndexedDB
+	*
+	* Updates the upload record with the list of successfully uploaded chunks.
+	* This enables resume functionality if the upload is interrupted.
+	*
+	* @remarks
+	* - Validates: Requirement 4.1 (write progress to IndexedDB)
+	* - Gracefully handles storage errors
+	* - Updates uploadedChunks array and timestamp
+	*
+	* @internal
+	*/
+	async persistProgress() {
+		try {
+			if (!this.storage.isAvailable()) return;
+			const uploadedChunkIndices = this.chunks.filter((_, index) => index < this.progress.uploadedChunks).map((chunk) => chunk.index);
+			try {
+				await this.storage.updateRecord(this.id, {
+					uploadedChunks: uploadedChunkIndices,
+					uploadToken: this.uploadToken?.token || "",
+					updatedAt: Date.now()
+				});
+			} catch (error) {
+				if (error.code === "OPERATION_FAILED") {
+					const record = {
+						taskId: this.id,
+						fileInfo: {
+							name: this.file.name,
+							size: this.file.size,
+							type: this.file.type,
+							lastModified: this.file.lastModified
+						},
+						uploadedChunks: uploadedChunkIndices,
+						uploadToken: this.uploadToken?.token || "",
+						createdAt: Date.now(),
+						updatedAt: Date.now()
+					};
+					await this.storage.saveRecord(record);
+				} else throw error;
+			}
+		} catch (error) {}
+	}
+	/**
+	* Pauses the upload
+	*
+	* Pauses an ongoing upload by changing the status to 'paused'.
+	* The upload can be resumed later from where it left off.
+	*
+	* @remarks
+	* - Validates: Requirements 4.3, 6.3 (pause functionality and lifecycle events)
+	* - Only works when status is 'uploading'
+	* - Emits 'pause' event
+	* - Progress is persisted to IndexedDB for resume
+	* - Ongoing chunk uploads will complete, but no new chunks will start
+	*
+	* @example
+	* ```typescript
+	* task.on('pause', () => {
+	*   console.log('Upload paused');
+	* });
+	*
+	* task.pause();
+	* ```
+	*/
+	pause() {
+		if (this.status !== "uploading") {
+			console.warn(`Cannot pause upload: current status is ${this.status}`);
+			return;
+		}
+		this.status = "paused";
+		this.eventBus.emit("pause", { taskId: this.id });
+	}
+	/**
+	* Resumes a paused upload (断点续传)
+	*
+	* Resumes an upload that was previously paused.
+	* Continues uploading from where it left off, skipping already uploaded chunks.
+	*
+	* @throws Error if upload is not in paused state
+	*
+	* @remarks
+	* - Validates: Requirements 4.3, 4.4, 6.3 (resume functionality and lifecycle events)
+	* - Only works when status is 'paused'
+	* - Emits 'resume' event
+	* - Continues from last uploaded chunk
+	* - Uses persisted progress from IndexedDB
+	*
+	* @example
+	* ```typescript
+	* task.on('resume', () => {
+	*   console.log('Upload resumed');
+	* });
+	*
+	* await task.resume();
+	* ```
+	*/
+	async resume() {
+		if (this.status !== "paused") throw new Error(`Cannot resume upload: current status is ${this.status}`);
+		try {
+			if (!this.uploadToken) throw new Error("Cannot resume: upload token not available");
+			this.status = "uploading";
+			this.eventBus.emit("resume", { taskId: this.id });
+			await this.startUpload();
+			if (this.status === "cancelled" || this.shouldCancelUpload) return;
+			if (this.status === "uploading") {
+				if (this.fileHash) try {
+					const chunkHashes = this.chunks.map((chunk) => chunk.hash);
+					const verifyResponse = await this.requestAdapter.verifyHash({
+						fileHash: this.fileHash,
+						chunkHashes,
+						uploadToken: this.uploadToken.token
+					});
+					if (verifyResponse.fileExists && verifyResponse.fileUrl) {
+						this.status = "success";
+						this.endTime = Date.now();
+						this.progress.uploadedBytes = this.file.size;
+						this.progress.uploadedChunks = this.chunks.length;
+						this.progress.percentage = 100;
+						this.eventBus.emit("success", {
+							taskId: this.id,
+							fileUrl: verifyResponse.fileUrl
+						});
+						return;
+					}
+				} catch (error) {
+					console.warn("Hash verification failed:", error);
+				}
+				const mergeResponse = await this.requestAdapter.mergeFile({
+					uploadToken: this.uploadToken.token,
+					fileHash: this.fileHash || "",
+					chunkHashes: this.chunks.map((chunk) => chunk.hash)
+				});
+				if (mergeResponse.success) {
+					this.status = "success";
+					this.endTime = Date.now();
+					this.eventBus.emit("success", {
+						taskId: this.id,
+						fileUrl: mergeResponse.fileUrl
+					});
+				} else throw new Error("Merge failed: response.success is false");
+			}
+		} catch (error) {
+			this.status = "error";
+			this.endTime = Date.now();
+			this.eventBus.emit("error", {
+				taskId: this.id,
+				error
+			});
+			throw error;
+		}
+	}
+	/**
+	* Cancels the upload
+	*
+	* Cancels an ongoing or paused upload.
+	* Once cancelled, the upload cannot be resumed.
+	*
+	* @remarks
+	* - Validates: Requirements 6.3 (cancel functionality and lifecycle events)
+	* - Works when status is 'uploading' or 'paused'
+	* - Emits 'cancel' event
+	* - Sets shouldCancelUpload flag to stop ongoing chunk uploads
+	* - Cleans up upload record from IndexedDB
+	* - Status becomes 'cancelled' (terminal state)
+	*
+	* @example
+	* ```typescript
+	* task.on('cancel', () => {
+	*   console.log('Upload cancelled');
+	* });
+	*
+	* task.cancel();
+	* ```
+	*/
+	cancel() {
+		if (this.status !== "uploading" && this.status !== "paused") {
+			console.warn(`Cannot cancel upload: current status is ${this.status}`);
+			return;
+		}
+		this.shouldCancelUpload = true;
+		this.status = "cancelled";
+		this.endTime = Date.now();
+		this.eventBus.emit("cancel", { taskId: this.id });
+		this.cleanupStorage().catch((error) => {
+			console.warn("Failed to cleanup upload storage:", error);
+		});
+	}
+	/**
+	* Cleans up the upload record from IndexedDB
+	*
+	* Removes the upload record to free up storage space.
+	* Called when upload is cancelled or completed.
+	*
+	* @remarks
+	* - Gracefully handles storage errors
+	* - Does not throw errors
+	*
+	* @internal
+	*/
+	async cleanupStorage() {
+		try {
+			if (this.storage.isAvailable()) await this.storage.deleteRecord(this.id);
+		} catch (error) {
+			console.warn("Failed to cleanup storage:", error);
+		}
+	}
+};
+
+//#endregion
+//#region src/upload-manager.ts
+/**
+* UploadManager class
+*
+* Central manager for handling multiple file upload tasks.
+* Provides task lifecycle management, plugin system, and persistent storage.
+*
+* @example
+* ```typescript
+* const manager = new UploadManager({
+*   requestAdapter: myAdapter,
+*   maxConcurrentTasks: 3,
+*   defaultChunkSize: 1024 * 1024, // 1MB
+* });
+*
+* // Initialize (loads unfinished tasks if enabled)
+* await manager.init();
+*
+* // Create and start a task
+* const task = manager.createTask(file);
+* await task.start();
+*
+* // Get all tasks
+* const allTasks = manager.getAllTasks();
+*
+* // Delete a task
+* await manager.deleteTask(task.id);
+* ```
+*/
+var UploadManager = class {
+	/** Map of task ID to UploadTask instances */
+	tasks;
+	/** Manager options with defaults applied */
+	options;
+	/** Storage instance for persistent task data */
+	storage;
+	/** Flag indicating if manager has been initialized */
+	initialized;
+	/** Registered plugins */
+	plugins;
+	/**
+	* Creates a new UploadManager instance
+	*
+	* @param options - Configuration options for the manager
+	*
+	* @remarks
+	* - Validates: Requirement 8.6 (UploadManager manages multiple tasks)
+	* - Applies default values for optional parameters
+	* - Creates storage instance for persistence
+	* - Does not automatically initialize - call init() explicitly
+	*/
+	constructor(options) {
+		this.tasks = /* @__PURE__ */ new Map();
+		this.options = {
+			requestAdapter: options.requestAdapter,
+			maxConcurrentTasks: options.maxConcurrentTasks ?? 3,
+			defaultChunkSize: options.defaultChunkSize ?? 1024 * 1024,
+			defaultConcurrency: options.defaultConcurrency ?? 3,
+			autoResumeUnfinished: options.autoResumeUnfinished ?? true
+		};
+		this.storage = new UploadStorage();
+		this.plugins = [];
+		this.initialized = false;
+	}
+	/**
+	* Registers a plugin with the manager
+	*
+	* Plugins can hook into task lifecycle events to add custom behavior.
+	* Plugins are called in the order they were registered.
+	*
+	* @param plugin - Plugin instance to register
+	*
+	* @remarks
+	* - Validates: Requirement 6.5 (Plugin mechanism)
+	* - Validates: Requirement 8.5 (Plugin system)
+	* - Plugin's install() method is called immediately if provided
+	* - Plugin errors are caught and logged but don't stop execution
+	* - Duplicate plugin names are allowed (no uniqueness check)
+	*
+	* @example
+	* ```typescript
+	* const logger = new LoggerPlugin();
+	* manager.use(logger);
+	*
+	* const stats = new StatisticsPlugin();
+	* manager.use(stats);
+	* ```
+	*/
+	use(plugin) {
+		this.plugins.push(plugin);
+		if (plugin.install) try {
+			plugin.install(this);
+		} catch (error) {
+			console.error(`Plugin "${plugin.name}" install failed:`, error);
+		}
+	}
+	/**
+	* Calls a plugin hook for all registered plugins
+	*
+	* @param hookName - Name of the hook to call
+	* @param args - Arguments to pass to the hook
+	*
+	* @internal
+	*/
+	callPluginHook(hookName, ...args) {
+		for (const plugin of this.plugins) {
+			const hook = plugin[hookName];
+			if (hook && typeof hook === "function") try {
+				hook.apply(plugin, args);
+			} catch (error) {
+				console.error(`Plugin "${plugin.name}" hook "${String(hookName)}" failed:`, error);
+			}
+		}
+	}
+	/**
+	* Initializes the UploadManager
+	*
+	* Performs initialization tasks including:
+	* - Initializing IndexedDB storage
+	* - Loading unfinished tasks if autoResumeUnfinished is enabled
+	*
+	* @remarks
+	* - Validates: Requirement 8.6 (initialization and task management)
+	* - Should be called once before using the manager
+	* - Safe to call multiple times (idempotent)
+	* - Gracefully handles storage initialization failures
+	*
+	* @example
+	* ```typescript
+	* const manager = new UploadManager({ requestAdapter });
+	* await manager.init();
+	* ```
+	*/
+	async init() {
+		if (this.initialized) return;
+		try {
+			await this.storage.init();
+			if (this.options.autoResumeUnfinished) await this.loadUnfinishedTasks();
+			this.initialized = true;
+		} catch (error) {
+			this.initialized = true;
+		}
+	}
+	/**
+	* Creates a new upload task
+	*
+	* Creates an UploadTask instance for the given file and adds it to the manager.
+	* The task is not automatically started - call task.start() to begin upload.
+	*
+	* @param file - File to upload
+	* @param options - Optional task-specific configuration (overrides defaults)
+	* @returns Created UploadTask instance
+	*
+	* @remarks
+	* - Validates: Requirement 8.6 (task creation and management)
+	* - Task is added to the manager's task map
+	* - Uses manager's default options unless overridden
+	* - Task is not started automatically
+	*
+	* @example
+	* ```typescript
+	* const task = manager.createTask(file, {
+	*   chunkSize: 2 * 1024 * 1024, // 2MB
+	*   concurrency: 5,
+	* });
+	*
+	* task.on('progress', ({ progress }) => {
+	*   console.log(`Progress: ${progress}%`);
+	* });
+	*
+	* await task.start();
+	* ```
+	*/
+	createTask(file, options) {
+		const task = new UploadTask({
+			file,
+			requestAdapter: this.options.requestAdapter,
+			chunkSize: options?.chunkSize ?? this.options.defaultChunkSize,
+			concurrency: options?.concurrency ?? this.options.defaultConcurrency,
+			retryCount: options?.retryCount ?? 3,
+			retryDelay: options?.retryDelay ?? 1e3,
+			autoStart: options?.autoStart ?? false
+		});
+		this.tasks.set(task.id, task);
+		this.callPluginHook("onTaskCreated", task);
+		this.setupTaskPluginHooks(task);
+		return task;
+	}
+	/**
+	* Sets up event listeners on a task to call plugin hooks
+	*
+	* @param task - Task to set up listeners for
+	*
+	* @internal
+	*/
+	setupTaskPluginHooks(task) {
+		task.on("start", () => {
+			this.callPluginHook("onTaskStart", task);
+		});
+		task.on("progress", () => {
+			const progressData = task.getProgress();
+			this.callPluginHook("onTaskProgress", task, progressData);
+		});
+		task.on("success", ({ fileUrl }) => {
+			this.callPluginHook("onTaskSuccess", task, fileUrl);
+		});
+		task.on("error", ({ error }) => {
+			this.callPluginHook("onTaskError", task, error);
+		});
+		task.on("pause", () => {
+			this.callPluginHook("onTaskPause", task);
+		});
+		task.on("resume", () => {
+			this.callPluginHook("onTaskResume", task);
+		});
+		task.on("cancel", () => {
+			this.callPluginHook("onTaskCancel", task);
+		});
+	}
+	/**
+	* Gets a task by its ID
+	*
+	* @param taskId - Unique task identifier
+	* @returns UploadTask instance or undefined if not found
+	*
+	* @remarks
+	* - Validates: Requirement 8.6 (task retrieval)
+	*
+	* @example
+	* ```typescript
+	* const task = manager.getTask('task_abc123');
+	* if (task) {
+	*   console.log(`Status: ${task.getStatus()}`);
+	* }
+	* ```
+	*/
+	getTask(taskId) {
+		return this.tasks.get(taskId);
+	}
+	/**
+	* Gets all tasks managed by this manager
+	*
+	* @returns Array of all UploadTask instances
+	*
+	* @remarks
+	* - Validates: Requirement 8.6 (task retrieval)
+	* - Returns a new array (safe to modify)
+	* - Tasks are in insertion order
+	*
+	* @example
+	* ```typescript
+	* const allTasks = manager.getAllTasks();
+	* console.log(`Total tasks: ${allTasks.length}`);
+	*
+	* // Filter by status
+	* const uploadingTasks = allTasks.filter(
+	*   task => task.getStatus() === 'uploading'
+	* );
+	* ```
+	*/
+	getAllTasks() {
+		return Array.from(this.tasks.values());
+	}
+	/**
+	* Deletes a task from the manager
+	*
+	* Cancels the task if it's still running and removes it from the manager.
+	* Also cleans up the task's storage record.
+	*
+	* @param taskId - Unique task identifier
+	*
+	* @remarks
+	* - Validates: Requirement 8.6 (task deletion)
+	* - Cancels the task if it's still running
+	* - Removes task from manager's task map
+	* - Cleans up storage record
+	* - Safe to call even if task doesn't exist
+	*
+	* @example
+	* ```typescript
+	* // Delete a specific task
+	* await manager.deleteTask('task_abc123');
+	*
+	* // Delete all completed tasks
+	* const tasks = manager.getAllTasks();
+	* for (const task of tasks) {
+	*   if (task.getStatus() === 'success') {
+	*     await manager.deleteTask(task.id);
+	*   }
+	* }
+	* ```
+	*/
+	async deleteTask(taskId) {
+		const task = this.tasks.get(taskId);
+		if (task) {
+			const status = task.getStatus();
+			if (status === "uploading" || status === "paused") task.cancel();
+			this.tasks.delete(taskId);
+			try {
+				if (this.storage.isAvailable()) await this.storage.deleteRecord(taskId);
+			} catch (error) {
+				console.warn(`Failed to delete storage record for task ${taskId}:`, error);
+			}
+		}
+	}
+	/**
+	* Loads unfinished tasks from storage
+	*
+	* Retrieves upload records from IndexedDB and creates task placeholders.
+	* Note: Tasks cannot be automatically resumed because File objects cannot
+	* be persisted. Users must re-select files to resume uploads.
+	*
+	* @remarks
+	* - Validates: Requirement 4.2 (read unfinished tasks from IndexedDB)
+	* - Creates task entries in the manager
+	* - Tasks are in 'paused' state and require file re-selection to resume
+	* - Gracefully handles storage errors
+	*
+	* @internal
+	*/
+	async loadUnfinishedTasks() {
+		try {
+			if (!this.storage.isAvailable()) return;
+			await this.storage.getAllRecords();
+		} catch (error) {}
+	}
+	/**
+	* Gets information about unfinished tasks from storage
+	*
+	* Returns metadata about uploads that were not completed in previous sessions.
+	* This allows UI layers to prompt users to resume uploads by re-selecting files.
+	*
+	* @returns Array of unfinished upload records with file metadata
+	*
+	* @remarks
+	* - Validates: Requirement 4.2 (read unfinished tasks from IndexedDB)
+	* - Validates: Requirement 4.3 (provide interface for resuming tasks)
+	* - Returns empty array if storage is unavailable or on error
+	* - File objects cannot be restored - users must re-select files
+	*
+	* @example
+	* ```typescript
+	* const unfinished = await manager.getUnfinishedTasksInfo();
+	* if (unfinished.length > 0) {
+	*   console.log('Found unfinished uploads:');
+	*   unfinished.forEach(record => {
+	*     console.log(`- ${record.fileInfo.name} (${record.uploadedChunks.length} chunks uploaded)`);
+	*   });
+	* }
+	* ```
+	*/
+	async getUnfinishedTasksInfo() {
+		try {
+			if (!this.storage.isAvailable()) return [];
+			return (await this.storage.getAllRecords()).map((record) => ({
+				taskId: record.taskId,
+				fileInfo: {
+					name: record.fileInfo.name,
+					size: record.fileInfo.size,
+					type: record.fileInfo.type,
+					lastModified: record.fileInfo.lastModified
+				},
+				uploadedChunks: record.uploadedChunks,
+				uploadToken: record.uploadToken,
+				createdAt: record.createdAt,
+				updatedAt: record.updatedAt
+			}));
+		} catch (error) {
+			console.warn("Failed to get unfinished tasks info:", error);
+			return [];
+		}
+	}
+	/**
+	* Resumes an unfinished upload task with a re-selected file
+	*
+	* Allows users to resume a previously interrupted upload by providing the
+	* original task ID and re-selecting the file. The method validates that the
+	* file matches the stored metadata and creates a new task that continues
+	* from the last uploaded chunk.
+	*
+	* @param taskId - ID of the unfinished task to resume
+	* @param file - Re-selected file (must match original file metadata)
+	* @param options - Optional task configuration overrides
+	* @returns Created UploadTask instance ready to resume
+	* @throws Error if task record not found or file doesn't match
+	*
+	* @remarks
+	* - Validates: Requirement 4.3 (resume unfinished tasks)
+	* - Validates: Requirement 4.4 (continue from last uploaded chunk)
+	* - Verifies file matches stored metadata (name, size, type, lastModified)
+	* - Creates new task with stored progress
+	* - Removes old storage record and creates new one with same ID
+	*
+	* @example
+	* ```typescript
+	* // Get unfinished tasks
+	* const unfinished = await manager.getUnfinishedTasksInfo();
+	*
+	* // User re-selects file
+	* const file = await selectFile();
+	*
+	* // Resume upload
+	* try {
+	*   const task = await manager.resumeTask(unfinished[0].taskId, file);
+	*   await task.start();
+	* } catch (error) {
+	*   console.error('Failed to resume:', error);
+	* }
+	* ```
+	*/
+	async resumeTask(taskId, file, options) {
+		if (!this.storage.isAvailable()) throw new Error("Storage is not available - cannot resume task");
+		const record = await this.storage.getRecord(taskId);
+		if (!record) throw new Error(`No unfinished task found with ID: ${taskId}`);
+		if (file.name !== record.fileInfo.name) throw new Error(`File name mismatch: expected "${record.fileInfo.name}", got "${file.name}"`);
+		if (file.size !== record.fileInfo.size) throw new Error(`File size mismatch: expected ${record.fileInfo.size}, got ${file.size}`);
+		if (file.type !== record.fileInfo.type) throw new Error(`File type mismatch: expected "${record.fileInfo.type}", got "${file.type}"`);
+		const task = new UploadTask({
+			file,
+			requestAdapter: this.options.requestAdapter,
+			chunkSize: options?.chunkSize ?? this.options.defaultChunkSize,
+			concurrency: options?.concurrency ?? this.options.defaultConcurrency,
+			retryCount: options?.retryCount ?? 3,
+			retryDelay: options?.retryDelay ?? 1e3,
+			autoStart: options?.autoStart ?? false,
+			resumeTaskId: taskId,
+			resumeUploadToken: record.uploadToken,
+			resumeUploadedChunks: record.uploadedChunks
+		});
+		this.tasks.set(task.id, task);
+		this.callPluginHook("onTaskCreated", task);
+		this.setupTaskPluginHooks(task);
+		try {
+			await this.storage.deleteRecord(taskId);
+		} catch (error) {
+			console.warn(`Failed to delete old storage record for task ${taskId}:`, error);
+		}
+		return task;
+	}
+	/**
+	* Clears a specific unfinished task record from storage
+	*
+	* Removes the storage record for an unfinished task without resuming it.
+	* Useful for cleaning up tasks that the user no longer wants to resume.
+	*
+	* @param taskId - ID of the unfinished task to clear
+	*
+	* @remarks
+	* - Validates: Requirement 4.5 (clear saved upload records)
+	* - Safe to call even if record doesn't exist
+	* - Does not affect active tasks in the manager
+	*
+	* @example
+	* ```typescript
+	* // Clear a specific unfinished task
+	* await manager.clearUnfinishedTask('task_abc123');
+	*
+	* // Clear all unfinished tasks
+	* const unfinished = await manager.getUnfinishedTasksInfo();
+	* for (const record of unfinished) {
+	*   await manager.clearUnfinishedTask(record.taskId);
+	* }
+	* ```
+	*/
+	async clearUnfinishedTask(taskId) {
+		try {
+			if (this.storage.isAvailable()) await this.storage.deleteRecord(taskId);
+		} catch (error) {
+			console.warn(`Failed to clear unfinished task ${taskId}:`, error);
+		}
+	}
+	/**
+	* Clears all unfinished task records from storage
+	*
+	* Removes all storage records for unfinished tasks.
+	* Useful for cleaning up when users don't want to resume any uploads.
+	*
+	* @returns Number of records cleared
+	*
+	* @remarks
+	* - Validates: Requirement 4.5 (clear saved upload records)
+	* - Does not affect active tasks in the manager
+	* - Returns 0 if storage is unavailable or on error
+	*
+	* @example
+	* ```typescript
+	* const cleared = await manager.clearAllUnfinishedTasks();
+	* console.log(`Cleared ${cleared} unfinished task(s)`);
+	* ```
+	*/
+	async clearAllUnfinishedTasks() {
+		try {
+			if (!this.storage.isAvailable()) return 0;
+			const count = (await this.storage.getAllRecords()).length;
+			await this.storage.clearAll();
+			return count;
+		} catch (error) {
+			console.warn("Failed to clear all unfinished tasks:", error);
+			return 0;
+		}
+	}
+	/**
+	* Gets the number of tasks in the manager
+	*
+	* @returns Total number of tasks
+	*
+	* @example
+	* ```typescript
+	* console.log(`Total tasks: ${manager.getTaskCount()}`);
+	* ```
+	*/
+	getTaskCount() {
+		return this.tasks.size;
+	}
+	/**
+	* Checks if the manager has been initialized
+	*
+	* @returns True if initialized, false otherwise
+	*
+	* @example
+	* ```typescript
+	* if (!manager.isInitialized()) {
+	*   await manager.init();
+	* }
+	* ```
+	*/
+	isInitialized() {
+		return this.initialized;
+	}
+	/**
+	* Clears all completed tasks from the manager
+	*
+	* Removes tasks with 'success', 'error', or 'cancelled' status.
+	* Does not affect running or paused tasks.
+	*
+	* @returns Number of tasks cleared
+	*
+	* @example
+	* ```typescript
+	* const cleared = await manager.clearCompletedTasks();
+	* console.log(`Cleared ${cleared} completed task(s)`);
+	* ```
+	*/
+	async clearCompletedTasks() {
+		const tasks = this.getAllTasks();
+		let clearedCount = 0;
+		for (const task of tasks) {
+			const status = task.getStatus();
+			if (status === "success" || status === "error" || status === "cancelled") {
+				await this.deleteTask(task.id);
+				clearedCount++;
+			}
+		}
+		return clearedCount;
+	}
+	/**
+	* Pauses all running tasks
+	*
+	* Calls pause() on all tasks with 'uploading' status.
+	*
+	* @returns Number of tasks paused
+	*
+	* @example
+	* ```typescript
+	* const paused = manager.pauseAll();
+	* console.log(`Paused ${paused} task(s)`);
+	* ```
+	*/
+	pauseAll() {
+		const tasks = this.getAllTasks();
+		let pausedCount = 0;
+		for (const task of tasks) if (task.getStatus() === "uploading") {
+			task.pause();
+			pausedCount++;
+		}
+		return pausedCount;
+	}
+	/**
+	* Resumes all paused tasks
+	*
+	* Calls resume() on all tasks with 'paused' status.
+	*
+	* @returns Number of tasks resumed
+	*
+	* @example
+	* ```typescript
+	* const resumed = await manager.resumeAll();
+	* console.log(`Resumed ${resumed} task(s)`);
+	* ```
+	*/
+	async resumeAll() {
+		const tasks = this.getAllTasks();
+		let resumedCount = 0;
+		for (const task of tasks) if (task.getStatus() === "paused") try {
+			await task.resume();
+			resumedCount++;
+		} catch (error) {
+			console.warn(`Failed to resume task ${task.id}:`, error);
+		}
+		return resumedCount;
+	}
+	/**
+	* Cancels all running and paused tasks
+	*
+	* Calls cancel() on all tasks that are not in a terminal state.
+	*
+	* @returns Number of tasks cancelled
+	*
+	* @example
+	* ```typescript
+	* const cancelled = manager.cancelAll();
+	* console.log(`Cancelled ${cancelled} task(s)`);
+	* ```
+	*/
+	cancelAll() {
+		const tasks = this.getAllTasks();
+		let cancelledCount = 0;
+		for (const task of tasks) {
+			const status = task.getStatus();
+			if (status === "uploading" || status === "paused") {
+				task.cancel();
+				cancelledCount++;
+			}
+		}
+		return cancelledCount;
+	}
+	/**
+	* Gets statistics about all tasks
+	*
+	* @returns Object containing task statistics
+	*
+	* @example
+	* ```typescript
+	* const stats = manager.getStatistics();
+	* console.log(`Total: ${stats.total}`);
+	* console.log(`Uploading: ${stats.uploading}`);
+	* console.log(`Success: ${stats.success}`);
+	* ```
+	*/
+	getStatistics() {
+		const tasks = this.getAllTasks();
+		const stats = {
+			total: tasks.length,
+			idle: 0,
+			uploading: 0,
+			paused: 0,
+			success: 0,
+			error: 0,
+			cancelled: 0
+		};
+		for (const task of tasks) switch (task.getStatus()) {
+			case "idle":
+				stats.idle++;
+				break;
+			case "uploading":
+				stats.uploading++;
+				break;
+			case "paused":
+				stats.paused++;
+				break;
+			case "success":
+				stats.success++;
+				break;
+			case "error":
+				stats.error++;
+				break;
+			case "cancelled":
+				stats.cancelled++;
+				break;
+		}
+		return stats;
+	}
+	/**
+	* Closes the manager and cleans up resources
+	*
+	* Cancels all running tasks and closes the storage connection.
+	* The manager should not be used after calling this method.
+	*
+	* @example
+	* ```typescript
+	* // Clean up when done
+	* manager.close();
+	* ```
+	*/
+	close() {
+		this.cancelAll();
+		this.storage.close();
+		this.tasks.clear();
+		this.initialized = false;
+	}
+};
+
+//#endregion
+//#region src/plugins.ts
+/**
+* Logger plugin for debugging and monitoring uploads
+*
+* Logs all task lifecycle events to the console with timestamps.
+* Useful for development and debugging.
+*
+* @remarks
+* - Validates: Requirement 6.5 (Plugin mechanism example)
+* - Validates: Requirement 8.5 (Plugin system example)
+* - Logs to console with timestamps
+* - Can be configured to log only specific events
+*
+* @example
+* ```typescript
+* const manager = new UploadManager({ requestAdapter });
+* manager.use(new LoggerPlugin());
+*
+* // With custom options
+* manager.use(new LoggerPlugin({
+*   logProgress: false, // Don't log progress updates
+*   prefix: '[Upload]'  // Custom log prefix
+* }));
+* ```
+*/
+var LoggerPlugin = class {
+	name = "logger";
+	options;
+	constructor(options) {
+		this.options = {
+			logProgress: options?.logProgress ?? true,
+			logStart: options?.logStart ?? true,
+			logSuccess: options?.logSuccess ?? true,
+			logError: options?.logError ?? true,
+			logPause: options?.logPause ?? true,
+			logResume: options?.logResume ?? true,
+			logCancel: options?.logCancel ?? true,
+			prefix: options?.prefix ?? "[LoggerPlugin]"
+		};
+	}
+	log(message, ...args) {
+		const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+		console.log(`${this.options.prefix} [${timestamp}]`, message, ...args);
+	}
+	install() {
+		this.log("Plugin installed");
+	}
+	onTaskCreated(task) {
+		this.log(`Task created: ${task.id}`, {
+			fileName: task.file.name,
+			fileSize: task.file.size,
+			fileType: task.file.type
+		});
+	}
+	onTaskStart(task) {
+		if (this.options.logStart) this.log(`Task started: ${task.id}`, { fileName: task.file.name });
+	}
+	onTaskProgress(task, progress) {
+		if (this.options.logProgress) this.log(`Task progress: ${task.id}`, {
+			percentage: `${progress.percentage.toFixed(2)}%`,
+			uploadedBytes: progress.uploadedBytes,
+			totalBytes: progress.totalBytes,
+			speed: `${(progress.speed / 1024 / 1024).toFixed(2)} MB/s`,
+			remainingTime: `${progress.remainingTime.toFixed(0)}s`
+		});
+	}
+	onTaskSuccess(task, fileUrl) {
+		if (this.options.logSuccess) this.log(`Task completed: ${task.id}`, {
+			fileName: task.file.name,
+			fileUrl
+		});
+	}
+	onTaskError(task, error) {
+		if (this.options.logError) this.log(`Task error: ${task.id}`, {
+			fileName: task.file.name,
+			error: error.message,
+			stack: error.stack
+		});
+	}
+	onTaskPause(task) {
+		if (this.options.logPause) this.log(`Task paused: ${task.id}`, { fileName: task.file.name });
+	}
+	onTaskResume(task) {
+		if (this.options.logResume) this.log(`Task resumed: ${task.id}`, { fileName: task.file.name });
+	}
+	onTaskCancel(task) {
+		if (this.options.logCancel) this.log(`Task cancelled: ${task.id}`, { fileName: task.file.name });
+	}
+};
+/**
+* Statistics plugin for tracking upload metrics
+*
+* Collects statistics about uploads including success/error counts,
+* total bytes uploaded, average speed, etc.
+*
+* @remarks
+* - Validates: Requirement 6.5 (Plugin mechanism example)
+* - Validates: Requirement 8.5 (Plugin system example)
+* - Tracks upload statistics in memory
+* - Provides methods to retrieve and reset statistics
+* - Thread-safe for concurrent uploads
+*
+* @example
+* ```typescript
+* const stats = new StatisticsPlugin();
+* manager.use(stats);
+*
+* // Later, get statistics
+* const metrics = stats.getStats();
+* console.log(`Success rate: ${metrics.successRate}%`);
+* console.log(`Total uploaded: ${metrics.totalBytesUploaded} bytes`);
+* console.log(`Average speed: ${metrics.averageSpeed} bytes/s`);
+* ```
+*/
+var StatisticsPlugin = class {
+	name = "statistics";
+	stats = {
+		totalFiles: 0,
+		successCount: 0,
+		errorCount: 0,
+		cancelledCount: 0,
+		totalBytesUploaded: 0,
+		totalUploadTime: 0,
+		startTimes: /* @__PURE__ */ new Map()
+	};
+	install() {}
+	onTaskCreated(_task) {
+		this.stats.totalFiles++;
+	}
+	onTaskStart(task) {
+		this.stats.startTimes.set(task.id, Date.now());
+	}
+	onTaskSuccess(task, _fileUrl) {
+		this.stats.successCount++;
+		this.stats.totalBytesUploaded += task.file.size;
+		const startTime = this.stats.startTimes.get(task.id);
+		if (startTime) {
+			const uploadTime = Date.now() - startTime;
+			this.stats.totalUploadTime += uploadTime;
+			this.stats.startTimes.delete(task.id);
+		}
+	}
+	onTaskError(task, _error) {
+		this.stats.errorCount++;
+		this.stats.startTimes.delete(task.id);
+	}
+	onTaskCancel(task) {
+		this.stats.cancelledCount++;
+		this.stats.startTimes.delete(task.id);
+	}
+	/**
+	* Gets current statistics
+	*
+	* @returns Object containing upload statistics
+	*
+	* @example
+	* ```typescript
+	* const stats = plugin.getStats();
+	* console.log(`Success rate: ${stats.successRate}%`);
+	* ```
+	*/
+	getStats() {
+		const completedCount = this.stats.successCount + this.stats.errorCount + this.stats.cancelledCount;
+		const averageSpeed = this.stats.totalUploadTime > 0 ? this.stats.totalBytesUploaded / this.stats.totalUploadTime * 1e3 : 0;
+		const averageUploadTime = this.stats.successCount > 0 ? this.stats.totalUploadTime / this.stats.successCount : 0;
+		const successRate = completedCount > 0 ? this.stats.successCount / completedCount * 100 : 0;
+		const errorRate = completedCount > 0 ? this.stats.errorCount / completedCount * 100 : 0;
+		return {
+			totalFiles: this.stats.totalFiles,
+			successCount: this.stats.successCount,
+			errorCount: this.stats.errorCount,
+			cancelledCount: this.stats.cancelledCount,
+			totalBytesUploaded: this.stats.totalBytesUploaded,
+			averageSpeed,
+			averageUploadTime,
+			successRate,
+			errorRate
+		};
+	}
+	/**
+	* Resets all statistics to zero
+	*
+	* @example
+	* ```typescript
+	* plugin.reset();
+	* ```
+	*/
+	reset() {
+		this.stats = {
+			totalFiles: 0,
+			successCount: 0,
+			errorCount: 0,
+			cancelledCount: 0,
+			totalBytesUploaded: 0,
+			totalUploadTime: 0,
+			startTimes: /* @__PURE__ */ new Map()
+		};
+	}
+	/**
+	* Gets a formatted summary of statistics
+	*
+	* @returns Human-readable statistics summary
+	*
+	* @example
+	* ```typescript
+	* console.log(plugin.getSummary());
+	* // Output:
+	* // Upload Statistics:
+	* //   Total Files: 10
+	* //   Success: 8 (80.00%)
+	* //   Errors: 1 (10.00%)
+	* //   Cancelled: 1 (10.00%)
+	* //   Total Uploaded: 52.43 MB
+	* //   Average Speed: 2.15 MB/s
+	* //   Average Time: 24.5s
+	* ```
+	*/
+	getSummary() {
+		const stats = this.getStats();
+		const formatBytes = (bytes) => {
+			return `${(bytes / 1024 / 1024).toFixed(2)} MB`;
+		};
+		const formatSpeed = (bytesPerSecond) => {
+			return `${(bytesPerSecond / 1024 / 1024).toFixed(2)} MB/s`;
+		};
+		const formatTime = (ms) => {
+			return `${(ms / 1e3).toFixed(1)}s`;
+		};
+		return `Upload Statistics:
+  Total Files: ${stats.totalFiles}
+  Success: ${stats.successCount} (${stats.successRate.toFixed(2)}%)
+  Errors: ${stats.errorCount} (${stats.errorRate.toFixed(2)}%)
+  Cancelled: ${stats.cancelledCount}
+  Total Uploaded: ${formatBytes(stats.totalBytesUploaded)}
+  Average Speed: ${formatSpeed(stats.averageSpeed)}
+  Average Time: ${formatTime(stats.averageUploadTime)}`;
+	}
+};
+
+//#endregion
+export { ChunkSizeAdjuster, CongestionState, LoggerPlugin, StatisticsPlugin, TCPChunkSizeAdjuster, UploadManager, UploadTask };
+//# sourceMappingURL=index.mjs.map