s3mini 0.2.0 → 0.4.0

package/README.md

@@ -60,6 +60,7 @@ The library supports a subset of S3 operations, focusing on essential features,
 - ✅ GetObject (getObject, getObjectResponse, getObjectWithETag, getObjectRaw, getObjectArrayBuffer, getObjectJSON)
 - ✅ PutObject (putObject)
 - ✅ DeleteObject (deleteObject)
+- ✅ DeleteObjects (deleteObjects)
 - ✅ HeadObject (objectExists, getEtag, getContentLength)
 - ✅ listMultipartUploads
 - ✅ CreateMultipartUpload (getMultipartUploadId)
@@ -68,6 +69,8 @@ The library supports a subset of S3 operations, focusing on essential features,
 - ✅ uploadPart
 - ❌ CopyObject: Not implemented (tbd)
 
+Put/Get objects with SSE-C (server-side encryption with customer-provided keys) is supported, but only tested on Cloudflare R2!
+
 ## Installation
 
 ```bash
@@ -99,10 +102,14 @@ mv example.env .env
 
 ## Usage
 
+> [!WARNING]
+> `s3mini` is a deprecated alias retained solely for backward compatibility.
+> It is scheduled for removal in a future release. Please migrate to the new `S3mini` class.
+
 ```typescript
-import { s3mini, sanitizeETag } from 's3mini';
+import { S3mini, sanitizeETag } from 's3mini';
 
-const s3client = new s3mini({
+const s3client = new S3mini({
   accessKeyId: config.accessKeyId,
   secretAccessKey: config.secretAccessKey,
   endpoint: config.endpoint,
@@ -149,7 +156,7 @@ 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 });
+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
@@ -175,6 +182,10 @@ if (list) {
 
 // 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';

package/dist/s3mini.d.ts

@@ -7,6 +7,11 @@ interface S3Config {
     requestAbortTimeout?: number;
     logger?: Logger;
 }
+interface SSECHeaders {
+    'x-amz-server-side-encryption-customer-algorithm': string;
+    'x-amz-server-side-encryption-customer-key': string;
+    'x-amz-server-side-encryption-customer-key-md5': string;
+}
 interface Logger {
     info: (message: string, ...args: unknown[]) => void;
     warn: (message: string, ...args: unknown[]) => void;
@@ -16,6 +21,13 @@ interface UploadPart {
     partNumber: number;
     etag: string;
 }
+interface ListObject {
+    Key: string;
+    Size: number;
+    LastModified: Date;
+    ETag: string;
+    StorageClass: string;
+}
 interface CompleteMultipartUploadResult {
     location: string;
     bucket: string;
@@ -92,7 +104,7 @@ type ExistResponseCode = false | true | null;
  * // Delete a file
  * await s3.deleteObject('example.txt');
  */
-declare class s3mini {
+declare class S3mini {
     /**
      * Creates an instance of the S3 class.
      *
@@ -136,37 +148,281 @@ declare class s3mini {
     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>;
-    listObjects(delimiter?: string, prefix?: string, maxKeys?: number, opts?: Record<string, unknown>): Promise<object[] | null>;
+    /**
+     * 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<IT.ListObject[] | 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<ListObject[] | 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>;
-    getObject(key: string, opts?: Record<string, unknown>): Promise<string | null>;
-    getObjectResponse(key: string, opts?: Record<string, unknown>): Promise<Response | null>;
-    getObjectArrayBuffer(key: string, opts?: Record<string, unknown>): Promise<ArrayBuffer | null>;
-    getObjectJSON<T = unknown>(key: string, opts?: Record<string, unknown>): Promise<T | null>;
-    getObjectWithETag(key: string, opts?: Record<string, unknown>): Promise<{
+    /**
+     * 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.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @returns A promise that resolves to the object data (string) or null if not found.
+     */
+    getObject(key: string, opts?: Record<string, unknown>, ssecHeaders?: SSECHeaders): 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.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @returns A promise that resolves to the Response object or null if not found.
+     */
+    getObjectResponse(key: string, opts?: Record<string, unknown>, ssecHeaders?: SSECHeaders): 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.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @returns A promise that resolves to the object data as an ArrayBuffer or null if not found.
+     */
+    getObjectArrayBuffer(key: string, opts?: Record<string, unknown>, ssecHeaders?: SSECHeaders): 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.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @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>, ssecHeaders?: SSECHeaders): 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.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @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>, ssecHeaders?: SSECHeaders): 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>;
+    /**
+     * 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.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @returns A promise that resolves to the Response object.
+     */
+    getObjectRaw(key: string, wholeFile?: boolean, rangeFrom?: number, rangeTo?: number, opts?: Record<string, unknown>, ssecHeaders?: SSECHeaders): 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, ssecHeaders?: SSECHeaders): 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>;
-    getEtag(key: string, opts?: Record<string, unknown>): Promise<string | null>;
-    putObject(key: string, data: string | Buffer, fileType?: string): 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>;
+    /**
+     * 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.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @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>, ssecHeaders?: SSECHeaders): Promise<string | null>;
+    /**
+     * 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.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @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, ssecHeaders?: SSECHeaders): 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.
+     * @param {IT.SSECHeaders?} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @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, ssecHeaders?: SSECHeaders): 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.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @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>, ssecHeaders?: SSECHeaders): 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>;
-    abortMultipartUpload(key: string, uploadId: string): Promise<object>;
+    /**
+     * 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.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @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, ssecHeaders?: SSECHeaders): 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;
     private _getSignatureKey;
 }
+/**
+ * @deprecated Use `S3mini` instead.
+ */
+declare const s3mini: typeof S3mini;
 
 /**
  * Sanitize ETag value by removing quotes and XML entities
@@ -185,4 +441,5 @@ declare const sanitizeETag: (etag: string) => string;
  */
 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 };
+export { S3mini, S3mini as default, runInBatches, s3mini, sanitizeETag };
+export type { CompleteMultipartUploadResult, ErrorWithCode, ExistResponseCode, ListBucketResponse, ListMultipartUploadResponse, Logger, S3Config, UploadPart };