@rpldy/uploader

Contents

• Intro
• Installation
• Usage
• Upload Options
• Uploader API
• Events
• Cancellable Events

Uploader

The Uploader is the processing and queuing engine for React-Uploady. When files are handed to the Uploader, it will represent each file as a Batch Item and group them together in Batches. This is for the most part internal to the uploading mechanism.

The Uploader fires Batch & BatchItem lifecycle events that can be registered to. Some of these events also allow to cancel uploads dynamically.

_If you're looking to integrate file upload with your React app, you'd probably want to head over to the @rpldy/uploady README.

Installation

#Yarn:
  $ yarn add @rpldy/uploader

#NPM:
  $ npm i @rpldy/uploader

Usage

When in React, you don't need to use this package directly. Uploady will take care of initialization and other aspects (ie: event registration) for you. In case you want to create your own uploader instance, you can do it like so:

import createUploader, { UPLOADER_EVENTS } from "@rpldy/uploader";

const uploader = createUploader({ 
    autoUpload: false,
    grouped: true,
    //...
});

uploader.on(UPLOADER_EVENTS.ITEM_START, (item) => {
     console.log(`item ${item.id} started uploading`);  
});

uploader.add(myFile);

Upload Options

Name (* = mandatory)	Type	Default	Description
autoUpload	boolean	true	automatically upload files when they are added
destination	Destination	undefined	configure the end-point to upload to
inputFieldName	string	"file"	name (attribute) of the file input field (requires sendWithFormData = true)
grouped	boolean	false	group multiple files in a single request
maxGroupSize	number	5	maximum of files to group together in a single request
formatGroupParamName	(number, string) => string	undefined	determine the upload request field name when more than file is grouped in a single upload
fileFilter	(File | string, index: number, File[] | string[]) => boolean	undefined	return false to exclude from batch
method	string	"POST"	HTTP method in upload request
params	Object	undefined	collection of params to pass along with the upload (requires sendWithFormData = true)
forceJsonResponse	boolean	false	parse server response as JSON even if no JSON content-type header received
withCredentials	boolean	false	set XHR withCredentials to true
enhancer	UploaderEnhancer	undefined	uploader enhancer function
concurrent	boolean	false	issue multiple upload requests simultaneously
maxConcurrent	number	2	maximum allowed simultaneous requests
send	SendMethod	@rpldy/sender	how to send files to the server
sendWithFormData	boolean	true	upload is sent as part of formdata - when true, additional params can be sent along with uploaded data
formatServerResponse	FormatServerResponseMethod	undefined	function to create the batch item's uploadResponse from the raw xhr response

Uploader API

add

(files: UploadInfo | UploadInfo[], options?: ?UploadOptions) => void

The way to add file(s) to be uploaded. Second parameters allows to pass different options than the ones the instance currently uses for this specific batch. These options will be merged with current instance options.

upload

() => void

For batches that were added with autoUpload = false, the upload method must be called for the files to begin uploading.

abort

(id?: string) => void

abort all files being uploaded or a single item by its ID

abortBatch

(id: string) => void

abort a specific batch by its ID

update

(options: UploadOptions) => UploaderType

options parameter will be merged with the instance's existing options Returns the uploader instance

getOptions

() => CreateOptions

get the instance's upload options

clearPending

() => void

remove all batches that were added with autoUpload = false and were not sent to upload yet.

on

OnAndOnceMethod

register an event handler

once

OnAndOnceMethod

register an event handler that will be called only once

off

OffMethod

unregister an existing event handler

registerExtension

(name: any, Object) => void

Extensions can only be registered by enhancers. If registerExtension is called outside an enhancer, an error will be thrown Name must be unique. If not, an error will be thrown

getExtension

(name: any) => ?Object_

Retrieve a registered extension by its name

Events

The Uploader will trigger for batch and batch-item lifecycle events.

Registering to handle events can be done using the uploader's on() and once() methods. Unregistering can be done using off() or by the return value of both on() and once().

const batchAddHandler = (batch) => {};

const unregister = uploader.on(UPLOADER_EVENTS.BATCH_ADD, batchAddHandler);

unregister(); //is equivalent to the line below
uploader.off(UPLOADER_EVENTS.BATCH_ADD, batchAddHandler);

UPLOADER_EVENTS.BATCH_ADD

Triggered when a new batch is added.

• Parameters: (batch, uploadOptions)

This event is cancellable

UPLOADER_EVENTS.BATCH_START

Triggered when batch items start uploading

• Parameters: (batch)

This event is cancellable

UPLOADER_EVENTS.BATCH_PROGRESS

Triggered every time progress data is received from the upload request(s)

• Parameters: (batch)

UPLOADER_EVENTS.BATCH_FINISH

Triggered when batch items finished uploading

• Parameters: (batch)

UPLOADER_EVENTS.BATCH_CANCEL

Triggered in case batch was cancelled from BATCH_START event handler

• Parameters: (batch)

UPLOADER_EVENTS.BATCH_ABORT

Triggered in case the batch was aborted

• Parameters: (batch)

UPLOADER_EVENTS.ITEM_START

Triggered when item starts uploading (just before) For grouped uploads (multiple files in same xhr request) ITEM_START is triggered for each item separately

• Parameters: (item)

This event is cancellable

UPLOADER_EVENTS.ITEM_FINISH

Triggered when item finished uploading successfully

• Parameters: (item)

The server response can be accessed through the item's uploadResponse property and status code through uploadStatus

UPLOADER_EVENTS.ITEM_PROGRESS

Triggered every time progress data is received for this file upload

• Parameters: (item)

progress info is accessed through the item's "completed" (percentage) and "loaded" (bytes) properties.

UPLOADER_EVENTS.ITEM_CANCEL

Triggered in case item was cancelled from ITEM_START event handler

• Parameters: (item)

UPLOADER_EVENTS.ITEM_ERROR

Triggered in case item upload failed

• Parameters: (item)

The server response can be accessed through the item's uploadResponse property.

UPLOADER_EVENTS.ITEM_ABORT

Triggered in case abort was called

• Parameters: (item)

UPLOADER_EVENTS.ITEM_FINALIZE

Triggered for item when uploading is done due to: finished, error, cancel or abort Use this event if you want to handle the state of the item being done for any reason.

• Parameters: (item)

UPLOADER_EVENTS.REQUEST_PRE_SEND

Triggered before a group of items is going to be uploaded Group will contain a single item unless "grouped" option is set to true.

Handler receives the item(s) in the group and the upload options that were used. The handler can change data inside the items and in the options by returning different data than received. See this guide for more details.

• Parameters: (items, options)

This event is cancellable

UPLOADER_EVENTS.ALL_ABORT

Triggered when abort is called without an item id (abort all)

• no parameters

Cancellable Events

These are events that allow the client to cancel their respective upload object (batch or batch-item) To cancel the upload, the handler must return (boolean) false.

uploader.on(UPLOADER_EVENTS.ITEM_START, (item) => {
    let result;
    
    if (item.file.name.endsWith(".xml")) {
        result = false; //only false will cause a cancel.
    }

    return result;
});

Changelog

0.10.0 (2021-02-27)

Features

• [uploady] - expose more TS types (shared, uploader, useFileInput, file&batch states)
• [uploader] - add server status code to batch item
• [sender] - new formatServerResponse option to customize uploadResponse added to batch item

Docs

• [uploady] - SendMethod link fix

Bug fixes

• [uploader] - batch and items state corrupted. Fix for #144

Internal

• e2e - upgrade to cypress.io latest (6.5.0)
• e2e - use cypress-intercept-formdata package