README.md

ngx-uploadx

Angular Resumable Upload Module

Key Features

• Pause / Resume / Cancel Uploads
• Retries using exponential back-off strategy
• Chunking

Setup

• Add ngx-uploadx module as dependency :

  npm install ngx-uploadx

• Import UploadxModule:

//...
import { UploadxModule } from 'ngx-uploadx';

@NgModule({
  imports: [
    UploadxModule,
   // ...
});

Basic usage

// Component code
//...
import { Observable } from 'rxjs';
import { UploadxOptions, UploadState } from 'ngx-uploadx';

@Component({
  selector: 'app-home',
  templateUrl: `
  <input type="file" [uploadx]="options" (uploadxState)="onUpload($event)">
  `
})
export class AppHomeComponent {
  options: UploadxOptions = { endpoint: `[URL]` };
  onUpload(state: Observable<UploadState>) {
    state.subscribe((item: UploadState) => {
      console.log(item);
      //...
    });
  }
}

Please navigate to the src/app sub-folder for more detailed examples

Server-side setup

• node-uploadx
• tus-node-server
• tusd

Options

• allowedTypes: Allowed file types (directive only)

• multiple: Allow to select multiple files. Default value: true

• autoUpload: Auto start upload when files added. Default value: true

• chunkSize: Set a fixed chunk size. If not specified, the optimal size will be automatically adjusted based on the network speed.

• concurrency: Set the maximum parallel uploads. Default value: 2

• headers: Headers to be appended to each HTTP request

• metadata: Custom uploads metadata

• uploaderClass: Upload API implementation. Built-in: Uploaderx(default), Tus. More examples.

• token: Authorization token as a string or function returning a string or Promise<string>

• endpoint: URL to create new uploads. Default value: '/upload'

Directives

<div>
  <label class="file-drop" uploadxDrop>
    <input
      type="file"
      [uploadx]="options"
      [uploadxAction]="control"
      (uploadxState)="onUpload($event)"
    />
  </label>
</div>

uploadx

File input directive

• [uploadx]: UploadxOptions

  Set directive options

• [uploadxAction]: UploadxControlEvent

  Control the uploads

• (uploadxState): ($event: <Observable>UploadState)=> void

uploadxDrop

File drop directive. 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`,
    token:  () => localStorage.getItem('access_token'),
    uploaderClass: Tus
  };
  ngOnInit() {
    this.uploadService.init(this.uploadxOptions)
      .subscribe((item: UploadState) => {
        console.log(item);
        //...
      }
  }

• 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`,
      token:  () => localStorage.getItem('access_token'),
    }
    constructor(private uploadService: UploadxService) {
      this.uploads$ = this.uploadService.connect(this.options);
    }

• disconnect(): void

  Terminate all uploads and clears the queue

• handleFile(file: File, options?: UploadxOptions): void

  Create Uploader for the file and add to the queue

• handleFileList(fileList: FileList, options?: UploadxOptions): void

  Add files 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 });
  }

• queue: Uploader[]

  Uploaders array

• events: Observable<UploadState>

  Unloads status events

Run demo

• Start server npm run server
• Run demo app 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)