s3mini 0.4.0 → 0.5.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)

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 };