Uploader

Package​

@rpldy/uploader

Installation​

npm install @rpldy/uploader

yarn add @rpldy/uploader

pnpm add @rpldy/uploader

Upload 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>

• See: UploadInfo
• See: UploadOptions

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

• See: UploadOptions

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;

• See: CreateOptions
• See: UploaderType

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

getOptions​

type GetOptions = () => CreateOptions;

• See: 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.

• Parameters: (batch, options: CreateOptions)

• See: CreateOptions

UPLOADER_EVENTS.BATCH_START​

Triggered when batch items start uploading

• Parameters: (batch, options: CreateOptions)

• See: CreateOptions

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)

UPLOADER_EVENTS.ITEM_FINISH​

Triggered when item finished uploading successfully

• Parameters: (item)

UPLOADER_EVENTS.ITEM_PROGRESS​

Triggered every time progress data is received for this file upload

• Parameters: (item)

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)

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)

• See: withRequestPreSendUpdate HOC

UPLOADER_EVENTS.ALL_ABORT​

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

• no parameters