Skip to main content

Uploader

Package​

@rpldy/uploader

Installation​

npm install @rpldy/uploader

Upload Options​

Name (* = mandatory)TypeDefaultDescription
autoUploadbooleantrueautomatically upload files when they are added
destinationDestinationundefinedconfigure the end-point to upload to
inputFieldNamestring"file"name (attribute) of the file input field (requires sendWithFormData = true)
groupedbooleanfalsegroup multiple files in a single request
maxGroupSizenumber5maximum of files to group together in a single request
formatGroupParamName(number, string) => stringundefineddetermine the upload request field name when more than file is grouped in a single upload
fileFilter[fileFilter](.#fileFilterundefinedreturn false or Promise resolving to false to exclude item from batch
methodstring"POST"HTTP method in upload request
paramsObjectundefinedcollection of params to pass along with the upload (requires sendWithFormData = true)
forceJsonResponsebooleanfalseparse server response as JSON even if no JSON content-type header received
withCredentialsbooleanfalseset XHR withCredentials to true
enhancerUploaderEnhancerundefineduploader enhancer function
concurrentbooleanfalseissue multiple upload requests simultaneously
maxConcurrentnumber2maximum allowed simultaneous requests
sendSendMethod@rpldy/senderhow to send files to the server
sendWithFormDatabooleantrueupload is sent as part of formdata - when true, additional params can be sent along with uploaded data
formatServerResponseFormatServerResponseMethodundefinedfunction to create the batch item's uploadResponse from the raw xhr response
formDataAllowUndefinedbooleanfalsewhether to include params with undefined value
clearPendingOnAddbooleanfalsewhether to clear pending batch(es) when a new one is added
isSuccessfulCallIsSuccessfulCallundefinedcallback to use to decide whether upload response is succssful or not
fastAbortThresholdnumber100the pending/active item count threshold from which to start using the performant abort mechanism
userDataanyundefinedmetadata set by the user and isn't used by the upload process in any way, provided as a convenience to pass data around
info

See uploady page for more details on some of these options

Example​

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

const uploader = createUploader({ destination: { url: "https://my-server.com/upload" }});

uploader.add([myFile1, myFile2], { autoUpload: false });

uploader.once(UPLOADER_EVENTS.BATCH_ADD, (batch) => {
	console.log(`NEW BATCH ADDED WITH ${batch.items.length} FILES`, batch);
});

API​

The Uploader API is typically used by internal logic of the various rpldy packages. In a React environment, accessing the API should be done through the Context API.

add​

type Add = (files: UploadInfo | UploadInfo[], addOptions?: UploadOptions) => Promise<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​

type Upload = (uploadOptions?: UploadOptions) => void

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

abort​

type Abort  = (id?: string) => void;

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

abortBatch​

(id: string) => void;

type AbortBatch  = (id?: string) => void;

abort a specific batch by passing its ID

update​

type Update = (updateOptions: CreateOptions) => UploaderType;

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

getOptions​

type GetOptions = () => CreateOptions;

Get the instance's upload options

clearPending​

type ClearPending = () => void;

Remove all batches that were added with autoUpload = false and were not handed over to the sender

on​

type On = (name: unknown, cb: EventCallback) => OffMethod

Register an event handler

once​

type Once = (name: unknown, cb: EventCallback) => OffMethod

Register an event handler that will be called a maximum one time

off​

type Off = (name: unknown, cb?: EventCallback) => void;

Unregister an existing event handler. If handler function reference isn't provided, will unregister all handlers for the provided event name.

registerExtension​

type RegisterExtension = (name: unknown, methods: { [key: string]: (...args: any[]) => void | unknown }) => void;

Extensions can only be registered by uploader 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​

type GetExtension = (name: unknown) => Record<string, unknown>;

Retrieve a registered extension by its name

Events​

The Uploader will trigger lifecycle events for Batch and Batch Item.

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);

Batch Events​

UPLOADER_EVENTS.BATCH_ADD​

Triggered when a new batch is added.

info

This event is cancellable

UPLOADER_EVENTS.BATCH_START​

Triggered when batch items start uploading

info

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.BATCH_ERROR​

Triggered in case the batch was failed with an error. These errors will most likely occur due to invalid event handling. For instance, by a handler (ex: BATCH_START) throwing an error.

  • Parameters: (batch)

UPLOADER_EVENTS.BATCH_FINALIZE​

Triggered when all batch items have finished uploading or in case the batch was cancelled(abort) or had an error

  • Parameters: (batch)

Batch Item Events​

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)
info

This event is cancellable

UPLOADER_EVENTS.ITEM_FINISH​

Triggered when item finished uploading successfully

  • Parameters: (item)
info

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)
info

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)
info

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)
info

This event is cancellable

UPLOADER_EVENTS.ALL_ABORT​

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

  • no parameters