README
ngx-uploadx
Angular Resumable Upload Module
Key Features
- Pause / Resume / Cancel Uploads
- Retries using exponential back-off strategy
- Chunking
Basic usage
- Add ngx-uploadx module as dependency:
npm install ngx-uploadx
- Import UploadxModule:
//...
import { UploadxModule } from 'ngx-uploadx';
@NgModule({
imports: [
UploadxModule,
// ...
});
- Add
uploadx
directive to the component template and provide the required options:
// Component code
//...
import { UploadxOptions, UploadState } from 'ngx-uploadx';
@Component({
selector: 'app-home',
templateUrl: `
<input type="file" [uploadx]="options" (state)="onUpload($event)">
`
})
export class AppHomeComponent {
options: UploadxOptions = { endpoint: `[URL]` };
onUpload(state: UploadState) {
console.log(state);
//...
}
}
Please navigate to the src/app sub-folder for more detailed examples.
Server-side setup
API
UploadxOptions
allowedTypes
Allowed file types (directive only)authorize
Function used to authorize requests (example)autoUpload
Auto start upload when files added. Default value:true
storeIncompleteHours
Limit upload lifetime. Default value:24
chunkSize
Fixed chunk size. If not specified, the optimal size will be automatically adjusted based on the network speed. If set to0
, normal unloading will be used instead of chunkedmaxChunkSize
Dynamic chunk size limitconcurrency
Set the maximum parallel uploads. Default value:2
endpoint
URL to create new uploads. Default value:'/upload'
responseType
Expected server response typeheaders
Headers to be appended to each HTTP requestmetadata
Custom metadata to be added to the uploaded filesmultiple
Allow selecting multiple files. Default value:true
(directive only)prerequest
Function called before every request (example)retryConfig
Object to configure retry settings:maxAttempts
Maximum number of retry attempts. Default value:8
shouldRestartCodes
Upload not exist and will be restarted. Default value:[404, 410]
authErrorCodes
If one of these codes is received, the request will be repeated with an updated authorization token. Default value:[401]
shouldRetryCodes
Retryable 4xx status codes. Default value:[423, 429]
shouldRetry
Overrides the built-in function that determines whether the operation should be retriedminDelay
Minimum (initial) retry interval. Default value:500
maxDelay
Maximum retry interval. Default value:50_000
onBusyDelay
Delay used between retries for non-error responses with missing range/offsettimeout
Time interval after which unfinished requests must be retried
token
Authorization token as astring
or function returning astring
orPromise<string>
uploaderClass
Upload API implementation. Built-in:UploaderX
(default),Tus
. More examples
UploadxModule
Adds directives and provide static method withConfig
for global configuration (example).
:bulb: No need to import
UploadxModule
if you do not use theuploadx
oruploadxDrop
directives in your application.
Directives
<div uploadxDrop>
<label class="file-drop">
<input type="file" [uploadx]="options" [control]="control" (state)="onState($event)" />
</label>
</div>
uploadx
File input directive.
selectors: [uploadx]
, uploadx
Properties:
@Input() uploadx: UploadxOptions
Set directive options@Input() options: UploadxOptions
Alias foruploadx
property@Input() control: UploadxControlEvent
Control the uploads@Output() state: EventEmitter<UploadState>
Event emitted on upload state change
uploadxDrop
File drop directive.
selector: uploadxDrop
:bulb: Activates the
.uploadx-drop-active
class on DnD operations.
UploadxService
init(options?: UploadxOptions): Observable<UploadState>
Initializes service. Returns Observable that emits a new value on progress or status changes.
// @example: uploadxOptions: UploadxOptions = { concurrency: 4, endpoint: `${environment.api}/upload`, uploaderClass: Tus }; ngOnInit() { this.uploadService.init(this.uploadxOptions) .subscribe((state: UploadState) => { console.log(state); // ... } }
connect(options?: UploadxOptions): Observable<Uploader[]>
Initializes service. Returns Observable that emits the current queue.
// @example: @Component({ template: ` <input type="file" uploadx"> <div *ngFor="let item of uploads$ | async">{{item.name}}</div> `, changeDetection: ChangeDetectionStrategy.OnPush }) export class UploadsComponent { uploads$: Observable<Uploader[]>; options: UploadxOptions = { endpoint: `${environment.api}/upload?uploadType=uploadx`, headers: { 'ngsw-bypass': 1 } } constructor(private uploadService: UploadxService) { this.uploads$ = this.uploadService.connect(this.options); }
disconnect(): void
Terminate all uploads and clears the queue.
ngOnDestroy(): void
Called when the service instance is destroyed. Interrupts all uploads and clears the queue and subscriptions.
:bulb: Normally
ngOnDestroy()
is never called becauseUploadxService
is an application-wide service, and uploading will continue even after the upload component is destroyed.handleFiles(files: FileList | File | File[], options = {} as UploadxOptions): void
// @example: onFilesSelected(): void { this.uploadService.handleFiles(this.fileInput.nativeElement.files); }
Creates uploaders for files and adds them to the upload queue.
control(event: UploadxControlEvent): void
Uploads control.
// @example: pause(uploadId?: string) { this.uploadService.control({ action: 'pause', uploadId }); } setToken(token: string) { this.uploadService.control({ token }); }
request<T = string>(config: AjaxRequestConfig): Promise<AjaxResponse<T>>
Make HTTP request with
axios
like interface. (example)state(): UploadState[]
Returns the current state of uploads.
constructor(private uploadService: UploadxService) { // restore background uploads this.uploads = this.uploadService.state(); }
queue: Uploader[]
Uploaders array.
// @example: export class UploadComponent { state: UploadState; options: UploadxOptions = { concurrency: 1, multiple: false, endpoint: `${environment.api}/upload`, } constructor(private uploadService: UploadxService) { this.state = this.uploadService.queue[0] || {}; }
events: Observable<UploadState>
Uploads state events.
DI tokens
UPLOADX_FACTORY_OPTIONS
: override default configurationUPLOADX_OPTIONS
: global optionsUPLOADX_AJAX
: override internal ajax lib
Run demo
- Run script
npm start
- Navigate to
http://localhost:4200/
Build
Run npm run build
to build the lib.
packaged by ng-packagr
Contributing
Pull requests are welcome!
References
- https://developers.google.com/drive/api/v3/manage-uploads#resumable
- https://github.com/tus/tus-resumable-upload-protocol/blob/master/protocol.md
License
The MIT License (see the LICENSE file for the full text)