GitHub - good-lly/s3mini: 👶 Tiny S3 client. Edge computing ready. No-dep. In Typescript. Works with @cloudflare @minio @backblaze @digitalocean @garagehq @oracle

# On Windows, Mac, or Linux
mv example.env .env

import { S3mini } from 's3mini';

const s3 = new S3mini({
  accessKeyId: process.env.S3_ACCESS_KEY,
  secretAccessKey: process.env.S3_SECRET_KEY,
  endpoint: 'https://bucket.region.r2.cloudflarestorage.com',
  region: 'auto',
});

// Upload (auto-selects single PUT or multipart based on size)
await s3.putAnyObject('photos/vacation.jpg', fileBuffer, 'image/jpeg');

// Download
const data = await s3.getObject('photos/vacation.jpg');

// List
const objects = await s3.listObjects('/', 'photos/');

// Delete
await s3.deleteObject('photos/vacation.jpg');

const s3 = new S3mini({
  // Required
  accessKeyId: string,
  secretAccessKey: string,
  endpoint: string, // Full URL: https://bucket.region.provider.com

  // Optional
  region: string, // Default: 'auto'
  minPartSize: number, // Default: 8MB — threshold for multipart
  requestSizeInBytes: number, // Default: 8MB — chunk size for range requests
  requestAbortTimeout: number, // Timeout in ms (undefined = no timeout)
  logger: Logger, // Custom logger with info/warn/error methods
  fetch: typeof fetch, // Custom fetch implementation
});

// Path-style (bucket in path)
'https://s3.us-east-1.amazonaws.com/my-bucket';

// Virtual-hosted-style (bucket in subdomain)
'https://my-bucket.s3.us-east-1.amazonaws.com';

// Provider-specific
'https://my-bucket.nyc3.digitaloceanspaces.com';
'https://account-id.r2.cloudflarestorage.com/my-bucket';

const response = await s3.putObject(
  key: string,                    // Object key/path
  data: string | Buffer | Uint8Array | Blob | File | ReadableStream,
  contentType?: string,           // Default: 'application/octet-stream'
  ssecHeaders?: SSECHeaders,      // Optional encryption headers
  additionalHeaders?: AWSHeaders, // Optional x-amz-* headers
  contentLength?: number,         // Optional, auto-detected for most types
);

// Returns: Response object
const etag = response.headers.get('etag');

// String content
await s3.putObject('config.json', JSON.stringify({ key: 'value' }), 'application/json');

// Buffer/Uint8Array
const buffer = await fs.readFile('image.png');
await s3.putObject('images/photo.png', buffer, 'image/png');

// Blob (browser File API or Node 18+)
const blob = new Blob(['Hello'], { type: 'text/plain' });
await s3.putObject('hello.txt', blob, 'text/plain');

// With custom headers
await s3.putObject('data.bin', buffer, 'application/octet-stream', undefined, {
  'x-amz-meta-author': 'john',
  'x-amz-meta-version': '1.0',
});

const response = await s3.putAnyObject(
  key: string,
  data: string | Buffer | Uint8Array | Blob | File | ReadableStream,
  contentType?: string,
  ssecHeaders?: SSECHeaders,
  additionalHeaders?: AWSHeaders,
  contentLength?: number,
);

// 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));

// ❌ Loads entire file into memory
const buffer = await fs.readFile('large-video.mp4');
await s3.putAnyObject('video.mp4', buffer);

// ✅ Zero-copy slicing — only reads data when uploading each part
const file = Bun.file('large-video.mp4'); // Bun
// or
const blob = new Blob([await fs.readFile('large-video.mp4')]); // Node
await s3.putAnyObject('video.mp4', file);

// 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);

import { runInBatches } from 's3mini';

const PART_SIZE = 8 * 1024 * 1024; // 8MB
const CONCURRENCY = 6;

async function uploadWithProgress(key: string, data: Uint8Array) {
  const uploadId = await s3.getMultipartUploadId(key);
  const totalParts = Math.ceil(data.byteLength / PART_SIZE);
  let completed = 0;

  const tasks = Array.from({ length: totalParts }, (_, i) => async () => {
    const start = i * PART_SIZE;
    const end = Math.min(start + PART_SIZE, data.byteLength);
    const part = await s3.uploadPart(key, uploadId, data.subarray(start, end), i + 1);
    completed++;
    console.log(`Progress: ${((completed / totalParts) * 100).toFixed(1)}%`);
    return part;
  });

  const results = await runInBatches(tasks, CONCURRENCY);
  const parts = results
    .filter((r): r is PromiseFulfilledResult => r.status === 'fulfilled')
    .map(r => r.value)
    .sort((a, b) => a.partNumber - b.partNumber);

  return s3.completeMultipartUpload(key, uploadId, parts);
}

await s3.abortMultipartUpload(key, uploadId);

const pending = await s3.listMultipartUploads();
// Clean up orphaned uploads
for (const upload of pending.Upload || []) {
  await s3.abortMultipartUpload(upload.Key, upload.UploadId);
}

// As string
const text = await s3.getObject('file.txt');

// As ArrayBuffer
const buffer = await s3.getObjectArrayBuffer('image.png');

// As JSON (auto-parsed)
const data = await s3.getObjectJSON('config.json');

// Full Response object (for headers, streaming)
const response = await s3.getObjectResponse('video.mp4');
const stream = response.body; // ReadableStream

// With ETag for caching
const { etag, data } = await s3.getObjectWithETag('file.txt');

// Range request (partial download)
const response = await s3.getObjectRaw(
  'large-file.bin',
  false, // wholeFile: false for range request
  0, // rangeFrom
  1024 * 1024, // rangeTo (first 1MB)
);

// List all objects (auto-paginates)
const objects = await s3.listObjects();

// With prefix filter (list "folder")
const photos = await s3.listObjects('/', 'photos/');

// With max keys limit
const first100 = await s3.listObjects('/', '', 100);

// Manual pagination
let token: string | undefined;
do {
  const { objects, nextContinuationToken } = await s3.listObjectsPaged(
    '/', // delimiter
    'uploads/', // prefix
    100, // maxKeys per page
    token, // continuation token
  );
  console.log(objects);
  token = nextContinuationToken;
} while (token);

interface ListObject {
  Key: string;
  Size: number;
  LastModified: Date;
  ETag: string;
  StorageClass: string;
}

// Single object
const deleted = await s3.deleteObject('file.txt'); // boolean

// Multiple objects (batched, max 1000 per request)
const keys = ['a.txt', 'b.txt', 'c.txt'];
const results = await s3.deleteObjects(keys); // boolean[] in same order

// Copy within same bucket
const result = await s3.copyObject('source.txt', 'backup/source.txt');

// Copy with new metadata
await s3.copyObject('report.pdf', 'archive/report.pdf', {
  metadataDirective: 'REPLACE',
  metadata: {
    'archived-at': new Date().toISOString(),
  },
  contentType: 'application/pdf',
});

// Move (copy + delete source)
await s3.moveObject('temp/upload.tmp', 'files/document.pdf');

interface CopyObjectOptions {
  metadataDirective?: 'COPY' | 'REPLACE';
  metadata?: Record;
  contentType?: string;
  storageClass?: string;
  taggingDirective?: 'COPY' | 'REPLACE';
  sourceSSECHeaders?: SSECHeaders;
  destinationSSECHeaders?: SSECHeaders;
  additionalHeaders?: AWSHeaders;
}

// Only download if changed (returns null if ETag matches)
const data = await s3.getObject('file.txt', {
  'if-none-match': '"abc123"',
});

// Only download if modified since date
const data = await s3.getObject('file.txt', {
  'if-modified-since': 'Wed, 21 Oct 2024 07:28:00 GMT',
});

// Check existence with conditions
const exists = await s3.objectExists('file.txt', {
  'if-match': '"abc123"',
}); // null if ETag mismatch, true/false otherwise

const ssecHeaders = {
  'x-amz-server-side-encryption-customer-algorithm': 'AES256',
  'x-amz-server-side-encryption-customer-key': base64Key,
  'x-amz-server-side-encryption-customer-key-md5': base64KeyMd5,
};

// Upload encrypted
await s3.putObject('secret.dat', data, 'application/octet-stream', ssecHeaders);

// Download encrypted (must provide same key)
const decrypted = await s3.getObject('secret.dat', {}, ssecHeaders);

// Copy encrypted object
await s3.copyObject('secret.dat', 'backup/secret.dat', {
  sourceSSECHeaders: {
    'x-amz-copy-source-server-side-encryption-customer-algorithm': 'AES256',
    'x-amz-copy-source-server-side-encryption-customer-key': base64Key,
    'x-amz-copy-source-server-side-encryption-customer-key-md5': base64KeyMd5,
  },
  destinationSSECHeaders: ssecHeaders,
});

import { runInBatches, sanitizeETag } from 's3mini';

// Run async tasks with concurrency control
const results = await runInBatches(
  tasks: Iterable<() => Promise>,
  batchSize?: number,    // Default: 30
  minIntervalMs?: number // Default: 0 (no delay between batches)
);

// Clean ETag value
const clean = sanitizeETag('"abc123"'); // 'abc123'

import { S3ServiceError, S3NetworkError } from 's3mini';

try {
  await s3.getObject('missing.txt');
} catch (err) {
  if (err instanceof S3ServiceError) {
    console.error(`S3 error ${err.status}: ${err.serviceCode}`);
    console.error('Response body:', err.body);
  } else if (err instanceof S3NetworkError) {
    console.error(`Network error: ${err.code}`); // ENOTFOUND, ETIMEDOUT, etc.
  }
}

export default {
  async fetch(request: Request, env: Env): Promise {
    const s3 = new S3mini({
      accessKeyId: env.R2_ACCESS_KEY,
      secretAccessKey: env.R2_SECRET_KEY,
      endpoint: env.R2_ENDPOINT,
    });

    const data = await s3.getObject('hello.txt');
    return new Response(data);
  },
};