JS Reference

The complete reference for our client-side JavaScript library

class: UploadClient(options: Object)

Initialize a new UploadClient instance

Options

Property

Type

Required

Description

apiKey

String

Yes

Your upload service API key

log

Boolean

No

Turn on internal console logs for debugging

// NPM users only
import UploadClient from "@betterstack/upload-client";
// Init upload client
const UC = new UploadClient({
apiKey: "<YOUR_API_KEY>",
});

setApiKey(key: String) => void

Change the API key of an UploadClient instance.

UC.setApiKey("<YOUR_API_KEY>");

upload(options: Object) => UploadTask

Create an UploadTask instance which is responsible for managing the upload of a certain set of files

const task = UC.upload({
providerId: "<YOUR_PROVIDER_ID>",
files: [
{
file: document.getElementById("file-input").files[0],
key: "upload-path/image.png",
acl: "public-read",
}
]
});

Options

Property

Type

Required

Description

providerId

String

Yes

Your upload service storage provider ID

files

UploadFile[]

Yes

An array of files to be uploaded. See the structure of each element in the next table

throwUploadError

Boolean

No

Used to disable errors from being thrown after the upload is commenced. For more info see the following section.

UploadFile

Property

Type

Required

Description

file

File

Yes

A file that can be acquired from a HTML input of type "file"

key

String

No

The upload path and file name. By default, files are uploaded to your base path with the original file name. See file upload path for more info

acl

String

No

The ACL defines the permissions of the uploaded file. By default files are private. See file upload permissions for more info

class: UploadTask

This class is initialized using the upload method on the UploadClient class.

start() => Promise

Calling the start method on an UploadTask returns a promise. This resolves to an array containing the UploadedFile object. It can also reject an error. See the error handling page for details on all errors.

If you upload a single file, take the first element from the resolved array to get the details of your upload.

task()
.then((uploadedFiles) => {
uploadedFiles.forEach((item) => console.log(item.key));
})
.catch((e) => {});

UploadedFile

Property

Type

Description

key

String

The final path of the uploaded file

file

File

The actual file itself for reference purposes

responseCode

Number

The HTTP response code of the upload. Only present if throwUploadError is false to verify if a file was successfully uploaded.

errorCode

String

The error code for why the upload failed. Only present if throwUploadError is false to handle the respective error.

stop() => void

This method is used to stop the upload after it has been started. Calling stop on a task will immediately abort the upload network request. Calling stop on an UploadTask that hasn't started or that has already been stopped will result in an error.

task.stop();

onProgress(fn: ProgressFunction) => void

Used to track the progress of an UploadTask. Call this method with a function that takes the TaskProgress object as an argument.

task.onProgress((p) => {
console.log(p.loadedPercent);
// Total bytes to upload and total bytes uploaded
console.log(p.totalBytes, p.loadedBytes);
// Array of bytes for each file and uploaded bytes / % of each file
console.log(p.filesBytes, p.filesLoadedBytes, p.filesLoadedPercent);
});

TaskProgress

Property

Type

Description

loadedPercent

number

Total loaded percent from 0 - 100

totalBytes

number

Total bytes to upload

loadedBytes

number

Total bytes uploaded

filesBytes

number[]

An array of numbers which are the total bytes to be uploaded for each file in the upload task

filesLoadedBytes

number[]

An array of numbers which are the total bytes uploaded for each file in the upload task

filesLoadedPercent

number[]

An array of numbers which are the total percent (0-100) uploaded for each file in the upload task