s3mini 0.1.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # s3mini | Tiny & fast S3 client for node and edge platforms.
 
-`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!)
+`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, Ceph, Oracle, Garage and MinIO. (No Browser support!)
 
 [[github](https://github.com/good-lly/s3mini)]
 [[issues](https://github.com/good-lly/s3mini/issues)]
@@ -12,7 +12,7 @@
 - 🔧 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 and Garage! Ceph and AWS are in the queue).
+- 📦 **BYOS3** — _Bring your own S3-compatible bucket_ (tested on Cloudflare R2, Backblaze B2, DigitalOcean Spaces, MinIO, Garage, Micro/Ceph and Oracle Object Storage).
 
 #### Tested On
 
@@ -31,6 +31,8 @@ Dev:
 ![npm package minimized gzipped size](https://img.shields.io/bundlejs/size/s3mini?color=green)
 ![GitHub License](https://img.shields.io/github/license/good-lly/s3mini)
 
+<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)
 
@@ -80,6 +82,15 @@ yarn add s3mini
 pnpm add s3mini
 ```
 
+### Environment Variables
+
+To use `s3mini`, you need to set up your environment variables for provider credentials and S3 endpoint. Create a `.env` file in your project root directory. Checkout the [example.env](example.env) file for reference.
+
+```bash
+# On Windows, Mac, or Linux
+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.
@@ -124,7 +135,10 @@ 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'));
@@ -214,17 +228,17 @@ For more check [USAGE.md](USAGE.md) file, examples and tests.
 - 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 welcomed! (in specific order)
 
-Contributions are greatly appreciated! If you have an idea for a new feature or have found a bug, we encourage you to get involved:
+Contributions are greatly appreciated! If you have an idea for a new feature or have found a bug, we encourage you to get involved in this order:
 
-- _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.
+1. _Open/Report Issues or Ideas_: If you encounter a problem, have an idea or a feature request, please open an issue on GitHub (FIRST!) . Be concise but include as much detail as necessary (environment, error messages, logs, steps to reproduce, etc.) so we can understand and address the issue and have a dialog.
 
-- _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.
+2. _Create 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 necessary 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.
+3. _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.
+4. _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!
 

package/dist/s3mini.d.ts

@@ -114,10 +114,8 @@ declare class s3mini {
     private requestSizeInBytes;
     private requestAbortTimeout?;
     private logger?;
-    private fullDatetime;
-    private shortDatetime;
-    private signingKey;
-    private credentialScope;
+    private signingKeyDate?;
+    private signingKey?;
     constructor({ accessKeyId, secretAccessKey, endpoint, region, requestSizeInBytes, requestAbortTimeout, logger, }: S3Config);
     private _sanitize;
     private _log;
@@ -133,36 +131,266 @@ declare class s3mini {
     private _sign;
     private _buildCanonicalHeaders;
     private _buildCanonicalRequest;
+    private _buildCredentialScope;
     private _buildStringToSign;
     private _calculateSignature;
     private _buildAuthorizationHeader;
     private _signedRequest;
+    /**
+     * Gets the current configuration properties of the S3 instance.
+     * @returns {IT.S3Config} The current S3 configuration object containing all settings.
+     * @example
+     * const config = s3.getProps();
+     * console.log(config.endpoint); // 'https://s3.amazonaws.com/my-bucket'
+     */
     getProps(): S3Config;
+    /**
+     * Updates the configuration properties of the S3 instance.
+     * @param {IT.S3Config} props - The new configuration object.
+     * @param {string} props.accessKeyId - The access key ID for authentication.
+     * @param {string} props.secretAccessKey - The secret access key for authentication.
+     * @param {string} props.endpoint - The endpoint URL of the S3-compatible service.
+     * @param {string} [props.region='auto'] - The region of the S3 service.
+     * @param {number} [props.requestSizeInBytes=8388608] - The request size of a single request in bytes.
+     * @param {number} [props.requestAbortTimeout] - The timeout in milliseconds after which a request should be aborted.
+     * @param {IT.Logger} [props.logger] - A logger object with methods like info, warn, error.
+     * @throws {TypeError} Will throw an error if required parameters are missing or of incorrect type.
+     * @example
+     * s3.setProps({
+     *   accessKeyId: 'new-access-key',
+     *   secretAccessKey: 'new-secret-key',
+     *   endpoint: 'https://new-endpoint.com/my-bucket',
+     *   region: 'us-west-2' // by default is auto
+     * });
+     */
     setProps(props: S3Config): void;
+    /**
+     * Sanitizes an ETag value by removing surrounding quotes and whitespace.
+     * Still returns RFC compliant ETag. https://www.rfc-editor.org/rfc/rfc9110#section-8.8.3
+     * @param {string} etag - The ETag value to sanitize.
+     * @returns {string} The sanitized ETag value.
+     * @example
+     * const cleanEtag = s3.sanitizeETag('"abc123"'); // Returns: 'abc123'
+     */
     sanitizeETag(etag: string): string;
+    /**
+     * Creates a new bucket.
+     * This method sends a request to create a new bucket in the specified in endpoint.
+     * @returns A promise that resolves to true if the bucket was created successfully, false otherwise.
+     */
     createBucket(): Promise<boolean>;
+    /**
+     * Checks if a bucket exists.
+     * This method sends a request to check if the specified bucket exists in the S3-compatible service.
+     * @returns A promise that resolves to true if the bucket exists, false otherwise.
+     */
     bucketExists(): Promise<boolean>;
+    /**
+     * Lists objects in the bucket with optional filtering and no pagination.
+     * This method retrieves all objects matching the criteria (not paginated like listObjectsV2).
+     * @param {string} [delimiter='/'] - The delimiter to use for grouping objects.
+     * @param {string} [prefix=''] - The prefix to filter objects by.
+     * @param {number} [maxKeys] - The maximum number of keys to return. If not provided, all keys will be returned.
+     * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+     * @returns {Promise<object[] | null>} A promise that resolves to an array of objects or null if the bucket is empty.
+     * @example
+     * // List all objects
+     * const objects = await s3.listObjects();
+     *
+     * // List objects with prefix
+     * const photos = await s3.listObjects('/', 'photos/', 100);
+     */
     listObjects(delimiter?: string, prefix?: string, maxKeys?: number, opts?: Record<string, unknown>): Promise<object[] | null>;
+    /**
+     * Lists multipart uploads in the bucket.
+     * This method sends a request to list multipart uploads in the specified bucket.
+     * @param {string} [delimiter='/'] - The delimiter to use for grouping uploads.
+     * @param {string} [prefix=''] - The prefix to filter uploads by.
+     * @param {IT.HttpMethod} [method='GET'] - The HTTP method to use for the request (GET or HEAD).
+     * @param {Record<string, string | number | boolean | undefined>} [opts={}] - Additional options for the request.
+     * @returns A promise that resolves to a list of multipart uploads or an error.
+     */
     listMultipartUploads(delimiter?: string, prefix?: string, method?: HttpMethod, opts?: Record<string, string | number | boolean | undefined>): Promise<ListMultipartUploadSuccess | MultipartUploadError>;
+    /**
+     * Get an object from the S3-compatible service.
+     * This method sends a request to retrieve the specified object from the S3-compatible service.
+     * @param {string} key - The key of the object to retrieve.
+     * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+     * @returns A promise that resolves to the object data (string) or null if not found.
+     */
     getObject(key: string, opts?: Record<string, unknown>): Promise<string | null>;
+    /**
+     * Get an object response from the S3-compatible service.
+     * This method sends a request to retrieve the specified object and returns the full response.
+     * @param {string} key - The key of the object to retrieve.
+     * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+     * @returns A promise that resolves to the Response object or null if not found.
+     */
     getObjectResponse(key: string, opts?: Record<string, unknown>): Promise<Response | null>;
+    /**
+     * Get an object as an ArrayBuffer from the S3-compatible service.
+     * This method sends a request to retrieve the specified object and returns it as an ArrayBuffer.
+     * @param {string} key - The key of the object to retrieve.
+     * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+     * @returns A promise that resolves to the object data as an ArrayBuffer or null if not found.
+     */
     getObjectArrayBuffer(key: string, opts?: Record<string, unknown>): Promise<ArrayBuffer | null>;
+    /**
+     * Get an object as JSON from the S3-compatible service.
+     * This method sends a request to retrieve the specified object and returns it as JSON.
+     * @param {string} key - The key of the object to retrieve.
+     * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+     * @returns A promise that resolves to the object data as JSON or null if not found.
+     */
     getObjectJSON<T = unknown>(key: string, opts?: Record<string, unknown>): Promise<T | null>;
+    /**
+     * Get an object with its ETag from the S3-compatible service.
+     * This method sends a request to retrieve the specified object and its ETag.
+     * @param {string} key - The key of the object to retrieve.
+     * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+     * @returns A promise that resolves to an object containing the ETag and the object data as an ArrayBuffer or null if not found.
+     */
     getObjectWithETag(key: string, opts?: Record<string, unknown>): Promise<{
         etag: string | null;
         data: ArrayBuffer | null;
     }>;
+    /**
+     * Get an object as a raw response from the S3-compatible service.
+     * This method sends a request to retrieve the specified object and returns the raw response.
+     * @param {string} key - The key of the object to retrieve.
+     * @param {boolean} [wholeFile=true] - Whether to retrieve the whole file or a range.
+     * @param {number} [rangeFrom=0] - The starting byte for the range (if not whole file).
+     * @param {number} [rangeTo=this.requestSizeInBytes] - The ending byte for the range (if not whole file).
+     * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+     * @returns A promise that resolves to the Response object.
+     */
     getObjectRaw(key: string, wholeFile?: boolean, rangeFrom?: number, rangeTo?: number, opts?: Record<string, unknown>): Promise<Response>;
+    /**
+     * Get the content length of an object.
+     * This method sends a HEAD request to retrieve the content length of the specified object.
+     * @param {string} key - The key of the object to retrieve the content length for.
+     * @returns A promise that resolves to the content length of the object in bytes, or 0 if not found.
+     * @throws {Error} If the content length header is not found in the response.
+     */
     getContentLength(key: string): Promise<number>;
+    /**
+     * Checks if an object exists in the S3-compatible service.
+     * This method sends a HEAD request to check if the specified object exists.
+     * @param {string} key - The key of the object to check.
+     * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+     * @returns A promise that resolves to true if the object exists, false if not found, or null if ETag mismatch.
+     */
     objectExists(key: string, opts?: Record<string, unknown>): Promise<ExistResponseCode>;
+    /**
+     * Retrieves the ETag of an object without downloading its content.
+     * @param {string} key - The key of the object to retrieve the ETag for.
+     * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+     * @returns {Promise<string | null>} A promise that resolves to the ETag value or null if the object is not found.
+     * @throws {Error} If the ETag header is not found in the response.
+     * @example
+     * const etag = await s3.getEtag('path/to/file.txt');
+     * if (etag) {
+     *   console.log(`File ETag: ${etag}`);
+     * }
+     */
     getEtag(key: string, opts?: Record<string, unknown>): Promise<string | null>;
-    putObject(key: string, data: string | Buffer): Promise<Response>;
+    /**
+     * Uploads an object to the S3-compatible service.
+     * @param {string} key - The key/path where the object will be stored.
+     * @param {string | Buffer} data - The data to upload (string or Buffer).
+     * @param {string} [fileType='application/octet-stream'] - The MIME type of the file.
+     * @returns {Promise<Response>} A promise that resolves to the Response object from the upload request.
+     * @throws {TypeError} If data is not a string or Buffer.
+     * @example
+     * // Upload text file
+     * await s3.putObject('hello.txt', 'Hello, World!', 'text/plain');
+     *
+     * // Upload binary data
+     * const buffer = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
+     * await s3.putObject('image.png', buffer, 'image/png');
+     */
+    putObject(key: string, data: string | Buffer, fileType?: string): Promise<Response>;
+    /**
+     * Initiates a multipart upload and returns the upload ID.
+     * @param {string} key - The key/path where the object will be stored.
+     * @param {string} [fileType='application/octet-stream'] - The MIME type of the file.
+     * @returns {Promise<string>} A promise that resolves to the upload ID for the multipart upload.
+     * @throws {TypeError} If key is invalid or fileType is not a string.
+     * @throws {Error} If the multipart upload fails to initialize.
+     * @example
+     * const uploadId = await s3.getMultipartUploadId('large-file.zip', 'application/zip');
+     * console.log(`Started multipart upload: ${uploadId}`);
+     */
     getMultipartUploadId(key: string, fileType?: string): Promise<string>;
+    /**
+     * Uploads a part in a multipart upload.
+     * @param {string} key - The key of the object being uploaded.
+     * @param {string} uploadId - The upload ID from getMultipartUploadId.
+     * @param {Buffer | string} data - The data for this part.
+     * @param {number} partNumber - The part number (must be between 1 and 10,000).
+     * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+     * @returns {Promise<IT.UploadPart>} A promise that resolves to an object containing the partNumber and etag.
+     * @throws {TypeError} If any parameter is invalid.
+     * @example
+     * const part = await s3.uploadPart(
+     *   'large-file.zip',
+     *   uploadId,
+     *   partData,
+     *   1
+     * );
+     * console.log(`Part ${part.partNumber} uploaded with ETag: ${part.etag}`);
+     */
     uploadPart(key: string, uploadId: string, data: Buffer | string, partNumber: number, opts?: Record<string, unknown>): Promise<UploadPart>;
+    /**
+     * Completes a multipart upload by combining all uploaded parts.
+     * @param {string} key - The key of the object being uploaded.
+     * @param {string} uploadId - The upload ID from getMultipartUploadId.
+     * @param {Array<IT.UploadPart>} parts - Array of uploaded parts with partNumber and etag.
+     * @returns {Promise<IT.CompleteMultipartUploadResult>} A promise that resolves to the completion result containing the final ETag.
+     * @throws {Error} If the multipart upload fails to complete.
+     * @example
+     * const result = await s3.completeMultipartUpload(
+     *   'large-file.zip',
+     *   uploadId,
+     *   [
+     *     { partNumber: 1, etag: 'abc123' },
+     *     { partNumber: 2, etag: 'def456' }
+     *   ]
+     * );
+     * console.log(`Upload completed with ETag: ${result.etag}`);
+     */
     completeMultipartUpload(key: string, uploadId: string, parts: Array<UploadPart>): Promise<CompleteMultipartUploadResult>;
+    /**
+     * Aborts a multipart upload and removes all uploaded parts.
+     * @param {string} key - The key of the object being uploaded.
+     * @param {string} uploadId - The upload ID to abort.
+     * @returns {Promise<object>} A promise that resolves to an object containing the abort status and details.
+     * @throws {TypeError} If key or uploadId is invalid.
+     * @throws {Error} If the abort operation fails.
+     * @example
+     * try {
+     *   const result = await s3.abortMultipartUpload('large-file.zip', uploadId);
+     *   console.log('Upload aborted:', result.status);
+     * } catch (error) {
+     *   console.error('Failed to abort upload:', error);
+     * }
+     */
     abortMultipartUpload(key: string, uploadId: string): Promise<object>;
     private _buildCompleteMultipartUploadXml;
+    /**
+     * Deletes an object from the bucket.
+     * This method sends a request to delete the specified object from the bucket.
+     * @param {string} key - The key of the object to delete.
+     * @returns A promise that resolves to true if the object was deleted successfully, false otherwise.
+     */
     deleteObject(key: string): Promise<boolean>;
+    private _deleteObjectsProcess;
+    /**
+     * Deletes multiple objects from the bucket.
+     * @param {string[]} keys - An array of object keys to delete.
+     * @returns A promise that resolves to an array of booleans indicating success for each key in order.
+     */
+    deleteObjects(keys: string[]): Promise<boolean[]>;
     private _sendRequest;
     private _handleErrorResponse;
     private _buildCanonicalQueryString;
@@ -182,8 +410,8 @@ declare const sanitizeETag: (etag: string) => string;
  * @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>>>}
+ * @returns {Promise<Array<PromiseSettledResult<T>>>}
  */
-declare const runInBatches: (tasks: Iterable<() => Promise<unknown>>, batchSize?: number, minIntervalMs?: number) => Promise<Array<PromiseSettledResult<unknown>>>;
+declare const runInBatches: <T = unknown>(tasks: Iterable<() => Promise<T>>, batchSize?: number, minIntervalMs?: number) => Promise<Array<PromiseSettledResult<T>>>;
 
 export { type CompleteMultipartUploadResult, type ErrorWithCode, type ExistResponseCode, type ListBucketResponse, type ListMultipartUploadResponse, type Logger, type S3Config, type UploadPart, s3mini as default, runInBatches, s3mini, sanitizeETag };