api-reference.md

API Reference

ChunkUploader

class ChunkUploader<TMetadata extends Metadata> {
  constructor(options: ChunkUploaderOptions<TMetadata>);
  get status(): ChunkUploaderStatus;
  get bytesUploaded(): number;
  get error(): unknown;
  get file(): File;
  start(): boolean;
  get canStart(): boolean;
  pause(): boolean;
  get canPause(): boolean;
  resume(): boolean;
  get canResume(): boolean;
  abort(): boolean;
  get canAbort(): boolean;
}

Constructor

new ChunkUploader(options: ChunkUploaderOptions)

• Parameters
  • options: ChunkUploaderOptions

Properties or Methods

status - Accessor

status: 'pending' | 'uploading' | 'pausing' | 'paused' | 'aborted' | 'complete' | 'error'

The status of the uploader

Reference: How status changes

bytesUploaded - Accessor

bytesUploaded: number

Bytes uploaded so far.

error - Accessor

error: unknown

The error that occurred during the upload process. This is undefined if no error occurred.

file - Accessor

file: File

The file for the upload process.

start - Method

start(): boolean

Start the upload process. returns false if the status is not pending.

• status: pending -> uploading -> complete or error

canStart - Accessor

canStart: boolean

true if the status is pending.

pause - Method

pause(): boolean

Pause the upload process. returns false if the status is not uploading.

Note that the status at the end could be complete if the last chunk is being uploaded when the function is called.

• status: uploading -> pausing -> paused or complete

canPause - Accessor

canPause: boolean

true if the status is uploading.

resume - Method

resume(): boolean

Resume the upload process. returns false if the status is not paused or error.

• status: paused or error -> uploading -> complete or error

canResume - Accessor

canResume: boolean

true if the status is paused or error.

abort - Method

abort(): boolean

Abort the upload process. returns false if the status is not paused or error.

• status: paused or error -> aborted

canAbort - Accessor

canAbort: boolean

true if the status is paused or error.

ChunkUploaderOptions

interface ChunkUploaderOptions<TMetadata extends Metadata> {
  file: File;
  onChunkUpload: ChunkUploadHandler<TMetadata>;
  metadata: TMetadata;
  chunkBytes?: number;
  retryDelays?: number[];
  onChunkComplete?: (bytesAccepted: number, bytesTotal: number) => void;
  onSuccess?: () => void;
  onError?: (error: unknown) => void;
  onPaused?: () => void;
  onAborted?: (metadata: TMetadata) => void;
  onStatusChange?: (
    oldStatus: ChunkUploaderStatus | undefined,
    newStatus: ChunkUploaderStatus
  ) => void;
}

Properties

file - Required

file: File

The file to be uploaded

onChunkUpload - Required

onChunkUpload: (chunkFormData, metadata) => Promise<void>

The function that defines how the chunk is uploaded to the server.

• Parameters
  • chunkFormData: ChunkFormData
  • metadata: Metadata

metadata - Required

metadata: (TMetadata extends Record<string, string | boolean | number | undefined | null>)

The metadata to send with each chunk. This can be used to send additional information like the file name, file type, etc.

chunkBytes - Optional

Default: 5MB (5 * 1024 * 1024)

chunkBytes?: number

The number of bytes to send in each chunk.

retryDelays - Optional

Default: [1000, 2000, 4000, 8000]

retryDelays?: number[]

Milliseconds to wait before retrying a failed chunk upload. Set to an empty array to disable retries.

onChunkComplete - Optional

Default: undefined

onChunkComplete?: (bytesAccepted: number, bytesTotal: number) => void

A callback that is called when a chunk is uploaded.

onSuccess - Optional

Default: undefined

onSuccess?: () => void

A callback that is called when the file is sucessfully uploaded.

onError - Optional

Default: undefined

onError?: (error: unknown) => void

A callback that is called when an error occurs during the upload process.

onPaused - Optional

Default: undefined

onPaused?: () => void

A callback that is called when the upload process is paused.

onAborted - Optional

Default: undefined

onAborted?: (metadata) => void

A callback that is called when the upload process is aborted.

• Parameters
  • metadata: Metadata

onStatusChange - Optional

Default: undefined

onStatusChange?: (oldStatus, newStatus) => void

A callback that is called when the status of the uploader changes.

• Parameters
  • oldStatus: ChunkUploaderStatus | undefined
  • newStatus: ChunkUploaderStatus

ChunkFormData

interface ChunkFormData {
  get(name: 'blob'): Blob;
  get(name: 'offset'): `${number}`;
  get(name: 'length'): `${number}`;
  get(name: 'retry'): `${number}`;
  get(name: 'total'): `${number}`;
  get(name: 'isLastChunk'): 'true' | 'false';
}

The form data that is sent with each chunk. This includes the chunk blob, the offset, the length, and other information.

Others

How status changes