s3mini 0.4.0 → 0.6.0

package/README.md

@@ -23,6 +23,12 @@ Dev:
 ![GitHub commit activity (branch)](https://img.shields.io/github/commit-activity/m/good-lly/s3mini/dev?color=greeen)
 ![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/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)
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=good-lly_s3mini&metric=bugs)](https://sonarcloud.io/summary/new_code?id=good-lly_s3mini)
+[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=good-lly_s3mini&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=good-lly_s3mini)
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=good-lly_s3mini&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=good-lly_s3mini)
+[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=good-lly_s3mini&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=good-lly_s3mini)
+[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=good-lly_s3mini&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=good-lly_s3mini)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=good-lly_s3mini&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=good-lly_s3mini)
 [![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)
 
 ![GitHub Repo stars](https://img.shields.io/github/stars/good-lly/s3mini?style=social)
@@ -67,7 +73,7 @@ The library supports a subset of S3 operations, focusing on essential features,
 - ✅ completeMultipartUpload
 - ✅ abortMultipartUpload
 - ✅ uploadPart
-- ❌ CopyObject: Not implemented (tbd)
+- ✅ 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!
 
@@ -98,13 +104,12 @@ mv example.env .env
 >
 > 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:** To enable built-in Node.js Crypto API, add the `nodejs_compat` compatibility flag to your Wrangler configuration file. This also enables `nodejs_compat_v2` as long as your compatibility date is `2024-09-23` or later. [Learn more about the Node.js compatibility flag and v2](https://developers.cloudflare.com/workers/configuration/compatibility-dates/#nodejs-compatibility-flag).
+> **Cloudflare Workers:** Now works without `nodejs_compat` compatibility flag, using native WebCrypto!
 
 ## 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.
+> `s3mini` was a deprecated alias removed in a recent `0.5.0` release. Please migrate to the new `S3mini` class.
 
 ```typescript
 import { S3mini, sanitizeETag } from 's3mini';
@@ -226,6 +231,9 @@ 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.

package/dist/s3mini.d.ts

@@ -12,6 +12,9 @@ interface SSECHeaders {
     'x-amz-server-side-encryption-customer-key': string;
     'x-amz-server-side-encryption-customer-key-md5': string;
 }
+interface AWSHeaders {
+    [k: `x-amz-${string}`]: string;
+}
 interface Logger {
     info: (message: string, ...args: unknown[]) => void;
     warn: (message: string, ...args: unknown[]) => void;
@@ -57,7 +60,7 @@ interface ListMultipartUploadSuccess {
         key: string;
         uploadId: string;
         size?: number;
-        mtime?: Date | undefined;
+        mtime?: Date;
         etag?: string;
         eTag?: string;
         parts: UploadPart[];
@@ -80,6 +83,55 @@ interface ErrorWithCode {
 type ListMultipartUploadResponse = ListMultipartUploadSuccess | MultipartUploadError;
 type HttpMethod = 'POST' | 'GET' | 'HEAD' | 'PUT' | 'DELETE';
 type ExistResponseCode = false | true | null;
+interface CopyObjectOptions {
+    /**
+     * Specifies whether the metadata is copied from the source object or replaced with metadata provided in the request.
+     * Valid values: 'COPY' | 'REPLACE'
+     * Default: 'COPY'
+     */
+    metadataDirective?: 'COPY' | 'REPLACE';
+    /**
+     * Metadata to be set on the destination object when metadataDirective is 'REPLACE'.
+     * Keys can be provided with or without 'x-amz-meta-' prefix.
+     */
+    metadata?: Record<string, string>;
+    contentType?: string;
+    /**
+     * Storage class for the destination object.
+     * Valid values: 'STANDARD' | 'REDUCED_REDUNDANCY' | 'STANDARD_IA' | 'ONEZONE_IA' | 'INTELLIGENT_TIERING' | 'GLACIER' | 'DEEP_ARCHIVE' | 'GLACIER_IR'
+     */
+    storageClass?: string;
+    /**
+     * Specifies whether the object tag-set is copied from the source object or replaced with tag-set provided in the request.
+     * Valid values: 'COPY' | 'REPLACE'
+     */
+    taggingDirective?: 'COPY' | 'REPLACE';
+    /**
+     * If the bucket is configured as a website, redirects requests for this object to another object or URL.
+     */
+    websiteRedirectLocation?: string;
+    /**
+     * Server-Side Encryption with Customer-Provided Keys headers for the source object.
+     * Should include:
+     * - x-amz-copy-source-server-side-encryption-customer-algorithm
+     * - x-amz-copy-source-server-side-encryption-customer-key
+     * - x-amz-copy-source-server-side-encryption-customer-key-MD5
+     */
+    sourceSSECHeaders?: Record<string, string | number>;
+    destinationSSECHeaders?: SSECHeaders;
+    additionalHeaders?: Record<string, string | number>;
+}
+interface CopyObjectResult {
+    etag: string;
+    lastModified?: Date;
+}
+/**
+ * Where Buffer is available, e.g. when @types/node is loaded, we want to use it.
+ * But it should be excluded in other environments (e.g. Cloudflare).
+ */
+type MaybeBuffer = typeof globalThis extends {
+    Buffer?: infer B;
+} ? B extends new (...a: unknown[]) => unknown ? InstanceType<B> : ArrayBuffer | Uint8Array : ArrayBuffer | Uint8Array;
 
 /**
  * S3 class for interacting with S3-compatible object storage services.
@@ -91,8 +143,8 @@ type ExistResponseCode = false | true | null;
  * 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
+ *   endpoint: 'https://your-s3-endpoint.com/bucket-name',
+ *   region: 'auto' // by default is auto
  * });
  *
  * // Upload a file
@@ -119,13 +171,14 @@ declare class S3mini {
      * @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?;
+    readonly accessKeyId: string;
+    readonly secretAccessKey: string;
+    readonly endpoint: URL;
+    readonly region: string;
+    readonly bucketName: string;
+    readonly requestSizeInBytes: number;
+    readonly requestAbortTimeout?: number;
+    readonly logger?: Logger;
     private signingKeyDate?;
     private signingKey?;
     constructor({ accessKeyId, secretAccessKey, endpoint, region, requestSizeInBytes, requestAbortTimeout, logger, }: S3Config);
@@ -139,43 +192,10 @@ declare class S3mini {
     private _checkPrefix;
     private _checkOpts;
     private _filterIfHeaders;
+    private _validateData;
     private _validateUploadPartParams;
     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
@@ -191,6 +211,7 @@ declare class S3mini {
      * @returns A promise that resolves to true if the bucket was created successfully, false otherwise.
      */
     createBucket(): Promise<boolean>;
+    private _extractBucketName;
     /**
      * Checks if a bucket exists.
      * This method sends a request to check if the specified bucket exists in the S3-compatible service.
@@ -213,6 +234,12 @@ declare class S3mini {
      * const photos = await s3.listObjects('/', 'photos/', 100);
      */
     listObjects(delimiter?: string, prefix?: string, maxKeys?: number, opts?: Record<string, unknown>): Promise<ListObject[] | null>;
+    private _fetchObjectBatch;
+    private _buildListObjectsQuery;
+    private _handleListObjectsError;
+    private _parseListObjectsResponse;
+    private _extractObjectsFromResponse;
+    private _extractContinuationToken;
     /**
      * Lists multipart uploads in the bucket.
      * This method sends a request to list multipart uploads in the specified bucket.
@@ -319,6 +346,7 @@ declare class S3mini {
      * @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.
+     * @param {IT.AWSHeaders} [additionalHeaders] - Additional x-amz-* headers specific to this request, 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
@@ -329,7 +357,7 @@ declare class S3mini {
      * 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>;
+    putObject(key: string, data: string | MaybeBuffer, fileType?: string, ssecHeaders?: SSECHeaders, additionalHeaders?: AWSHeaders): Promise<Response>;
     /**
      * Initiates a multipart upload and returns the upload ID.
      * @param {string} key - The key/path where the object will be stored.
@@ -362,7 +390,7 @@ declare class S3mini {
      * );
      * 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>;
+    uploadPart(key: string, uploadId: string, data: MaybeBuffer | 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.
@@ -400,6 +428,109 @@ declare class S3mini {
      */
     abortMultipartUpload(key: string, uploadId: string, ssecHeaders?: SSECHeaders): Promise<object>;
     private _buildCompleteMultipartUploadXml;
+    /**
+     * Executes the copy operation for local copying (same bucket/endpoint).
+     * @private
+     */
+    private _executeCopyOperation;
+    /**
+     * Copies an object within the same bucket.
+     *
+     * @param {string} sourceKey - The key of the source object to copy
+     * @param {string} destinationKey - The key where the object will be copied to
+     * @param {IT.CopyObjectOptions} [options={}] - Copy operation options
+     * @param {string} [options.metadataDirective='COPY'] - How to handle metadata ('COPY' | 'REPLACE')
+     * @param {Record<string,string>} [options.metadata={}] - New metadata (only used if metadataDirective='REPLACE')
+     * @param {string} [options.contentType] - New content type for the destination object
+     * @param {string} [options.storageClass] - Storage class for the destination object
+     * @param {string} [options.taggingDirective] - How to handle object tags ('COPY' | 'REPLACE')
+     * @param {string} [options.websiteRedirectLocation] - Website redirect location for the destination
+     * @param {IT.SSECHeaders} [options.sourceSSECHeaders={}] - Encryption headers for reading source (if encrypted)
+     * @param {IT.SSECHeaders} [options.destinationSSECHeaders={}] - Encryption headers for destination
+     * @param {IT.AWSHeaders} [options.additionalHeaders={}] - Extra x-amz-* headers
+     *
+     * @returns {Promise<IT.CopyObjectResult>} Copy result with etag and lastModified date
+     * @throws {TypeError} If sourceKey or destinationKey is invalid
+     * @throws {Error} If copy operation fails or S3 returns an error
+     *
+     * @example
+     * // Simple copy
+     * const result = await s3.copyObject('report-2024.pdf', 'archive/report-2024.pdf');
+     * console.log(`Copied with ETag: ${result.etag}`);
+     *
+     * @example
+     * // Copy with new metadata and content type
+     * const result = await s3.copyObject('data.csv', 'processed/data.csv', {
+     *   metadataDirective: 'REPLACE',
+     *   metadata: {
+     *     'processed-date': new Date().toISOString(),
+     *     'original-name': 'data.csv'
+     *   },
+     *   contentType: 'text/csv; charset=utf-8'
+     * });
+     *
+     * @example
+     * // Copy encrypted object (Cloudflare R2 SSE-C)
+     * const ssecKey = 'n1TKiTaVHlYLMX9n0zHXyooMr026vOiTEFfT+719Hho=';
+     * await s3.copyObject('sensitive.json', 'backup/sensitive.json', {
+     *   sourceSSECHeaders: {
+     *     'x-amz-copy-source-server-side-encryption-customer-algorithm': 'AES256',
+     *     'x-amz-copy-source-server-side-encryption-customer-key': ssecKey,
+     *     'x-amz-copy-source-server-side-encryption-customer-key-md5': 'gepZmzgR7Be/1+K1Aw+6ow=='
+     *   },
+     *   destinationSSECHeaders: {
+     *     'x-amz-server-side-encryption-customer-algorithm': 'AES256',
+     *     'x-amz-server-side-encryption-customer-key': ssecKey,
+     *     'x-amz-server-side-encryption-customer-key-md5': 'gepZmzgR7Be/1+K1Aw+6ow=='
+     *   }
+     * });
+     */
+    copyObject(sourceKey: string, destinationKey: string, options?: CopyObjectOptions): Promise<CopyObjectResult>;
+    private _buildSSECHeaders;
+    /**
+     * Moves an object within the same bucket (copy + delete atomic-like operation).
+     *
+     * WARNING: Not truly atomic - if delete fails after successful copy, the object
+     * will exist in both locations. Consider your use case carefully.
+     *
+     * @param {string} sourceKey - The key of the source object to move
+     * @param {string} destinationKey - The key where the object will be moved to
+     * @param {IT.CopyObjectOptions} [options={}] - Options passed to the copy operation
+     *
+     * @returns {Promise<IT.CopyObjectResult>} Result from the copy operation
+     * @throws {TypeError} If sourceKey or destinationKey is invalid
+     * @throws {Error} If copy succeeds but delete fails (includes copy result in error)
+     *
+     * @example
+     * // Simple move
+     * await s3.moveObject('temp/upload.tmp', 'files/document.pdf');
+     *
+     * @example
+     * // Move with metadata update
+     * await s3.moveObject('unprocessed/image.jpg', 'processed/image.jpg', {
+     *   metadataDirective: 'REPLACE',
+     *   metadata: {
+     *     'status': 'processed',
+     *     'processed-at': Date.now().toString()
+     *   },
+     *   contentType: 'image/jpeg'
+     * });
+     *
+     * @example
+     * // Safe move with error handling
+     * try {
+     *   const result = await s3.moveObject('inbox/file.dat', 'archive/file.dat');
+     *   console.log(`Moved successfully: ${result.etag}`);
+     * } catch (error) {
+     *   // Check if copy succeeded but delete failed
+     *   if (error.message.includes('delete source object after successful copy')) {
+     *     console.warn('File copied but not deleted from source - manual cleanup needed');
+     *   }
+     * }
+     */
+    moveObject(sourceKey: string, destinationKey: string, options?: CopyObjectOptions): Promise<CopyObjectResult>;
+    private _buildMetadataHeaders;
+    private _parseCopyObjectResponse;
     /**
      * Deletes an object from the bucket.
      * This method sends a request to delete the specified object from the bucket.
@@ -415,14 +546,11 @@ declare class S3mini {
      */
     deleteObjects(keys: string[]): Promise<boolean[]>;
     private _sendRequest;
+    private _parseErrorXml;
     private _handleErrorResponse;
     private _buildCanonicalQueryString;
     private _getSignatureKey;
 }
-/**
- * @deprecated Use `S3mini` instead.
- */
-declare const s3mini: typeof S3mini;
 
 /**
  * Sanitize ETag value by removing quotes and XML entities
@@ -441,5 +569,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 { S3mini, S3mini as default, runInBatches, s3mini, sanitizeETag };
+export { S3mini, S3mini as default, runInBatches, sanitizeETag };
 export type { CompleteMultipartUploadResult, ErrorWithCode, ExistResponseCode, ListBucketResponse, ListMultipartUploadResponse, Logger, S3Config, UploadPart };