s3mini 0.9.1 → 0.9.3

package/README.md

@@ -9,18 +9,18 @@
 ## Features
 
 - 🚀 Light and fast: averages ≈15 % more ops/s and only ~20 KB (minified, not gzipped).
-- 🔧 Zero dependencies; supports AWS SigV4 (no pre-signed requests) and SSE-C headers (tested only on Cloudflare)
+- 🔧 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:
@@ -46,39 +46,25 @@ Dev:
 
 ## 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
@@ -105,151 +91,628 @@ 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
+
+```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/');
 
-> [!WARNING]
-> `s3mini` was a deprecated alias removed in a recent `0.5.0` release. Please migrate to the new `S3mini` class.
+// 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);
+```
 
-// 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.');
+**List pending multipart uploads:**
+
+```typescript
+const pending = await s3.listMultipartUploads();
+// Clean up orphaned uploads
+for (const upload of pending.Upload || []) {
+  await s3.abortMultipartUpload(upload.Key, upload.UploadId);
 }
+```
 
-// 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.');
+---
+
+## Downloading Objects
+
+```typescript
+// 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)
+);
+```
+
+---
+
+## 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
 
-// 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);
+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:**
+
+```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',
+});
+```
+
+**Signed headers (enforce headers on the client request):**
+
+```typescript
+// Upload URL that requires Content-Type — client MUST send this exact header
+const url = await s3.getPresignedUrl('PUT', 'uploads/data.json', 300, {}, {
+  'Content-Type': 'application/json',
+});
+
+await fetch(url, {
+  method: 'PUT',
+  body: JSON.stringify({ ok: true }),
+  headers: { 'Content-Type': 'application/json' },
+});
+```
+
+**Method signature:**
+
+```typescript
+getPresignedUrl(
+  method: 'GET' | 'PUT',
+  key: string,
+  expiresIn?: number,           // Default: 3600 (1 hour), max: 604800 (7 days)
+  queryParams?: Record<string, string>,
+  headers?: Record<string, string>,  // HTTP headers to sign (e.g. Content-Type)
+): 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`.
+- When `headers` are provided, they are included in `X-Amz-SignedHeaders` and the signature. The client consuming the URL must send those exact headers with matching values. The `host` header is always signed automatically.
+
+---
+
+## 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?, headers?)` | `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