s3mini 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Peter Jensen (good-lly)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+# s3mini | Tiny & fast S3 client built for the edge.
+
+`s3mini` is an ultra-lightweight TypeScript client (~14 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, and MinIO. (No Browser support!)
+
+## Features
+
+- 🚀 Light and fast: averages ≈15 % more ops/s and only ~14 KB (minified, not gzipped).
+- 🔧 Zero dependencies; supports AWS SigV4 (no pre-signed requests).
+- 🟠 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.
+- 📦 **BYOS3** — _Bring your own S3-compatible bucket_ (tested on Cloudflare R2, Backblaze B2, DigitalOcean Spaces, MinIO; Ceph and Garage are in the queue).
+
+![GitHub Repo stars](https://img.shields.io/github/stars/good-lly/s3mini?style=social)
+![GitHub License](https://img.shields.io/github/license/good-lly/s3mini)
+
+Dev:
+![GitHub package.json version](https://img.shields.io/github/package-json/v/good-lly/s3mini?color=green)
+![GitHub commit activity](https://img.shields.io/github/commit-activity/m/good-lly/s3mini)
+[![CodeQL Advanced](https://github.com/good-lly/s3mini/actions/workflows/codeql.yml/badge.svg?branch=dev)](https://github.com/good-lly/s3mini/actions/workflows/codeql.yml)
+[![Test:e2e(all)](https://github.com/good-lly/s3mini/actions/workflows/test-e2e.yml/badge.svg?branch=dev)](https://github.com/good-lly/s3mini/actions/workflows/test-e2e.yml)
+
+![performance-image](https://raw.githubusercontent.com/good-lly/s3mini/dev/performance-screenshot.png)
+
+## Table of Contents
+
+- [Supported Ops](#supported-ops)
+- [Installation](#installation)
+- [Usage](#usage)
+- [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)
+- ✅ GetObject (getObject, getObjectWithETag, getObjectRaw, getObjectArrayBuffer)
+- ✅ PutObject (putObject)
+- ✅ DeleteObject (deleteObject)
+- ✅ HeadObject (objectExists, getEtag, getContentLength)
+- ✅ listMultipartUploads
+- ✅ CreateMultipartUpload (getMultipartUploadId)
+- ✅ completeMultipartUpload
+- ✅ abortMultipartUpload
+- ✅ uploadPart
+- ❌ CopyObject: Not implemented (tbd)
+
+## Installation
+
+```bash
+npm install s3mini
+```
+
+```bash
+yarn add s3mini
+```
+
+```bash
+pnpm add s3mini
+```
+
+## Usage
+
+```typescript
+import { s3mini, sanitizeETag } from 's3mini';
+
+const s3client = new s3mini({
+  accessKeyId: config.accessKeyId,
+  secretAccessKey: config.secretAccessKey,
+  endpoint: config.endpoint,
+  region: config.region,
+});
+
+// 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();
+}
+
+// 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
+  const resp: Response = await s3client.putObject(smallObjectKey, smallObjectContent);
+  // you can also get etag via getEtag method
+  // const etag: string = await s3client.getEtag(smallObjectKey);
+  etag = sanitizeETag(resp.headers.get('etag'));
+}
+
+// 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 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.');
+}
+
+// delete the object
+const wasDeleted: boolean = await s3client.deleteObject(smallObjectKey);
+
+// 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));
+}
+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();
+```
+
+For more check [USAGE.md](USAGE.md) file, examples and tests.
+
+## Security Notes
+
+- The library masks sensitive information (access keys, session tokens, etc.) when logging.
+- Always protect your AWS credentials and avoid hard-coding them in your application (!!!). Use environment variables. Use environment variables or a secure vault for storing credentials.
+- Ensure you have the necessary permissions to access the S3 bucket and perform operations.
+- Be cautious when using multipart uploads, as they can incur additional costs if not managed properly.
+- Authors are not responsible for any data loss or security breaches resulting from improper usage of the library.
+- If you find a security vulnerability, please report it to us directly via email. For more details, please refer to the [SECURITY.md](SECURITY.md) file.
+
+## Contributions welcomed!
+
+Contributions are greatly appreciated! If you have an idea for a new feature or have found a bug, we encourage you to get involved:
+
+- _Report Issues_: If you encounter a problem or have a feature request, please open an issue on GitHub. Include as much detail as possible (environment, error messages, logs, steps to reproduce, etc.) so we can understand and address the issue.
+
+- _Pull Requests_: We welcome PRs! If you want to implement a new feature or fix a bug, feel free to submit a pull request to the latest `dev branch`. For major changes, it's a good idea to discuss your plans in an issue first.
+
+- _Lightweight Philosophy_: When contributing, keep in mind that s3mini aims to remain lightweight and dependency-free. Please avoid adding heavy dependencies. New features should provide significant value to justify any increase in size.
+
+- _Community Conduct_: Be respectful and constructive in communications. We want a welcoming environment for all contributors. For more details, please refer to our [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). No one reads it, but it's there for a reason.
+
+If you figure out a solution to your question or problem on your own, please consider posting the answer or closing the issue with an explanation. It could help the next person who runs into the same thing!
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.

package/dist/s3mini.d.ts

@@ -0,0 +1,187 @@
+interface S3Config {
+    accessKeyId: string;
+    secretAccessKey: string;
+    endpoint: string;
+    region?: string;
+    requestSizeInBytes?: number;
+    requestAbortTimeout?: number;
+    logger?: Logger;
+}
+interface Logger {
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+}
+interface UploadPart {
+    partNumber: number;
+    etag: string;
+}
+interface CompleteMultipartUploadResult {
+    location: string;
+    bucket: string;
+    key: string;
+    etag: string;
+    eTag: string;
+    ETag: string;
+}
+interface ListBucketResult {
+    keyCount: string;
+    contents?: Array<Record<string, unknown>>;
+}
+interface ListBucketError {
+    error: {
+        code: string;
+        message: string;
+    };
+}
+type ListBucketResponse = {
+    listBucketResult: ListBucketResult;
+} | {
+    error: ListBucketError;
+};
+interface ListMultipartUploadSuccess {
+    listMultipartUploadsResult: {
+        bucket: string;
+        key: string;
+        uploadId: string;
+        size?: number;
+        mtime?: Date | undefined;
+        etag?: string;
+        eTag?: string;
+        parts: UploadPart[];
+        isTruncated: boolean;
+        uploads: UploadPart[];
+    };
+}
+interface MultipartUploadError {
+    error: {
+        code: string;
+        message: string;
+    };
+}
+interface ErrorWithCode {
+    code?: string;
+    cause?: {
+        code?: string;
+    };
+}
+type ListMultipartUploadResponse = ListMultipartUploadSuccess | MultipartUploadError;
+type HttpMethod = 'POST' | 'GET' | 'HEAD' | 'PUT' | 'DELETE';
+type ExistResponseCode = false | true | null;
+
+/**
+ * S3 class for interacting with S3-compatible object storage services.
+ * This class provides methods for common S3 operations such as uploading, downloading,
+ * and deleting objects, as well as multipart uploads.
+ *
+ * @class
+ * @example
+ * const s3 = new CoreS3({
+ *   accessKeyId: 'your-access-key',
+ *   secretAccessKey: 'your-secret-key',
+ *   endpoint: 'https://your-s3-endpoint.com',
+ *   region: 'us-east-1' // by default is auto
+ * });
+ *
+ * // Upload a file
+ * await s3.putObject('example.txt', 'Hello, World!');
+ *
+ * // Download a file
+ * const content = await s3.getObject('example.txt');
+ *
+ * // Delete a file
+ * await s3.deleteObject('example.txt');
+ */
+declare class s3mini {
+    /**
+     * Creates an instance of the S3 class.
+     *
+     * @constructor
+     * @param {Object} config - Configuration options for the S3 instance.
+     * @param {string} config.accessKeyId - The access key ID for authentication.
+     * @param {string} config.secretAccessKey - The secret access key for authentication.
+     * @param {string} config.endpoint - The endpoint URL of the S3-compatible service.
+     * @param {string} [config.region='auto'] - The region of the S3 service.
+     * @param {number} [config.requestSizeInBytes=8388608] - The request size of a single request in bytes (AWS S3 is 8MB).
+     * @param {number} [config.requestAbortTimeout=undefined] - The timeout in milliseconds after which a request should be aborted (careful on streamed requests).
+     * @param {Object} [config.logger=null] - A logger object with methods like info, warn, error.
+     * @throws {TypeError} Will throw an error if required parameters are missing or of incorrect type.
+     */
+    private accessKeyId;
+    private secretAccessKey;
+    private endpoint;
+    private region;
+    private requestSizeInBytes;
+    private requestAbortTimeout?;
+    private logger?;
+    private fullDatetime;
+    private shortDatetime;
+    private signingKey;
+    private credentialScope;
+    constructor({ accessKeyId, secretAccessKey, endpoint, region, requestSizeInBytes, requestAbortTimeout, logger, }: S3Config);
+    private _sanitize;
+    private _log;
+    private _validateConstructorParams;
+    private _ensureValidUrl;
+    private _validateMethodIsGetOrHead;
+    private _checkKey;
+    private _checkDelimiter;
+    private _checkPrefix;
+    private _checkOpts;
+    private _filterIfHeaders;
+    private _validateUploadPartParams;
+    private _sign;
+    private _buildCanonicalHeaders;
+    private _buildCanonicalRequest;
+    private _buildStringToSign;
+    private _calculateSignature;
+    private _buildAuthorizationHeader;
+    private _signedRequest;
+    getProps(): S3Config;
+    setProps(props: S3Config): void;
+    sanitizeETag(etag: string): string;
+    createBucket(): Promise<boolean>;
+    bucketExists(): Promise<boolean>;
+    listObjects(delimiter?: string, prefix?: string, maxKeys?: number, opts?: Record<string, unknown>): Promise<object[] | null>;
+    listMultipartUploads(delimiter?: string, prefix?: string, method?: HttpMethod, opts?: Record<string, string | number | boolean | undefined>): Promise<ListMultipartUploadSuccess | MultipartUploadError>;
+    getObject(key: string, opts?: Record<string, unknown>): Promise<string | null>;
+    getObjectArrayBuffer(key: string, opts?: Record<string, unknown>): Promise<ArrayBuffer | null>;
+    getObjectWithETag(key: string, opts?: Record<string, unknown>): Promise<{
+        etag: string | null;
+        data: ArrayBuffer | null;
+    }>;
+    getObjectRaw(key: string, wholeFile?: boolean, rangeFrom?: number, rangeTo?: number, opts?: Record<string, unknown>): Promise<Response>;
+    getContentLength(key: string): Promise<number>;
+    objectExists(key: string, opts?: Record<string, unknown>): Promise<ExistResponseCode>;
+    getEtag(key: string, opts?: Record<string, unknown>): Promise<string | null>;
+    putObject(key: string, data: string | Buffer): Promise<Response>;
+    getMultipartUploadId(key: string, fileType?: string): Promise<string>;
+    uploadPart(key: string, uploadId: string, data: Buffer | string, partNumber: number, opts?: Record<string, unknown>): Promise<UploadPart>;
+    completeMultipartUpload(key: string, uploadId: string, parts: Array<UploadPart>): Promise<CompleteMultipartUploadResult>;
+    abortMultipartUpload(key: string, uploadId: string): Promise<object>;
+    private _buildCompleteMultipartUploadXml;
+    deleteObject(key: string): Promise<boolean>;
+    private _sendRequest;
+    private _handleErrorResponse;
+    private _buildCanonicalQueryString;
+    private _getSignatureKey;
+}
+
+/**
+ * Sanitize ETag value by removing quotes and XML entities
+ * @param etag ETag value to sanitize
+ * @returns Sanitized ETag
+ */
+declare const sanitizeETag: (etag: string) => string;
+/**
+ * Run async-returning tasks in batches with an *optional* minimum
+ * spacing (minIntervalMs) between the *start* times of successive batches.
+ *
+ * @param {Iterable<() => Promise<unknonw>>} tasks       – functions returning Promises
+ * @param {number} [batchSize=30]                    – max concurrent requests
+ * @param {number} [minIntervalMs=0]                 – ≥0; 0 means “no pacing”
+ * @returns {Promise<Array<PromiseSettledResult<unknonw>>>}
+ */
+declare const runInBatches: (tasks: Iterable<() => Promise<unknown>>, batchSize?: number, minIntervalMs?: number) => Promise<Array<PromiseSettledResult<unknown>>>;
+
+export { type CompleteMultipartUploadResult, type ErrorWithCode, type ExistResponseCode, type ListBucketResponse, type ListMultipartUploadResponse, type Logger, type S3Config, type UploadPart, s3mini as default, runInBatches, s3mini, sanitizeETag };