Skip to main content

​
Overview

The S3M class provides several methods for managing multipart uploads to AWS S3.

​
upload()

Main method that orchestrates the entire upload process. 
const result = await uploader.upload();

​
Returns

​
Promise<Object>
Promise
Returns a promise that resolves to an object containing upload information.

​
Return Object (auto_complete: true)

​
uuid
string
Unique identifier for the upload.
​
key
string
S3 object key where the file is stored.
​
extension
string
File extension extracted from the filename.
​
name
string
Original filename.
​
url
string
Public URL of the uploaded file.

​
Return Object (auto_complete: false)

​
uuid
string
Unique identifier for the upload.
​
key
string
S3 object key where the file is stored.
​
extension
string
File extension extracted from the filename.
​
name
string
Original filename.
​
upload_id
string
AWS S3 upload ID for the multipart upload.
​
parts
Array<Object>
Array of uploaded parts with ETag and PartNumber.

​
Example

const uploader = new S3M(file, {
  progress: (percent) => console.log(`${percent}%`)
});

const result = await uploader.upload();
console.log('Uploaded to:', result.url);
console.log('File UUID:', result.uuid);

​
startUpload()

Initiates a multipart upload and gets the upload ID from AWS S3. 
const { key, uploadId, uuid } = await uploader.startUpload();

​
Returns

​
Promise<Object>
Promise
Promise that resolves to an object with upload initialization data.

​
Return Fields

​
key
string
S3 object key for the file.
​
uploadId
string
AWS S3 multipart upload ID.
​
uuid
string
Unique identifier for the upload.

​
Example

const uploader = new S3M(file);
const { key, uploadId, uuid } = await uploader.startUpload();
console.log('Upload started with ID:', uploadId);

​
Throws

  • Error - If filename is empty

​
uploadChunks()

Uploads the file in chunks with concurrent upload management. 
const parts = await uploader.uploadChunks(key, uploadId, updateProgress);

​
Parameters

​
key
string
required
S3 object key for the file.
​
uploadId
string
required
AWS S3 multipart upload ID.
​
updateProgress
Function
required
Callback function to receive progress updates.Signature: (percent: number) => void

​
Returns

​
Promise<Array>
Promise
Promise that resolves to an array of uploaded parts, sorted by PartNumber.Each part object contains:
  • ETag (string): Entity tag from S3
  • PartNumber (number): Part number (1-indexed)

​
Example

const { key, uploadId } = await uploader.startUpload();
const parts = await uploader.uploadChunks(key, uploadId, (percent) => {
  console.log(`Progress: ${percent}%`);
});
console.log(`Uploaded ${parts.length} parts`);

​
uploadChunk()

Uploads a single chunk with retry logic. 
const part = await uploader.uploadChunk(
  key,
  uploadId,
  partNumber,
  chunk,
  totalChunks,
  progress,
  updateProgress
);

​
Parameters

​
key
string
required
S3 object key for the file.
​
uploadId
string
required
AWS S3 multipart upload ID.
​
partNumber
number
required
Part number (1-indexed).
​
chunk
Blob
required
Blob containing the chunk data.
​
totalChunks
number
required
Total number of chunks in the upload.
​
progress
Array
required
Array tracking progress of all chunks.
​
updateProgress
Function
required
Callback function to receive progress updates.

​
Returns

​
Promise<Object>
Promise
Promise that resolves to a part object.

​
Return Fields

​
ETag
string
Entity tag from S3 response headers.
​
PartNumber
number
Part number that was uploaded.

​
Behavior

  • Automatically retries failed uploads up to chunk_retries times
  • Logs warnings when retrying
  • Throws error if all retries are exhausted

​
completeUpload()

Completes the multipart upload on AWS S3. 
const url = await uploader.completeUpload(key, uploadId, parts);

​
Parameters

​
key
string
required
S3 object key for the file.
​
uploadId
string
required
AWS S3 multipart upload ID.
​
parts
Array
required
Array of uploaded parts with ETag and PartNumber.

​
Returns

​
Promise<string>
Promise
Promise that resolves to the public URL of the uploaded file.

​
Example

const { key, uploadId } = await uploader.startUpload();
const parts = await uploader.uploadChunks(key, uploadId, () => {});
const url = await uploader.completeUpload(key, uploadId, parts);
console.log('File available at:', url);

​
getSignUrl()

Gets a pre-signed URL from the backend for uploading a specific part. 
const signedUrl = await uploader.getSignUrl(key, uploadId, partNumber);

​
Parameters

​
key
string
required
S3 object key for the file.
​
uploadId
string
required
AWS S3 multipart upload ID.
​
partNumber
number
required
Part number to get signed URL for (1-indexed).

​
Returns

​
Promise<string>
Promise
Promise that resolves to the pre-signed S3 upload URL.

​
Example

const signedUrl = await uploader.getSignUrl('my-file-key', 'upload-123', 1);
console.log('Signed URL:', signedUrl);

​
handleUploadProgress()

Handles progress events from chunk uploads and calculates overall progress. 
uploader.handleUploadProgress(event, totalChunks, chunkIndex, progress, updateProgress);

​
Parameters

​
event
ProgressEvent
required
Progress event from axios upload.Contains loaded and total properties.
​
totalChunks
number
required
Total number of chunks in the upload.
​
chunkIndex
number
required
Index of the current chunk (0-indexed).
​
progress
Array
required
Array tracking progress percentage of each chunk.
​
updateProgress
Function
required
Callback function to receive overall progress updates.Signature: (percent: number) => void

​
Returns

This method returns void and updates the progress array and calls the callback.

​
Behavior

  1. Calculates the progress percentage for the current chunk
  2. Updates the progress array at the chunk’s index
  3. Calculates overall progress as the average of all chunks
  4. Calls the updateProgress callback with the overall percentage

​
Helper Function: s3m()

Convenience function that creates an S3M instance and immediately starts the upload. 
import { s3m } from '@savannabits/s3m';

const result = await s3m(file, options);

​
Parameters

​
file
File
required
File object to upload.
​
options
Object
Configuration options (same as S3M constructor).

​
Returns

Returns the same result as calling new S3M(file, options).upload().

​
Example

import { s3m } from '@savannabits/s3m';

const file = document.getElementById('file-input').files[0];

const result = await s3m(file, {
  chunk_size: 5 * 1024 * 1024,
  progress: (percent) => {
    console.log(`Upload: ${percent}%`);
  }
});

console.log('Uploaded:', result.url);

Build docs developers (and LLMs) love

Get started for freeTalk to us