s3mini Documentation

The putAnyObject method is the recommended way to upload data. It automatically decides between a single PUT request and a multipart upload based on the data size.

• ≤ 8MB (default): Performs a single PUT request.
• > 8MB: Automatically performs a multipart upload with 4 concurrent part uploads, automatic retries (3 attempts with exponential backoff), and automatic cleanup on failure.

Memory Efficiency Tip: For large files, use Blob or File instead of Uint8Array to enable zero-copy slicing, which prevents loading the entire file into memory.

// Small file — uses single PUT internally
await s3.putAnyObject('small.txt', 'Hello World');

// Large file — automatically uses multipart
const largeBuffer = await fs.readFile('video.mp4'); // 500MB
await s3.putAnyObject('videos/movie.mp4', largeBuffer, 'video/mp4');

// Blob (zero-copy slicing for memory efficiency)
const file = new File([largeArrayBuffer], 'data.bin');
await s3.putAnyObject('uploads/data.bin', file);

// ReadableStream (uploads as data arrives)
const stream = fs.createReadStream('huge-file.dat');
await s3.putAnyObject('backups/data.dat', Readable.toWeb(stream));

Starting from version 0.8.1, listObjects and listObjectsPaged include CommonPrefixes in results when the delimiter option is used.

Directory prefixes are returned as synthetic ListObject entries with the following properties:

• Key: Ends in / (e.g., prefix/subdir/)
• Size: 0
• ETag: ''
• StorageClass: ''
• LastModified: new Date(0)

Migration: If your logic expects only files, you must now filter the results by checking if the Key ends with a slash or by checking for a non-empty ETag.

// Before: only files returned
const objects = await s3.listObjects('/', 'prefix/', undefined, { delimiter: '/' });

// After: files + directory prefixes returned
const all = await s3.listObjects('/', 'prefix/', undefined, { delimiter: '/' });
const files = all.filter(o => !o.Key.endsWith('/'));
const directories = all.filter(o => o.Key.endsWith('/'));

Version 1.0.0 introduced several significant changes:

ESM Only

s3mini is now an ESM-only package. The minified CJS build has been removed.

Bun Native Fast Paths

On Bun, several methods now use Bun.S3Client instead of globalThis.fetch. This improves performance but changes how requests are handled:

• Affected Methods: getObject, getObjectArrayBuffer, getObjectJSON, getEtag, getContentLength, objectExists, deleteObject, listObjects, and getPresignedUrl.
• Behavioral Changes: These requests bypass globalThis.fetch, meaning fetch mocks, interceptors, requestAbortTimeout, and per-request logger output will not work for them.
• Error Handling: Errors are still S3ServiceError, but .status may be 0 for certain codes, and .body contains the provider's message text instead of raw XML.
• Presigned URLs: Uses Bun's signer; query parameters may differ from other runtimes.

Migration: If you need to maintain the previous fetch-based behavior on Bun, pass a custom fetch implementation in your configuration:

const s3 = new S3mini({ ...config, fetch: (input, init) => fetch(input, init) });

Upload Methods

putObject, putAnyObject, getObjectRaw, and getObjectWithETag no longer use Bun fast paths to avoid issues with Bun.write() rewriting content types or mishandling ReadableStream objects. These methods now use the standard signed path on all runtimes.

For advanced scenarios requiring progress tracking, resumable uploads, or custom concurrency, use the manual multipart upload workflow:

1. Initialize: Call getMultipartUploadId to get an uploadId.
2. Upload Parts: Use uploadPart to upload chunks. Each part must be $\ge$ 5MB (except the last part). Part numbers are 1-indexed (max 10,000).
3. Complete: Call completeMultipartUpload with the array of completed parts.
4. Abort/Cleanup: Use abortMultipartUpload to cancel an upload or listMultipartUploads to find and clean up orphaned uploads.

// 1. Initialize upload
const uploadId = await s3.getMultipartUploadId(
  key: string,
  contentType?: string,
  ssecHeaders?: SSECHeaders,
  additionalHeaders?: AWSHeaders,
);

// 2. Upload parts (must be ≥ 5MB except last part)
const parts: UploadPart[] = [];

for (let i = 0; i < totalParts; i++) {
  const partData = buffer.subarray(i * partSize, (i + 1) * partSize);
  const part = await s3.uploadPart(
    key,
    uploadId,
    partData,
    i + 1,  // partNumber: 1-indexed, max 10,000
  );
  parts.push(part);
  console.log(`Uploaded part ${i + 1}/${totalParts}`);
}

// 3. Complete upload
const result = await s3.completeMultipartUpload(key, uploadId, parts);
console.log('Final ETag:', result.etag);