s3mini 0.9.3 → 0.9.4

package/README.md

@@ -2,13 +2,17 @@
 
 `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!)
 
+![Node.js](https://img.shields.io/badge/node.js-6DA55F?style=for-the-badge&logo=node.js&logoColor=white)
+![Bun](https://img.shields.io/badge/Bun-%23000000.svg?style=for-the-badge&logo=bun&logoColor=white)
+![Cloudflare](https://img.shields.io/badge/Cloudflare-F38020?style=for-the-badge&logo=Cloudflare&logoColor=white)
+
 [[github](https://github.com/good-lly/s3mini)]
 [[issues](https://github.com/good-lly/s3mini/issues)]
 [[npm](https://www.npmjs.com/package/s3mini)]
 
 ## Features
 
-- 🚀 Light and fast: averages ≈15 % more ops/s and only ~20 KB (minified, not gzipped).
+- 🚀 Light and fast: ~20 KB (minified, not gzipped), up to 1.37x faster on Bun vs Node.
 - 🔧 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.
@@ -44,6 +48,10 @@ 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>
 
+### Bun vs Node
+
+s3mini is tested on both Node and Bun. In our benchmarks against MinIO, Bun is roughly **~1.4x faster** on most operations (median across ~40 tests). Blob multipart uploads see the largest gain (~20x) thanks to Bun's native `Blob.slice()`. Results are approximate and will vary by environment.
+
 ## Table of Contents
 
 - [Installation](#installation)

package/dist/s3mini.d.ts

@@ -164,6 +164,7 @@ declare class S3mini {
     readonly logger?: Logger;
     readonly _fetch: typeof fetch;
     readonly minPartSize: number;
+    private readonly _bun?;
     private signingKeyDate?;
     private signingKey?;
     constructor({ accessKeyId, secretAccessKey, endpoint, region, requestSizeInBytes, requestAbortTimeout, logger, fetch, minPartSize, }: S3Config);
@@ -175,6 +176,8 @@ declare class S3mini {
      * @returns true if both accessKeyId and secretAccessKey are non-empty.
      */
     private _hasCredentials;
+    /** Run a read op via Bun-native S3, returning null on NoSuchKey. */
+    private _bunRead;
     private _ensureValidUrl;
     private _validateMethodIsGetOrHead;
     private _checkKey;
@@ -249,6 +252,10 @@ declare class S3mini {
     private _parseListObjectsResponse;
     private _extractObjectsFromResponse;
     private _extractContinuationToken;
+    private _bunListAll;
+    private _bunFetchPage;
+    private _bunNextCursor;
+    private _bunMapListResult;
     /**
      * Lists multipart uploads in the bucket.
      * This method sends a request to list multipart uploads in the specified bucket.
@@ -579,6 +586,9 @@ declare class S3mini {
      */
     deleteObject(key: string): Promise<boolean>;
     private _deleteObjectsProcess;
+    private _sendDeleteRequest;
+    private _markDeletedKeys;
+    private _logDeleteErrors;
     /**
      * Deletes multiple objects from the bucket.
      * @param {string[]} keys - An array of object keys to delete.

package/dist/s3mini.js

@@ -31,6 +31,21 @@ const ERROR_UPLOAD_ID_REQUIRED = `${ERROR_PREFIX}uploadId must be a non-empty st
 const ERROR_PREFIX_TYPE = `${ERROR_PREFIX}prefix must be a string`;
 const ERROR_DELIMITER_REQUIRED = `${ERROR_PREFIX}delimiter must be a string`;
 
+const isBun = typeof navigator !== 'undefined' && navigator.userAgent === 'Bun';
+/** Strips the bucket name from a full endpoint URL, returning the base origin for Bun.S3Client. */
+const extractBaseEndpoint = (endpoint, bucket) => {
+    // Path-style (/bucket/…): just use the origin
+    if (endpoint.pathname.split('/').some(Boolean)) {
+        return endpoint.origin;
+    }
+    // Virtual-hosted (bucket.host…): strip the bucket subdomain
+    const prefix = bucket + '.';
+    if (endpoint.hostname.startsWith(prefix)) {
+        const base = endpoint.hostname.slice(prefix.length);
+        return `${endpoint.protocol}//${base}${endpoint.port ? ':' + endpoint.port : ''}`;
+    }
+    return endpoint.origin;
+};
 const ENCODR = new TextEncoder();
 const chunkSize = 0x8000; // 32KB chunks
 const HEX_CHARS = new Uint8Array([48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 97, 98, 99, 100, 101, 102]);
@@ -398,6 +413,7 @@ class S3mini {
     logger;
     _fetch;
     minPartSize;
+    _bun;
     signingKeyDate;
     signingKey;
     constructor({ accessKeyId, secretAccessKey, endpoint, region = 'auto', requestSizeInBytes = DEFAULT_REQUEST_SIZE_IN_BYTES, requestAbortTimeout = undefined, logger = undefined, fetch = globalThis.fetch, minPartSize = MIN_PART_SIZE, }) {
@@ -412,6 +428,16 @@ class S3mini {
         this.logger = logger;
         this._fetch = (input, init) => fetch(input, init);
         this.minPartSize = minPartSize;
+        if (isBun) {
+            const { S3Client } = globalThis.Bun;
+            this._bun = new S3Client({
+                accessKeyId,
+                secretAccessKey,
+                endpoint: extractBaseEndpoint(this.endpoint, this.bucketName),
+                region: this.region,
+                bucket: this.bucketName,
+            });
+        }
     }
     _sanitize(obj) {
         if (typeof obj !== 'object' || obj === null) {
@@ -472,6 +498,18 @@ class S3mini {
     _hasCredentials() {
         return this.#accessKeyId.trim().length > 0 && this.#secretAccessKey.trim().length > 0;
     }
+    /** Run a read op via Bun-native S3, returning null on NoSuchKey. */
+    async _bunRead(key, op) {
+        try {
+            return await op(this._bun.file(key));
+        }
+        catch (e) {
+            if (e?.code === 'NoSuchKey') {
+                return null;
+            }
+            throw e;
+        }
+    }
     _ensureValidUrl(raw) {
         const candidate = /^(https?:)?\/\//i.test(raw) ? raw : `https://${raw}`;
         try {
@@ -677,32 +715,24 @@ class S3mini {
     }
     _extractBucketName() {
         const url = this.endpoint;
-        // First check if bucket is in the pathname (path-style URLs)
-        const pathSegments = url.pathname.split('/').filter(Boolean);
-        if (pathSegments.length > 0) {
-            if (typeof pathSegments[0] === 'string') {
-                return pathSegments[0];
-            }
+        // Path-style: bucket is the first non-empty path segment
+        const firstSegment = url.pathname.split('/').find(Boolean);
+        if (firstSegment) {
+            return firstSegment;
+        }
+        // Virtual-hosted style: bucket is the first subdomain label
+        const hostname = url.hostname;
+        // IP addresses (v4: digits+dots, v6: contains colons) can't carry a bucket subdomain
+        if (/^\d+\.\d+\.\d+\.\d+$/.test(hostname) || hostname.includes(':')) {
+            return '';
         }
-        // Otherwise extract from subdomain (virtual-hosted-style URLs)
-        const hostParts = url.hostname.split('.');
-        // Common patterns:
-        // bucket-name.s3.amazonaws.com
-        // bucket-name.s3.region.amazonaws.com
-        // bucket-name.region.digitaloceanspaces.com
-        // bucket-name.region.cdn.digitaloceanspaces.com
-        if (hostParts.length >= 3) {
-            // Check if it's a known S3-compatible service
-            const domain = hostParts.slice(-2).join('.');
-            const knownDomains = ['amazonaws.com', 'digitaloceanspaces.com', 'cloudflare.com'];
-            if (knownDomains.some(d => domain.includes(d))) {
-                if (typeof hostParts[0] === 'string') {
-                    return hostParts[0];
-                }
-            }
+        const labels = hostname.split('.');
+        // Need ≥3 labels for virtual-hosted (bucket.service.tld)
+        // Single-label (localhost) or two-label (example.com) have no room for a bucket subdomain
+        if (labels.length < 3) {
+            return '';
         }
-        // Fallback: use the first subdomain
-        return hostParts[0] || '';
+        return labels[0];
     }
     /**
      * Checks if a bucket exists.
@@ -732,6 +762,12 @@ class S3mini {
         this._checkDelimiter(delimiter);
         this._checkPrefix(prefix);
         this._checkOpts(opts);
+        if (this._bun && delimiter === '/') {
+            const extraKeys = Object.keys(opts).filter(k => k !== 'delimiter');
+            if (extraKeys.length === 0) {
+                return this._bunListAll(prefix, maxKeys, opts.delimiter);
+            }
+        }
         const keyPath = delimiter === '/' ? delimiter : uriEscape(delimiter);
         const unlimited = !(maxKeys && maxKeys > 0);
         let remaining = unlimited ? Infinity : maxKeys;
@@ -877,6 +913,71 @@ class S3mini {
             response.NextMarker ||
             response.nextMarker);
     }
+    async _bunListAll(prefix, maxKeys, delimiter) {
+        const unlimited = !(maxKeys && maxKeys > 0);
+        let remaining = unlimited ? Infinity : maxKeys;
+        let startAfter;
+        const all = [];
+        try {
+            do {
+                const batchSize = Math.min(remaining === Infinity ? 1000 : remaining, 1000);
+                const res = await this._bunFetchPage(prefix, delimiter, batchSize, startAfter);
+                const mapped = this._bunMapListResult(res);
+                all.push(...mapped);
+                if (!unlimited) {
+                    remaining -= mapped.length;
+                }
+                startAfter = this._bunNextCursor(res);
+            } while (startAfter && remaining > 0);
+        }
+        catch (e) {
+            if (e?.code === 'NoSuchBucket') {
+                return null;
+            }
+            throw e;
+        }
+        return all;
+    }
+    _bunFetchPage(prefix, delimiter, maxKeys, startAfter) {
+        return this._bun.list({
+            prefix: prefix || undefined,
+            delimiter: delimiter || '/',
+            maxKeys,
+            ...(startAfter ? { startAfter } : {}),
+        });
+    }
+    _bunNextCursor(res) {
+        if (!res.isTruncated) {
+            return undefined;
+        }
+        return res.contents?.length ? res.contents.at(-1).key : undefined;
+    }
+    _bunMapListResult(res) {
+        const objects = [];
+        if (res.contents) {
+            for (const item of res.contents) {
+                objects.push({
+                    Key: item.key,
+                    Size: item.size,
+                    LastModified: item.lastModified instanceof Date ? item.lastModified : new Date(item.lastModified),
+                    ETag: item.etag ?? '',
+                    StorageClass: item.storageClass ?? '',
+                });
+            }
+        }
+        if (res.commonPrefixes) {
+            for (const item of res.commonPrefixes) {
+                objects.push({
+                    Key: item.prefix,
+                    Size: 0,
+                    LastModified: new Date(0),
+                    ETag: '',
+                    StorageClass: '',
+                });
+            }
+        }
+        return objects;
+    }
     /**
      * Lists multipart uploads in the bucket.
      * This method sends a request to list multipart uploads in the specified bucket.
@@ -923,7 +1024,9 @@ class S3mini {
      * @returns A promise that resolves to the object data (string) or null if not found.
      */
     async getObject(key, opts = {}, ssecHeaders) {
-        // if ssecHeaders is set, add it to headers
+        if (this._bun && !ssecHeaders && !Object.keys(opts).length) {
+            return this._bunRead(key, f => f.text());
+        }
         const res = await this._signedRequest('GET', key, {
             query: opts, // use opts.query if it exists, otherwise use an empty object
             tolerated: [200, 404, 412, 304],
@@ -965,6 +1068,9 @@ class S3mini {
      * @returns A promise that resolves to the object data as an ArrayBuffer or null if not found.
      */
     async getObjectArrayBuffer(key, opts = {}, ssecHeaders) {
+        if (this._bun && !ssecHeaders && !Object.keys(opts).length) {
+            return this._bunRead(key, f => f.arrayBuffer());
+        }
         const res = await this._signedRequest('GET', key, {
             query: opts,
             tolerated: [200, 404, 412, 304],
@@ -985,6 +1091,9 @@ class S3mini {
      * @returns A promise that resolves to the object data as JSON or null if not found.
      */
     async getObjectJSON(key, opts = {}, ssecHeaders) {
+        if (this._bun && !ssecHeaders && !Object.keys(opts).length) {
+            return this._bunRead(key, f => f.json());
+        }
         const res = await this._signedRequest('GET', key, {
             query: opts,
             tolerated: [200, 404, 412, 304],
@@ -1005,6 +1114,19 @@ class S3mini {
      * @returns A promise that resolves to an object containing the ETag and the object data as an ArrayBuffer or null if not found.
      */
     async getObjectWithETag(key, opts = {}, ssecHeaders) {
+        if (this._bun && !ssecHeaders && !Object.keys(opts).length) {
+            try {
+                const f = this._bun.file(key);
+                const [stat, data] = await Promise.all([f.stat(), f.arrayBuffer()]);
+                return { etag: sanitizeETag(stat.etag), data };
+            }
+            catch (e) {
+                if (e?.code === 'NoSuchKey') {
+                    return { etag: null, data: null };
+                }
+                throw e;
+            }
+        }
         try {
             const res = await this._signedRequest('GET', key, {
                 query: opts,
@@ -1039,6 +1161,28 @@ class S3mini {
      * @returns A promise that resolves to the Response object.
      */
     async getObjectRaw(key, wholeFile = true, rangeFrom = 0, rangeTo, opts = {}, ssecHeaders) {
+        if (this._bun && !ssecHeaders && !Object.keys(opts).length) {
+            const f = this._bun.file(key);
+            if (wholeFile) {
+                const buf = await f.arrayBuffer();
+                const stat = await f.stat();
+                return new Response(buf, {
+                    status: 200,
+                    headers: { 'content-length': String(stat.size), etag: stat.etag, 'content-type': stat.type },
+                });
+            }
+            const sliced = rangeTo === undefined ? f.slice(rangeFrom) : f.slice(rangeFrom, rangeTo);
+            const buf = await sliced.arrayBuffer();
+            const stat = await f.stat();
+            const endByte = rangeTo === undefined ? stat.size - 1 : rangeTo - 1;
+            return new Response(buf, {
+                status: 206,
+                headers: {
+                    'content-range': `bytes ${rangeFrom}-${endByte}/${stat.size}`,
+                    'content-length': String(buf.byteLength),
+                },
+            });
+        }
         let rangeHdr = {};
         if (!wholeFile) {
             rangeHdr =
@@ -1059,6 +1203,9 @@ class S3mini {
      */
     async getContentLength(key, ssecHeaders) {
         try {
+            if (this._bun && !ssecHeaders) {
+                return (await this._bun.file(key).stat()).size;
+            }
             const res = await this._signedRequest('HEAD', key, {
                 headers: ssecHeaders ? { ...ssecHeaders } : undefined,
             });
@@ -1080,6 +1227,9 @@ class S3mini {
      * @returns A promise that resolves to true if the object exists, false if not found, or null if ETag mismatch.
      */
     async objectExists(key, opts = {}) {
+        if (this._bun && !Object.keys(opts).length) {
+            return this._bun.file(key).exists();
+        }
         const res = await this._signedRequest('HEAD', key, {
             query: opts,
             tolerated: [200, 404, 412, 304],
@@ -1106,6 +1256,15 @@ class S3mini {
      * }
      */
     async getEtag(key, opts = {}, ssecHeaders) {
+        if (this._bun && !ssecHeaders && !Object.keys(opts).length) {
+            return this._bunRead(key, async (f) => {
+                const { etag } = await f.stat();
+                if (!etag) {
+                    throw new Error(`${ERROR_PREFIX}ETag not found in response headers`);
+                }
+                return sanitizeETag(etag);
+            });
+        }
         const res = await this._signedRequest('HEAD', key, {
             query: opts,
             tolerated: [200, 304, 404, 412],
@@ -1141,6 +1300,12 @@ class S3mini {
      * await s3.putObject('image.png', buffer, 'image/png');
      */
     async putObject(key, data, fileType = DEFAULT_STREAM_CONTENT_TYPE, ssecHeaders, additionalHeaders, contentLength) {
+        if (this._bun && !ssecHeaders && !additionalHeaders) {
+            const f = this._bun.file(key);
+            await f.write(data, { type: fileType });
+            const { etag } = await f.stat();
+            return new Response(null, { status: 200, headers: etag ? { etag } : {} });
+        }
         const size = contentLength ?? getByteSize(data);
         return this._signedRequest('PUT', key, {
             body: data,
@@ -1173,6 +1338,14 @@ class S3mini {
      * await s3.putAnyObject('image.png', buffer, 'image/png');
      */
     async putAnyObject(key, data, fileType = DEFAULT_STREAM_CONTENT_TYPE, ssecHeaders, additionalHeaders, contentLength) {
+        // Bun handles multipart automatically for large files
+        if (this._bun && !ssecHeaders && !additionalHeaders) {
+            this._checkKey(key);
+            const f = this._bun.file(key);
+            await f.write(data, { type: fileType });
+            const { etag } = await f.stat();
+            return this._createSuccessResponse(etag || '');
+        }
         const size = contentLength ?? getByteSize(data);
         // Single PUT for small files
         if (!Number.isNaN(size) && size <= this.minPartSize) {
@@ -1635,72 +1808,74 @@ class S3mini {
      * @returns A promise that resolves to true if the object was deleted successfully, false otherwise.
      */
     async deleteObject(key) {
+        if (this._bun) {
+            await this._bun.file(key).delete();
+            return true;
+        }
         const res = await this._signedRequest('DELETE', key, { tolerated: [200, 204] });
         return res.status === 200 || res.status === 204;
     }
     async _deleteObjectsProcess(keys) {
+        const out = await this._sendDeleteRequest(keys);
+        const resultMap = new Map(keys.map(k => [k, false]));
+        this._markDeletedKeys(out, resultMap);
+        this._logDeleteErrors(out, resultMap);
+        return keys.map(key => resultMap.get(key) || false);
+    }
+    async _sendDeleteRequest(keys) {
         const objectsXml = keys.map(key => `<Object><Key>${escapeXml(key)}</Key></Object>`).join('');
         const xmlBody = '<Delete>' + objectsXml + '</Delete>';
-        const query = { delete: '' };
         const sha256base64 = base64FromBuffer(await sha256(xmlBody));
-        const headers = {
-            [HEADER_CONTENT_TYPE]: XML_CONTENT_TYPE,
-            [HEADER_CONTENT_LENGTH]: getByteSize(xmlBody),
-            [HEADER_AMZ_CHECKSUM_SHA256]: sha256base64,
-        };
         const res = await this._signedRequest('POST', '', {
-            query,
+            query: { delete: '' },
             body: xmlBody,
-            headers,
+            headers: {
+                [HEADER_CONTENT_TYPE]: XML_CONTENT_TYPE,
+                [HEADER_CONTENT_LENGTH]: getByteSize(xmlBody),
+                [HEADER_AMZ_CHECKSUM_SHA256]: sha256base64,
+            },
             withQuery: true,
         });
         const parsed = parseXml(await res.text());
         if (!parsed || typeof parsed !== 'object') {
             throw new Error(`${ERROR_PREFIX}Failed to delete objects: ${JSON.stringify(parsed)}`);
         }
-        const out = (parsed.DeleteResult || parsed.deleteResult || parsed);
-        const resultMap = new Map();
-        for (const key of keys) {
-            resultMap.set(key, false);
-        }
+        return (parsed.DeleteResult || parsed.deleteResult || parsed);
+    }
+    _markDeletedKeys(out, resultMap) {
         const deleted = out.deleted || out.Deleted;
-        if (deleted) {
-            const deletedArray = Array.isArray(deleted) ? deleted : [deleted];
-            for (const item of deletedArray) {
-                if (item && typeof item === 'object') {
-                    const obj = item;
-                    // Check both key and Key
-                    const key = obj.key || obj.Key;
-                    if (key && typeof key === 'string') {
-                        resultMap.set(key, true);
-                    }
+        if (!deleted) {
+            return;
+        }
+        const items = Array.isArray(deleted) ? deleted : [deleted];
+        for (const item of items) {
+            if (item && typeof item === 'object') {
+                const key = item.key || item.Key;
+                if (key && typeof key === 'string') {
+                    resultMap.set(key, true);
                 }
             }
         }
-        // Handle errors (check both cases)
+    }
+    _logDeleteErrors(out, resultMap) {
         const errors = out.error || out.Error;
-        if (errors) {
-            const errorsArray = Array.isArray(errors) ? errors : [errors];
-            for (const item of errorsArray) {
-                if (item && typeof item === 'object') {
-                    const obj = item;
-                    // Check both cases for all properties
-                    const key = obj.key || obj.Key;
-                    const code = obj.code || obj.Code;
-                    const message = obj.message || obj.Message;
-                    if (key && typeof key === 'string') {
-                        resultMap.set(key, false);
-                        // Optionally log the error for debugging
-                        this._log('warn', `Failed to delete object: ${key}`, {
-                            code: code || 'Unknown',
-                            message: message || 'Unknown error',
-                        });
-                    }
+        if (!errors) {
+            return;
+        }
+        const items = Array.isArray(errors) ? errors : [errors];
+        for (const item of items) {
+            if (item && typeof item === 'object') {
+                const obj = item;
+                const key = obj.key || obj.Key;
+                if (key && typeof key === 'string') {
+                    resultMap.set(key, false);
+                    this._log('warn', `Failed to delete object: ${key}`, {
+                        code: obj.code || obj.Code || 'Unknown',
+                        message: obj.message || obj.Message || 'Unknown error',
+                    });
                 }
             }
         }
-        // Return boolean array in the same order as input keys
-        return keys.map(key => resultMap.get(key) || false);
     }
     /**
      * Deletes multiple objects from the bucket.
@@ -1815,6 +1990,9 @@ class S3mini {
         if (!Number.isFinite(expiresIn) || expiresIn <= 0 || expiresIn > 604800) {
             throw new TypeError(`${ERROR_PREFIX}expiresIn must be between 1 and 604800 seconds`);
         }
+        if (this._bun && !Object.keys(queryParams).length && !Object.keys(headers).length) {
+            return this._bun.presign(key, { method, expiresIn: Math.floor(expiresIn) });
+        }
         return this._presign(method, uriResourceEscape(key), Math.floor(expiresIn), queryParams, headers);
     }
     async _presign(method, keyPath, expiresIn, queryParams, headers) {