s3mini 0.9.0 → 0.9.2

package/README.md

@@ -1,6 +1,6 @@
 # s3mini | Tiny & fast S3 client for node and edge platforms.
 
-`s3mini` is an ultra-lightweight Typescript client (~18 KB minified, ≈15 % more ops/s) for S3-compatible object storage. It runs on Node, Bun, Cloudflare Workers, and other edge platforms. It has been tested on Cloudflare R2, Backblaze B2, DigitalOcean Spaces, Ceph, Oracle, Garage and MinIO. (No Browser support!)
+`s3mini` is an ultra-lightweight Typescript client (~20 KB minified, ≈15 % more ops/s) for S3-compatible object storage. It runs on Node, Bun, Cloudflare Workers, and other edge platforms. It has been tested on Cloudflare R2, Backblaze B2, DigitalOcean Spaces, Ceph, Oracle, Garage and MinIO. (No Browser support!)
 
 [[github](https://github.com/good-lly/s3mini)]
 [[issues](https://github.com/good-lly/s3mini/issues)]
@@ -8,18 +8,19 @@
 
 ## Features
 
-- 🚀 Light and fast: averages ≈15 % more ops/s and only ~18 KB (minified, not gzipped).
-- 🔧 Zero dependencies; supports AWS SigV4 (no pre-signed requests) and SSE-C headers (tested only on Cloudflare)
+- 🚀 Light and fast: averages ≈15 % more ops/s and only ~20 KB (minified, not gzipped).
+- 🔧 Zero dependencies; supports AWS SigV4, pre-signed URLs, and SSE-C headers (tested on Cloudflare)
 - 🟠 Works on Cloudflare Workers; ideal for edge computing, Node, and Bun (no browser support).
 - 🔑 Only the essential S3 APIs—improved list, put, get, delete, and a few more.
 - 🛠️ Supports multipart uploads.
+- 🎄 Tree-shakeable ES module.
 - 🎯 TypeScript support with type definitions.
-- 📚 Poorly-documented with examples and tests - But widely tested on various S3-compatible services! (Contributions welcome!)
+- 📚 Documented with examples, tests and widely tested on various S3-compatible services! (Contributions welcome!)
 - 📦 **BYOS3** — _Bring your own S3-compatible bucket_ (tested on Cloudflare R2, Backblaze B2, DigitalOcean Spaces, MinIO, Garage, Micro/Ceph and Oracle Object Storage, Scaleway).
 
 #### Tested On
 
-![Tested On](testedon.png)
+![Tested On](testedon.png) and more ...
 Contributions welcome!
 
 Dev:
@@ -43,44 +44,27 @@ Dev:
 
 <a href="https://github.com/good-lly/s3mini/issues/"> <img src="https://img.shields.io/badge/contributions-welcome-brightgreen.svg" alt="Contributions welcome" /></a>
 
-Performance tests was done on local Minio instance. Your results may vary depending on environment and network conditions, so take it with a grain of salt.
-![performance-image](https://raw.githubusercontent.com/good-lly/s3mini/dev/performance-screenshot.png)
-
 ## Table of Contents
 
-- [Supported Ops](#supported-ops)
 - [Installation](#installation)
-- [Usage](#usage)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Uploading Objects](#uploading-objects)
+- [Downloading Objects](#downloading-objects)
+- [Listing Objects](#listing-objects)
+- [Deleting Objects](#deleting-objects)
+- [Copy and Move](#copy-and-move)
+- [Conditional Requests](#conditional-requests)
+- [Pre-signed URLs](#pre-signed-urls)
+- [Server-Side Encryption (SSE-C)](#server-side-encryption-sse-c)
+- [API Reference](#api-reference)
+- [Error Handling](#error-handling)
+- [Cloudflare Workers](#cloudflare-workers)
+- [Supported Operations](#supported-operations)
 - [Security Notes](#security-notes)
 - [💙 Contributions welcomed!](#contributions-welcomed)
 - [License](#license)
 
-## Supported Ops
-
-The library supports a subset of S3 operations, focusing on essential features, making it suitable for environments with limited resources.
-
-#### Bucket ops
-
-- ✅ HeadBucket (bucketExists)
-- ✅ createBucket (createBucket)
-
-#### Objects ops
-
-- ✅ ListObjectsV2 (listObjects, listObjectsPaged)
-- ✅ GetObject (getObject, getObjectResponse, getObjectWithETag, getObjectRaw, getObjectArrayBuffer, getObjectJSON)
-- ✅ PutObject (putObject)
-- ✅ DeleteObject (deleteObject)
-- ✅ DeleteObjects (deleteObjects)
-- ✅ HeadObject (objectExists, getEtag, getContentLength)
-- ✅ listMultipartUploads
-- ✅ CreateMultipartUpload (getMultipartUploadId)
-- ✅ completeMultipartUpload
-- ✅ abortMultipartUpload
-- ✅ uploadPart
-- ✅ CopyObject: Local copyObject/moveObject(copyObject w delete)
-
-Put/Get objects with SSE-C (server-side encryption with customer-provided keys) is supported, but only tested on Cloudflare R2!
-
 ## Installation
 
 ```bash
@@ -107,151 +91,611 @@ mv example.env .env
 > **⚠️ Environment Support Notice**
 >
 > This library is designed to run in environments like **Node.js**, **Bun**, and **Cloudflare Workers**. It does **not support browser environments** due to the use of Node.js APIs and polyfills.
->
-> **Cloudflare Workers:** Now works without `nodejs_compat` compatibility flag, using native WebCrypto!
 
-## Usage
+## Quick Start
 
-> [!WARNING]
-> `s3mini` was a deprecated alias removed in a recent `0.5.0` release. Please migrate to the new `S3mini` class.
+```typescript
+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');
+```
+
+## Configuration
 
 ```typescript
-import { S3mini, sanitizeETag } from 's3mini';
-
-const s3client = new S3mini({
-  accessKeyId: config.accessKeyId,
-  secretAccessKey: config.secretAccessKey,
-  endpoint: config.endpoint, // e.g., 'https://<your-bucket>.<your-region>.digitaloceanspaces.com'
-  region: config.region,
-  // ?requestSizeInBytes = default is 8 MB
-  // ?requestAbortTimeout = default is no timeout
-  // ?logger = default is undefined (no logging)
-  // ?fetch = default is globalThis.fetch (you can provide your own fetch implementation)
+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
 });
+```
 
-// Basic bucket ops
-let exists: boolean = false;
-try {
-  // Check if the bucket exists
-  exists = await s3client.bucketExists();
-} catch (err) {
-  throw new Error(`Failed bucketExists() call, wrong credentials maybe: ${err.message}`);
-}
-if (!exists) {
-  // Create the bucket based on the endpoint bucket name
-  await s3client.createBucket();
+**Endpoint formats:**
+
+```typescript
+// 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';
+```
+
+---
+
+## Uploading Objects
+
+### putObject — Simple Upload
+
+Direct single-request upload. Use for small files or when you need fine control.
+
+```typescript
+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');
+```
+
+**Examples:**
+
+```typescript
+// 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',
+});
+```
+
+### putAnyObject — Smart Upload (Recommended)
+
+Automatically chooses single PUT or multipart based on data size. **This is the recommended method for most use cases.**
+
+```typescript
+const response = await s3.putAnyObject(
+  key: string,
+  data: string | Buffer | Uint8Array | Blob | File | ReadableStream,
+  contentType?: string,
+  ssecHeaders?: SSECHeaders,
+  additionalHeaders?: AWSHeaders,
+  contentLength?: number,
+);
+```
+
+**Behavior:**
+
+- **≤ minPartSize (8MB default):** Single PUT request
+- **> minPartSize:** Automatic multipart upload with:
+  - Parallel part uploads (4 concurrent by default)
+  - Automatic retries with exponential backoff (3 retries)
+  - Proper cleanup on failure (aborts incomplete uploads)
+
+**Examples:**
+
+```typescript
+// 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));
+```
+
+**Memory efficiency with Blobs:**
+
+For large files, using `Blob` or `File` is more memory-efficient than `Uint8Array`:
+
+```typescript
+// ❌ 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);
+```
+
+### Manual Multipart Upload
+
+For advanced control over multipart uploads (progress tracking, resumable uploads, custom concurrency).
+
+```typescript
+// 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}`);
 }
 
-// Basic object ops
-// key is the name of the object in the bucket
-const smallObjectKey: string = 'small-object.txt';
-// content is the data you want to store in the object
-// it can be a string or Buffer (recommended for large objects)
-const smallObjectContent: string = 'Hello, world!';
-
-// check if the object exists
-const objectExists: boolean = await s3client.objectExists(smallObjectKey);
-let etag: string | null = null;
-if (!objectExists) {
-  // put/upload the object, content can be a string or Buffer
-  // to add object into "folder", use "folder/filename.txt" as key
-  // Third argument is optional, it can be used to set content type ... default is 'application/octet-stream'
-  const resp: Response = await s3client.putObject(smallObjectKey, smallObjectContent);
-  // example with content type:
-  // const resp: Response = await s3client.putObject(smallObjectKey, smallObjectContent, 'image/png');
-  // you can also get etag via getEtag method
-  // const etag: string = await s3client.getEtag(smallObjectKey);
-  etag = sanitizeETag(resp.headers.get('etag'));
+// 3. Complete upload
+const result = await s3.completeMultipartUpload(key, uploadId, parts);
+console.log('Final ETag:', result.etag);
+```
+
+**Parallel uploads with progress:**
+
+```typescript
+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);
 }
+```
+
+**Abort an incomplete upload:**
+
+```typescript
+await s3.abortMultipartUpload(key, uploadId);
+```
+
+**List pending multipart uploads:**
 
-// get the object, null if not found
-const objectData: string | null = await s3client.getObject(smallObjectKey);
-console.log('Object data:', objectData);
-
-// get the object with ETag, null if not found
-const response2: Response = await S3mini.getObject(smallObjectKey, { 'if-none-match': etag });
-if (response2) {
-  // ETag changed so we can get the object data and new ETag
-  // Note: ETag is not guaranteed to be the same as the MD5 hash of the object
-  // ETag is sanitized to remove quotes
-  const etag2: string = sanitizeETag(response2.headers.get('etag'));
-  console.log('Object data with ETag:', response2.body, 'ETag:', etag2);
-} else {
-  console.log('Object not found or ETag does match.');
+```typescript
+const pending = await s3.listMultipartUploads();
+// Clean up orphaned uploads
+for (const upload of pending.Upload || []) {
+  await s3.abortMultipartUpload(upload.Key, upload.UploadId);
 }
+```
+
+---
+
+## Downloading Objects
+
+```typescript
+// As string
+const text = await s3.getObject('file.txt');
 
-// list objects in the bucket, null if bucket is empty
-// Note: listObjects uses listObjectsV2 API and iterate over all pages
-// so it will return all objects in the bucket which can take a while
-// If you want to limit the number of objects returned, use the maxKeys option
-// If you want to list objects in a specific "folder", use "folder/" as prefix
-// Example s3client.listObjects({"/" "myfolder/"})
-const list: object[] | null = await s3client.listObjects();
-if (list) {
-  console.log('List of objects:', list);
-} else {
-  console.log('No objects found in the bucket.');
+// 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)
+);
+```
+
+---
+
+## Listing Objects
+
+```typescript
+// 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);
+```
+
+**Response shape:**
+
+```typescript
+interface ListObject {
+  Key: string;
+  Size: number;
+  LastModified: Date;
+  ETag: string;
+  StorageClass: string;
 }
+```
+
+---
+
+## Deleting Objects
+
+```typescript
+// 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 and Move
+
+Server-side copy (no data transfer through client):
+
+```typescript
+// 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');
+```
+
+**Options:**
 
-// list objects in the bucket, 10 at a time using pagination token
-let results = await s3.listObjectsPaged('/', undefined, 10, undefined);
-while (results?.objects?.length) {
-  console.log('List of objects in this page:', results);
-  results = await s3.listObjectsPaged('/', undefined, 10, results.nextContinuationToken);
+```typescript
+interface CopyObjectOptions {
+  metadataDirective?: 'COPY' | 'REPLACE';
+  metadata?: Record;
+  contentType?: string;
+  storageClass?: string;
+  taggingDirective?: 'COPY' | 'REPLACE';
+  sourceSSECHeaders?: SSECHeaders;
+  destinationSSECHeaders?: SSECHeaders;
+  additionalHeaders?: AWSHeaders;
 }
+```
 
-// delete the object
-const wasDeleted: boolean = await s3client.deleteObject(smallObjectKey);
-// to delete multiple objects, use deleteObjects method
-// const keysToDelete: string[] = ['object1.txt', 'object2.txt'];
-// const deletedArray: boolean[] = await s3client.deleteObjects(keysToDelete);
-// Note: deleteObjects returns an array of booleans, one for each key, indicating if the object was deleted or not
-
-// Multipart upload
-const multipartKey = 'multipart-object.txt';
-const large_buffer = new Uint8Array(1024 * 1024 * 15); // 15 MB buffer
-const partSize = 8 * 1024 * 1024; // 8 MB
-const totalParts = Math.ceil(large_buffer.length / partSize);
-// Beware! This will return always a new uploadId
-// if you want to use the same uploadId, you need to store it somewhere
-const uploadId = await s3client.getMultipartUploadId(multipartKey);
-const uploadPromises = [];
-for (let i = 0; i < totalParts; i++) {
-  const partBuffer = large_buffer.subarray(i * partSize, (i + 1) * partSize);
-  // upload each part
-  // Note: uploadPart returns a promise, so you can use Promise.all to upload all parts in parallel
-  // but be careful with the number of parallel uploads, it can cause throttling
-  // or errors if you upload too many parts at once
-  // You can also use generator functions to upload parts in batches
-  uploadPromises.push(s3client.uploadPart(multipartKey, uploadId, partBuffer, i + 1));
+---
+
+## Conditional Requests
+
+Use If-\* headers to avoid unnecessary transfers:
+
+```typescript
+// 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
+```
+
+---
+
+## Pre-signed URLs
+
+Generate time-limited URLs that allow unauthenticated HTTP clients to upload or download objects directly — no credentials needed on the client side.
+
+```typescript
+// Download URL (valid for 1 hour by default)
+const downloadUrl = await s3.getPresignedUrl('GET', 'photos/vacation.jpg');
+
+// Upload URL (valid for 5 minutes)
+const uploadUrl = await s3.getPresignedUrl('PUT', 'uploads/file.bin', 300);
+```
+
+**Client-side usage (no SDK or credentials required):**
+
+```typescript
+// Upload via pre-signed URL
+await fetch(uploadUrl, {
+  method: 'PUT',
+  body: fileData,
+  headers: { 'Content-Type': 'image/jpeg' },
+});
+
+// Download via pre-signed URL
+const response = await fetch(downloadUrl);
+const data = await response.arrayBuffer();
+```
+
+**Custom response headers:**
+
+```typescript
+// Force download with a specific filename
+const url = await s3.getPresignedUrl('GET', 'report.pdf', 3600, {
+  'response-content-disposition': 'attachment; filename="report.pdf"',
+  'response-content-type': 'application/pdf',
+});
+```
+
+**Method signature:**
+
+```typescript
+getPresignedUrl(
+  method: 'GET' | 'PUT',
+  key: string,
+  expiresIn?: number,           // Default: 3600 (1 hour), max: 604800 (7 days)
+  queryParams?: Record<string, string>,
+): Promise<string>
+```
+
+**Notes:**
+
+- `expiresIn` must be between 1 and 604800 seconds (7 days); non-integer values are floored.
+- Works with both virtual-hosted-style and path-style endpoints.
+- Special characters and unicode in keys are handled automatically.
+- Throws `TypeError` for empty keys or out-of-range `expiresIn`.
+
+---
+
+## Server-Side Encryption (SSE-C)
+
+Customer-provided encryption keys (tested on Cloudflare R2):
+
+```typescript
+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,
+});
+```
+
+---
+
+## API Reference
+
+### Constructor
+
+| Parameter             | Type           | Default            | Description               |
+| --------------------- | -------------- | ------------------ | ------------------------- |
+| `accessKeyId`         | `string`       | required           | AWS access key            |
+| `secretAccessKey`     | `string`       | required           | AWS secret key            |
+| `endpoint`            | `string`       | required           | Full S3 endpoint URL      |
+| `region`              | `string`       | `'auto'`           | AWS region                |
+| `minPartSize`         | `number`       | `8388608`          | Multipart threshold (8MB) |
+| `requestAbortTimeout` | `number`       | `undefined`        | Request timeout in ms     |
+| `logger`              | `Logger`       | `undefined`        | Custom logger             |
+| `fetch`               | `typeof fetch` | `globalThis.fetch` | Custom fetch              |
+
+### Methods
+
+| Method                                                             | Returns                                     | Description             |
+| ------------------------------------------------------------------ | ------------------------------------------- | ----------------------- |
+| `bucketExists()`                                                   | `Promise<boolean>`                          | Check if bucket exists  |
+| `createBucket()`                                                   | `Promise<boolean>`                          | Create bucket           |
+| `listObjects(delimiter?, prefix?, maxKeys?)`                       | `Promise<ListObject[] \| null>`             | List all objects        |
+| `listObjectsPaged(delimiter?, prefix?, maxKeys?, token?)`          | `Promise<{objects, nextContinuationToken}>` | Paginated list          |
+| `getObject(key, opts?, ssec?)`                                     | `Promise<string \| null>`                   | Get object as string    |
+| `getObjectArrayBuffer(key, opts?, ssec?)`                          | `Promise<ArrayBuffer \| null>`              | Get as ArrayBuffer      |
+| `getObjectJSON<T>(key, opts?, ssec?)`                              | `Promise<T \| null>`                        | Get as parsed JSON      |
+| `getObjectResponse(key, opts?, ssec?)`                             | `Promise<Response \| null>`                 | Get full Response       |
+| `getObjectWithETag(key, opts?, ssec?)`                             | `Promise<{etag, data}>`                     | Get with ETag           |
+| `getObjectRaw(key, wholeFile?, from?, to?, opts?, ssec?)`          | `Promise<Response>`                         | Range request           |
+| `putObject(key, data, type?, ssec?, headers?, length?)`            | `Promise<Response>`                         | Simple upload           |
+| `putAnyObject(key, data, type?, ssec?, headers?, length?)`         | `Promise<Response>`                         | Smart upload            |
+| `deleteObject(key)`                                                | `Promise<boolean>`                          | Delete single object    |
+| `deleteObjects(keys)`                                              | `Promise<boolean[]>`                        | Delete multiple         |
+| `objectExists(key, opts?)`                                         | `Promise<boolean \| null>`                  | Check existence         |
+| `getEtag(key, opts?, ssec?)`                                       | `Promise<string \| null>`                   | Get ETag only           |
+| `getContentLength(key, ssec?)`                                     | `Promise<number>`                           | Get size in bytes       |
+| `copyObject(source, dest, opts?)`                                  | `Promise<CopyObjectResult>`                 | Server-side copy        |
+| `moveObject(source, dest, opts?)`                                  | `Promise<CopyObjectResult>`                 | Copy + delete           |
+| `getPresignedUrl(method, key, expiresIn?, queryParams?)`           | `Promise<string>`                           | Generate pre-signed URL |
+| `getMultipartUploadId(key, type?, ssec?, headers?)`                | `Promise<string>`                           | Init multipart          |
+| `uploadPart(key, uploadId, data, partNum, opts?, ssec?, headers?)` | `Promise<UploadPart>`                       | Upload part             |
+| `completeMultipartUpload(key, uploadId, parts)`                    | `Promise<CompleteResult>`                   | Complete multipart      |
+| `abortMultipartUpload(key, uploadId, ssec?)`                       | `Promise<object>`                           | Abort multipart         |
+| `listMultipartUploads(delimiter?, prefix?, method?, opts?)`        | `Promise<object>`                           | List pending            |
+| `sanitizeETag(etag)`                                               | `string`                                    | Remove quotes from ETag |
+
+### Utility Functions
+
+```typescript
+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'
+```
+
+---
+
+## Error Handling
+
+```typescript
+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.
+  }
 }
-const uploadResponses = await Promise.all(uploadPromises);
-const parts = uploadResponses.map((response, index) => ({
-  partNumber: index + 1,
-  etag: response.etag,
-}));
-// Complete the multipart upload
-const completeResponse = await s3client.completeMultipartUpload(multipartKey, uploadId, parts);
-const completeEtag = completeResponse.etag;
-
-// List multipart uploads
-// returns object with uploadId and key
-const multipartUploads: object = await s3client.listMultipartUploads();
-// Abort the multipart upload
-const abortResponse = await s3client.abortMultipartUpload(multipartUploads.key, multipartUploads.uploadId);
-
-// Multipart download
-// lets test getObjectRaw with range
-const rangeStart = 2048 * 1024; // 2 MB
-const rangeEnd = 8 * 1024 * 1024 * 2; // 16 MB
-const rangeResponse = await s3client.getObjectRaw(multipartKey, false, rangeStart, rangeEnd);
-const rangeData = await rangeResponse.arrayBuffer();
-
-// Local copyObject example
-const result = await s3.copyObject('report-2024.pdf', 'archive/report-2024.pdf');
 ```
 
-For more check [USAGE.md](USAGE.md) file, examples and tests.
+**Error classes:**
+
+- `S3Error` — Base error class
+- `S3ServiceError` — S3 returned an error response (4xx, 5xx)
+- `S3NetworkError` — Network-level failure (DNS, timeout, connection refused)
+
+---
+
+## Cloudflare Workers
+
+Works natively without `nodejs_compat`:
+
+```typescript
+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);
+  },
+};
+```
+
+---
+
+## Supported Operations
+
+| Operation               | Method                                                                                                                     |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| HeadBucket              | `bucketExists()`                                                                                                           |
+| CreateBucket            | `createBucket()`                                                                                                           |
+| ListObjectsV2           | `listObjects()`, `listObjectsPaged()`                                                                                      |
+| GetObject               | `getObject()`, `getObjectArrayBuffer()`, `getObjectJSON()`, `getObjectResponse()`, `getObjectWithETag()`, `getObjectRaw()` |
+| PutObject               | `putObject()`, `putAnyObject()`                                                                                            |
+| DeleteObject            | `deleteObject()`                                                                                                           |
+| DeleteObjects           | `deleteObjects()`                                                                                                          |
+| HeadObject              | `objectExists()`, `getEtag()`, `getContentLength()`                                                                        |
+| CopyObject              | `copyObject()`, `moveObject()`                                                                                             |
+| CreateMultipartUpload   | `getMultipartUploadId()`                                                                                                   |
+| UploadPart              | `uploadPart()`                                                                                                             |
+| CompleteMultipartUpload | `completeMultipartUpload()`                                                                                                |
+| AbortMultipartUpload    | `abortMultipartUpload()`                                                                                                   |
+| ListMultipartUploads    | `listMultipartUploads()`                                                                                                   |
+| Pre-signed URLs         | `getPresignedUrl()`                                                                                                        |
+
+---
 
 ## Security Notes