@akanass/rx-file-upload

v2.3.0

Published

3 years ago

Library to upload a file in the browser and send it fully or in several chunks to the server.

Downloads

0High
0Medium
0Low

Browser FormData File Chunks Upload Streams Async RxJS ReactiveX Observable Observer Subject ES2015 ES2016 ES2017 ES2018 ES2019 ES2020 ESNEXT ES5 ESM Typescript

Rx-File-Upload

Library to upload a file in the browser and send it fully or in several chunks to the server.

All the implementation is done in Typescript and is based on the latest version of RxJS.

This library can only be used in browsers because its functionalities are based on specific elements such as FormData and XMLHttpRequest.

However, we provide a method that will allow you to easily verify if you are in a compatible environment before performing your treatments. This can be very useful in the case of components rendered on the server side (SSR).

Installation

This package is available on npm:

$> npm install @akanass/rx-file-upload rxjs

or 

$> yarn add @akanass/rx-file-upload rxjs

UMD

This package can also be installed via unpkg by including the following script in your page's <head> element. The library's methods will be available on the global RxFileUploadUnPkg object.

<script src="https://unpkg.com/@akanass/rx-file-upload"></script>

Usage

You must first have an HTML file containing an input of type file.

In our example, we will allow the selection of several PDF type files or any image:

<input id="input-file" type="file" accept="application/pdf,image/*" multiple />

Then, in your Typescript file, you can use the library like this:

// import library elements
import { rxFileUpload, RxFileUpload, RxFileUploadError, RxFileUploadProgressData, RxFileUploadResponse } from '@akanass/rx-file-upload';
import { Subscription } from 'rxjs';

// create variables to store rxjs subscriptions
let progressSubscription: Subscription;
let uploadSubscription: Subscription;

// get HTML element
const inputFile: HTMLInputElement = document.querySelector(
  '#input-file',
);

// set listener to clean previous files selection
inputFile.addEventListener(
  'click',
  (e: Event) => (e.target['value'] = null),
);

// set listener to upload files
inputFile.addEventListener('change', (e: Event) => {
  // get file list
  const fileList: FileList = e.target['files'];

  // build files array
  const files: Files[] = Array.from(
    { length: fileList.length },
    (_, idx: number) => idx++,
  ).map((i: number) => fileList.item(i));

  // delete previous subscriptions to memory free
  if (!!uploadSubscription) {
    uploadSubscription.unsubscribe();
  }
  if (!!progressSubscription) {
    progressSubscription.unsubscribe();
  }

  // create new instance of RxFileUpload
  const manager: RxFileUpload = rxFileUpload({
    url: 'http://my_api.com/upload'
  });

  // listen on progress to update UI
  progressSubscription = manager.progress$.subscribe({
    next: (_: RxFileUploadProgressData) => {
      // log progress data in the console
      console.log(_);
      // do some UI update based on progress data 
      // updateProgressUI(_);
    },
    complete: () => console.log('PROGRESS ALL FILES COMPLETED'),
  });

  // upload file
  uploadSubscription = manager
    .upload<any>(files)
    .subscribe({
      next: (_: RxFileUploadResponse<any>) => {
        // log server answer in the console
        console.log(_);
        // do some UI update based on server data 
        // updateUI(_);
      },
      error: (e: RxFileUploadError | Error) => {
        // display error in the console
        console.error(e);
        // do some UI update based on error data 
        // updateUIWithError(e);
      },
      complete: () => console.log('UPLOAD ALL FILES COMPLETED'),
    });
});

You just have to compile your file and insert it in a script tag of your HTML and you're done.

Of course, you can use JavaScript language to create your script file but in this case the types will not be available as in the previous example and you will just have to import the method allowing to create the instance of the library.

import { rxFileUpload } from '@akanass/rx-file-upload';

To have a real implementation and test of this library, go to this project.

API in Details

`rxFileUpload(config)`

Create a new instance of RxFileUpload. An error will be thrown if you aren't in a browser environment.

Parameter:

{RxFileUploadConfig} config: object with only url member required.

Return:

{RxFileUpload} new instance of RxFileUpload with the given configuration.

Example:

import { rxFileUpload, RxFileUpload } from '@akanass/rx-file-upload';

// create new instance of RxFileUpload
const manager: RxFileUpload = rxFileUpload({
  url: 'http://my_api.com/upload'
});

`.progress$`

Progress Observable which streams progress data for each file(s)/chunk(s) uploaded.

Return:

{Observable<RxFileUploadProgressData>} the Observable which streams progress data RxFileUploadProgressData for each file(s)/chunk(s) uploaded.

Example:

import { rxFileUpload, RxFileUpload, RxFileUploadProgressData } from '@akanass/rx-file-upload';

// create new instance of RxFileUpload
const manager: RxFileUpload = rxFileUpload({
  url: 'http://my_api.com/upload'
});

// subscribe to progress stream
manager.progress$.subscribe({
  next: (_: RxFileUploadProgressData) => {
    // log progress data in the console
    console.log(_);
    // do some UI update based on progress data 
    // updateProgressUI(_);
  },
  complete: () => console.log('PROGRESS ALL FILES COMPLETED'),
});

`.upload<T>(oneFileOrMultipleFiles[,additionalFormData])`

Function to upload one or multiple files, with or without chunks, to the server with optional additional data and returns the Observable which streams the response from the server after each file has been uploaded.

NOTES:
This function will do a POST request to the server by default. Only POST and PUT requests are allowed. See RxFileUploadConfig to change the method.
For each uploaded file, a unique identifier will be inserted in the X-RxFileUpload-ID header and in the rxFileUploadId attribute of the FormData in order to be able to trace the transaction. This unique value will be present in all new requests and will be, of course, the same when sending the file in several chunks. You can therefore associate them easily with their main file without having to look at the additional data inserted in the FormData.

Parameters:

{File | File[]} oneFileOrMultipleFiles (required): the file(s) to upload to the server.
{RxFileUploadAdditionalFormData} additionalFormData (optional): object representing additional data added in the FormData before sending to the server.

Return:

{Observable<RxFileUploadResponse<T>>} the Observable which streams the response RxFileUploadResponse<T>, from the server, after each file has been uploaded. <T> is a generic value that corresponds to the type of the response sent by the server.

Example:

import { rxFileUpload, RxFileUpload, RxFileUploadResponse, RxFileUploadError } from '@akanass/rx-file-upload';

// create new instance of RxFileUpload
const manager: RxFileUpload = rxFileUpload({
  url: 'http://my_api.com/upload'
});

// subscribe to upload stream
manager.upload<any>(files)
  .subscribe({
    next: (_: RxFileUploadResponse<any>) => {
      // log server answer in the console
      console.log(_);
      // do some UI update based on server data 
      // updateUI(_);
    },
    error: (e: RxFileUploadError | Error) => {
      // display error in the console
      console.error(e);
      // do some UI update based on error data 
      // updateUIWithError(e);
    },
    complete: () => console.log('UPLOAD ALL FILES COMPLETED'),
});

Data sent in the FormData

The data sent to the server will be included in a FormData object of which here are the details:

// data object built and inserted in a FormData object
const data: any = {
  rxFileUploadId: [string], // unique identifier used to identify a transaction. This value is the same as in the `X-RxFileUpload-ID` header.
  fileData: {
    name: [File.name], // name property of the current file to upload
    size: [File.size], // size property of the current file to upload
    lastModified: [File.lastModified], // lastModified property of the current file to upload
    type: [File.type], // type property of the current file to upload
    sha256Checksum?: [checksum] // generated only if config.addChecksum === true
  },
  [additionalFormData.fieldName]?: [additionalFormData.data], // generated only if `additionalFormData` object is passed in parameter of the upload method
  chunkData?: { // generated only if config.useChunks === true
    name: [`${File.name}.part${chunkData.sequence}`], // name property of the current chunk to upload which is the current `File.name` suffixed by `.partX` with `X` the value of the current sequence 
    size: [chunkData.endByte - chunkData.startByte], // size property of the current chunk to upload which is a helper to avoid the calculation of `endByte - startByte`
    lastModified: [File.lastModified], // lastModified property of the current chunk to upload which is the same than the file itself
    type: 'application/octet-stream', // type property of the current chunk to upload which is only a binary part of the full file
    sequence: [number], // the current chunk number
    totalChunks: [number], // the total number of chunks
    startByte: [number], // the start byte number of the chunk
    endByte: [number] // the end byte number of the chunk
  },
  file: [File], // the file object to upload which is the binary data. For a file upload, it's the file itself and for chunks upload, it's a new instance of the File object for each individual chunk: `new File([File.slice(chunkData.startByte, chunkData.endByte)], chunkData.name, {type: chunkData.type, lastModified: chunkData.lastModified})`
};

// FormData instance
const formData = new FormData();

formData.append('rxFileUploadId', data.rxFileUploadId);
formData.append('fileData', JSON.stringify(data.fileData));
formData.append('[additionalFormData.fieldName]', JSON.stringify(data['[additionalFormData.fieldName]'])); // optional
formData.append('chunkData', JSON.stringify(data.chunkData)); // optional
formData.append('file', data.file);

`supportsRxFileUpload()`

Method that will allow you to easily verify if you are in a compatible environment before performing your treatments.

This can be very useful in the case of components rendered on the server side (SSR).

This method is called when you instantiate RxFileUpload and throw an error if you can't use the library.

Return:

{boolean} the flag to know if we can use RxFileUpload library.

Example:

import { supportsRxFileUpload } from '@akanass/rx-file-upload';

// check if the library is supported
if (!!supportsRxFileUpload()) {
  // then do your stuff
}

Types in Details

RxFileUpload:

Represents the instance of the object to upload file to the server. This is the main type of the library.

{Observable<RxFileUploadProgressData>} .progress$: the Observable which streams progress data RxFileUploadProgressData for each file(s)/chunk(s) uploaded.
{Observable<RxFileUploadResponse<T>>} .upload<T>(oneFileOrMultipleFiles: File | File[], additionalFormData?: RxFileUploadAdditionalFormData): the function to upload file to the server and returns the Observable which streams the response RxFileUploadResponse<T>, from the server, after each file has been uploaded.

RxFileUploadConfig:

Represents the object to configure a new instance of RxFileUpload with the rxFileUpload(config) method.

{string} url (required): The address of the resource to request via HTTP. An error will be thrown if you don't provide it.
{string} method (optional): The HTTP Method to use for the request. Only POST and PUT are allowed. (default: POST).
{Readonly<Record<string, any>>} headers (optional): The HTTP headers to apply. NOTE: Content-Type header must not be included because it will be automatically added by the library with the good value.
{number} timeout (optional): The time to wait before causing the underlying XMLHttpRequest to timeout. (default: 0, which is idiomatic for never timeout).
{string} user (optional): The user credentials username to send with the HTTP request. (default: undefined).
{string} password (optional): The user credentials password to send with the HTTP request. (default: undefined).
{boolean} crossDomain (optional): Whether to send the HTTP request as a CORS request. (default: false).
{boolean} withCredentials (optional): To send user credentials in a CORS request, set to true. To exclude user credentials from a CORS request, OR when cookies are to be ignored by the CORS response, set to false. (default: false).
{string} xsrfCookieName (optional): The name of your site's XSRF cookie. (default: undefined).
{string} xsrfHeaderName (optional): The name of a custom header that you can use to send your XSRF cookie. (default: undefined).
{XMLHttpRequestResponseType} responseType (optional): Can be set to change the response type. Valid values are "arraybuffer", "blob", "document", "json", and "text". Note that the type of "document" (such as an XML document) is ignored if the global context is not Window. (default: "json").
{string | URLSearchParams | Record<string, string | number | boolean | string[] | number[] | boolean[]> | [string, string | number | boolean | string[] | number[] | boolean[]][]} queryParams (optional): Query string parameters to add to the URL in the request. (This will require a polyfill for URL and URLSearchParams in Internet Explorer!). Accepts either a query string, a URLSearchParams object, a dictionary of key/value pairs, or an array of key/value entry tuples. (Essentially, it takes anything that new URLSearchParams would normally take). If, for some reason you have a query string in the url argument, this will append to the query string in the url, but it will also overwrite the value of any keys that are an exact match. In other words, an url of /test?a=1&b=2, with queryParams of { b: 5, c: 6 } will result in a url of roughly /test?a=1&b=5&c=6. (default: undefined).
{boolean} useChunks (optional): The flag to indicate if the file(s) should be split into several chunks before sending to the server and not sending the full file. (default: false).
{number} chunkSize (optional): The size in bytes of a chunk. The size of a chunk must be a multiple of 1024 bytes (1 Kb) else an error will be thrown when the library is instantiated. (default: 1048576 (1 Mb)).
{boolean} addChecksum (optional): The flag to indicate if the file(s) sha256 checksum should be calculated before sending to the server. However, you should know that the larger the file, the longer the generation time will be, which will cause a delay before sending it to the server. (default: false).
{boolean} disableProgressCompletion (optional): The flag to indicate if the .progress$ Observable completion will be disabled at the end of the upload process. If you want to keep the same instance of RxFileUpload and use the .upload<T>(oneFileOrMultipleFiles[,additionalFormData]) method several times without having to subscribe again to the .progress$ Observable, you must therefore deactivate its completion. (default: false).

RxFileUploadAdditionalFormData:

Represents the object to add additional data inside the FormData before sending the file(s) to the server with the .upload<T>(oneFileOrMultipleFiles[,additionalFormData]) method.

{string} fieldName (required): The key of the FormData key/pair data - Read-Only.
{string | object} data (required): The value of the FormData key/pair data - Read-Only. This value will be automatically serialized, if it's an object, with a JSON.stringify().

RxFileUploadProgressData:

Represents the object sent by the progress Observable when subscribing to the .progress$ attribute.

{number} progress (required): The current progress value for the upload of a file - Read-Only. It does not matter if the file is sent totally or in chunks, the value of progress will be calculated according to the type of send.
{number} fileIndex (optional): The file index in the array of files for a multiple files upload - Read-Only. (default: undefined).

RxFileUploadResponse<T>:

Represents the response, from the server, streamed by the Observable, after each file has been uploaded, when subscribing to the .upload<T>(oneFileOrMultipleFiles[,additionalFormData]) method. <T> is a generic value that corresponds to the type of the response sent by the server.

{number} status (required): The HTTP status code - Read-Only.
{T} response (required): The response data, if any. Note that this will automatically be converted to the proper type - Read-Only.
{Record<string, string>} responseHeaders (required): A dictionary of the response headers - Read-Only.
{number} fileIndex (optional): The file index in the array of files for a multiple files upload - Read-Only. (default: undefined).

RxFileUploadError:

Represents the error response, from the server, streamed by the Observable, during each file upload, when subscribing to the .upload<T>(oneFileOrMultipleFiles[,additionalFormData]) method.

{number} status (required): The HTTP status code, if the request has completed. If not, it is set to 0.
{any} response (required): The error response data.

License

This library is MIT licensed.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Rx-File-Upload

Table of contents

Installation

UMD

Usage

API in Details

rxFileUpload(config)

.progress$

.upload<T>(oneFileOrMultipleFiles[,additionalFormData])

Data sent in the FormData

supportsRxFileUpload()

Types in Details

RxFileUpload:

RxFileUploadConfig:

RxFileUploadAdditionalFormData:

RxFileUploadProgressData:

RxFileUploadResponse<T>:

RxFileUploadError:

License

`rxFileUpload(config)`

`.progress$`

`.upload<T>(oneFileOrMultipleFiles[,additionalFormData])`

`supportsRxFileUpload()`