feat(uploader): add chunked file upload

[lexasq]

Adds opt-in chunked uploads through a new ChunkedFileUploader class. This is a fresh implementation on the current codebase, building on the idea and API from #977. Thanks @PauloPeres, who is credited as co-author.

Closes #880, closes #435.

Apps that don't use the new class are not affected. FileItem is unchanged. In FileUploader, form building and request setup move unchanged into two protected helpers (_buildFormData, _openRequest) that ChunkedFileUploader reuses; a new request spec passes on both the old and the new FileUploader.

Usage

const uploader = new ChunkedFileUploader({
  url: '/api/upload',
  chunkSize: 2 * 1024 * 1024, // 2 MB per request
});

// optional: send the remaining chunks to an upload id returned by the server
uploader.onSuccessChunk = (item, chunk, response) => {
  item.url = `/api/upload/${JSON.parse(response).id}`;
};

// optional: the app decides whether and when to retry
const retries = new Map<FileItem, number>();
uploader.onErrorItem = (item, response, status) => {
  const count = retries.get(item) ?? 0;
  if (status >= 500 && count < 3) {
    retries.set(item, count + 1);
    setTimeout(() => uploader.resumeItem(item), 1000);
  }
};

Behaviour

• Drop-in: it extends FileUploader, so it works with ng2FileSelect / ng2FileDrop and all existing options and callbacks. Without chunkSize it behaves exactly like FileUploader.
• Requests: multipart requests send each chunk as the file field, keeping the file's MIME type, preceded by chunkIndex and totalChunks fields. Their names can be changed with chunkIndexParam and totalChunksParam. With disableMultipart, raw chunks are sent with a Content-Range header, unless the app sets one itself.
• Hooks:
  • onBeforeUploadChunk(item, chunk) runs before each chunk request.
  • onSuccessChunk(item, chunk, response, status, headers) runs after each successful chunk. Changing item.url, item.method or item.headers here applies to the next chunk.
  • onErrorChunk(item, chunk, response, status, headers) runs when a chunk fails. The item then fails as usual and no more chunks are sent.
• Retries are up to the app. The library doesn't retry or delay anything itself; resumeItem(item) uploads a failed or cancelled item again, starting from the chunk that didn't complete. Failed items must stay in the queue, so retrying needs removeAfterUpload off. Each attempt reports the item again (onErrorItem, onCompleteItem, onCompleteAll).
• Cancel: item.cancel() stops the remaining chunks, whether called during a request or from a hook. It has no effect once the last chunk has completed, and an item whose chunk failed stays failed.
• Callbacks that throw: if a chunk callback throws, the item fails with status 0 instead of stalling the queue, and the error is rethrown.
• Callbacks per file and per chunk: onSuccessItem, onErrorItem and onCompleteItem fire once per file. onBuildItemForm and uploader.response fire once per chunk request.
• Progress is reported across the whole file.
• Chunk size is read once per upload.

Testing

• chunked-file-uploader.class.spec.ts (41 tests) and file-uploader-request.spec.ts (7 tests, also passing against the previous FileUploader). The existing FileUploader specs pass unchanged. Lint, build, the demo build and all 76 library tests pass.
• Manually checked in the demo against a local server: multipart and raw mode, an app-driven retry with resumeItem after a 500, and cancel between chunks.

[github-actions]

Visit the preview URL for this PR (updated for commit ea46813):

https://ngx-file-upload--pr1303-feat-chunked-upload-vqu3xksn.web.app

_{(expires Thu, 08 Oct 2026 16:02:28 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: f15ad3fba241d6d58091ac579c27208d04d4562f}