lean-s3 0.6.2 → 0.7.0

package/README.md

@@ -141,6 +141,9 @@ See [DESIGN_DECISIONS.md](./DESIGN_DECISIONS.md) to read about why this library
 - ✅ [`UploadPart`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html) via `.uploadPart`
 - ✅ [`CompleteMultipartUpload`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html) via `.completeMultipartUpload`
 - ✅ [`AbortMultipartUpload`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html) via `.abortMultipartUpload`
+- ✅ [`PutBucketCors`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketCors.html) via `.putBucketCors`
+- ✅ [`GetBucketCors`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketCors.html) via `.getBucketCors`
+- ✅ [`DeleteBucketCors`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucketCors.html) via `.deleteBucketCors`
 
 ## Example Configurations
 ### Hetzner Object Storage

package/dist/index.d.ts

@@ -39,8 +39,11 @@ interface S3ClientOptions {
     secretAccessKey: string;
     sessionToken?: string;
 }
-type OverridableS3ClientOptions = Pick<S3ClientOptions, "region" | "bucket" | "endpoint">;
-type CreateFileInstanceOptions = {};
+type OverridableS3ClientOptions = Partial<Pick<S3ClientOptions, "region" | "bucket" | "endpoint">>;
+type CreateFileInstanceOptions = {
+    /** Content-Type of the file. */
+    type?: string;
+};
 type DeleteObjectsOptions = {
     bucket?: string;
     signal?: AbortSignal;
@@ -55,13 +58,15 @@ type DeleteObjectsError = {
     versionId: string;
 };
 interface S3FilePresignOptions {
-    contentHash: Buffer;
+    contentHash?: Buffer;
     /** Seconds. */
-    expiresIn: number;
-    method: PresignableHttpMethod;
-    contentLength: number;
-    storageClass: StorageClass;
-    acl: Acl;
+    expiresIn?: number;
+    method?: PresignableHttpMethod;
+    contentLength?: number;
+    storageClass?: StorageClass;
+    acl?: Acl;
+    /** `Content-Type` of the file. */
+    type?: string;
 }
 type ListObjectsOptions = {
     bucket?: string;
@@ -208,6 +213,35 @@ type BucketDeletionOptions = {
 type BucketExistsOptions = {
     signal?: AbortSignal;
 };
+type BucketCorsRules = readonly BucketCorsRule[];
+type BucketCorsRule = {
+    allowedMethods: readonly HttpMethod[];
+    /** One or more origins you want customers to be able to access the bucket from. */
+    allowedOrigins: readonly string[];
+    /** Headers that are specified in the `Access-Control-Request-Headers` header. These headers are allowed in a preflight `OPTIONS` request. */
+    allowedHeaders?: readonly string[];
+    /** One or more headers in the response that you want customers to be able to access from their applications. */
+    exposeHeaders?: readonly string[];
+    /** Unique identifier for the rule. The value cannot be longer than 255 characters. */
+    id?: string;
+    /** The time in seconds that your browser is to cache the preflight response for the specified resource. */
+    maxAgeSeconds?: number;
+};
+type PutBucketCorsOptions = {
+    bucket?: string;
+    signal?: AbortSignal;
+};
+type DeleteBucketCorsOptions = {
+    bucket?: string;
+    signal?: AbortSignal;
+};
+type GetBucketCorsOptions = {
+    bucket?: string;
+    signal?: AbortSignal;
+};
+type GetBucketCorsResult = {
+    rules: BucketCorsRule[];
+};
 /**
  * A configured S3 bucket instance for managing files.
  *
@@ -255,7 +289,6 @@ declare class S3Client {
      *
      * lean-s3 does not enforce these restrictions.
      *
-     * @param {Partial<CreateFileInstanceOptions>} [_options] TODO
      * @example
      * ```js
      * const file = client.file("image.jpg");
@@ -263,11 +296,10 @@ declare class S3Client {
      *
      * const configFile = client.file("config.json", {
      *   type: "application/json",
-     *   acl: "private"
      * });
      * ```
      */
-    file(path: string, _options?: Partial<CreateFileInstanceOptions>): S3File;
+    file(path: string, options?: CreateFileInstanceOptions): S3File;
     /**
      * Generate a presigned URL for temporary access to a file.
      * Useful for generating upload/download URLs without exposing credentials.
@@ -281,7 +313,7 @@ declare class S3Client {
      * ```
      */
     presign(path: string, { method, expiresIn, // TODO: Maybe rename this to expiresInSeconds
-    storageClass, contentLength, acl, region: regionOverride, bucket: bucketOverride, endpoint: endpointOverride, }?: Partial<S3FilePresignOptions & OverridableS3ClientOptions>): string;
+    storageClass, contentLength, type, acl, region: regionOverride, bucket: bucketOverride, endpoint: endpointOverride, }?: S3FilePresignOptions & OverridableS3ClientOptions): string;
     createMultipartUpload(key: string, options?: CreateMultipartUploadOptions): Promise<CreateMultipartUploadResult>;
     /**
      * @remarks Uses [`ListMultipartUploads`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html).
@@ -345,6 +377,18 @@ declare class S3Client {
      * @remarks Uses [`HeadBucket`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadBucket.html).
      */
     bucketExists(name: string, options?: BucketExistsOptions): Promise<boolean>;
+    /**
+     * @remarks Uses [`PutBucketCors`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketCors.html).
+     */
+    putBucketCors(rules: BucketCorsRules, options?: PutBucketCorsOptions): Promise<void>;
+    /**
+     * @remarks Uses [`GetBucketCors`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketCors.html).
+     */
+    getBucketCors(options?: GetBucketCorsOptions): Promise<GetBucketCorsResult>;
+    /**
+     * @remarks Uses [`DeleteBucketCors`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucketCors.html).
+     */
+    deleteBucketCors(options?: DeleteBucketCorsOptions): Promise<void>;
     /**
      * Uses [`ListObjectsV2`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) to iterate over all keys. Pagination and continuation is handled internally.
      */
@@ -385,6 +429,10 @@ declare class S3Stat {
     static tryParseFromHeaders(headers: Record<string, string | string[] | undefined>): S3Stat | undefined;
 }
 
+type S3FileWriteOptions = {
+    /** Content-Type of the file. */
+    type?: string;
+};
 declare class S3File {
     #private;
     /** @internal */
@@ -397,20 +445,20 @@ declare class S3File {
      * @throws {S3Error} If the file does not exist or the server has some other issues.
      * @throws {Error} If the server returns an invalid response.
      */
-    stat(options?: Partial<S3StatOptions>): Promise<S3Stat>;
+    stat(options?: S3StatOptions): Promise<S3Stat>;
     /**
      * Check if a file exists in the bucket. Uses `HEAD` request to check existence.
      *
      * @remarks Uses [`HeadObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html).
      */
-    exists(options?: Partial<S3FileExistsOptions>): Promise<boolean>;
+    exists(options?: S3FileExistsOptions): Promise<boolean>;
     /**
      * Delete a file from the bucket.
      *
      * @remarks - Uses [`DeleteObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html).
      *          - `versionId` not supported.
      *
-     * @param {Partial<S3FileDeleteOptions>} [options]
+     * @param {S3FileDeleteOptions} [options]
      *
      * @example
      * ```js
@@ -426,7 +474,7 @@ declare class S3File {
      * }
      * ```
      */
-    delete(options?: Partial<S3FileDeleteOptions>): Promise<void>;
+    delete(options?: S3FileDeleteOptions): Promise<void>;
     toString(): string;
     json(): Promise<unknown>;
     bytes(): Promise<Uint8Array>;
@@ -437,18 +485,19 @@ declare class S3File {
     stream(): ReadableStream<Uint8Array>;
     /**
      * @param {ByteSource} data
+     * @param {S3FileWriteOptions} [options.type] Defaults to the Content-Type that was used to create the {@link S3File} instance.
      * @returns {Promise<void>}
      */
-    write(data: ByteSource): Promise<void>;
+    write(data: ByteSource, options?: S3FileWriteOptions): Promise<void>;
 }
 interface S3FileDeleteOptions extends OverridableS3ClientOptions {
-    signal: AbortSignal;
+    signal?: AbortSignal;
 }
 interface S3StatOptions extends OverridableS3ClientOptions {
-    signal: AbortSignal;
+    signal?: AbortSignal;
 }
 interface S3FileExistsOptions extends OverridableS3ClientOptions {
-    signal: AbortSignal;
+    signal?: AbortSignal;
 }
 
 declare class S3Error extends Error {
@@ -490,4 +539,4 @@ type BucketInfo = {
     type?: string;
 };
 
-export { type AbortMultipartUploadOptions, type Acl, type BucketCreationOptions, type BucketDeletionOptions, type BucketExistsOptions, type BucketInfo, type BucketLocationInfo, type ByteSource, type ChecksumAlgorithm, type ChecksumType, type CompleteMultipartUploadOptions, type CompleteMultipartUploadResult, type CreateFileInstanceOptions, type CreateMultipartUploadOptions, type CreateMultipartUploadResult, type DeleteObjectsError, type DeleteObjectsOptions, type DeleteObjectsResult, type HttpMethod, type ListMultipartUploadsOptions, type ListMultipartUploadsResult, type ListObjectsIteratingOptions, type ListObjectsOptions, type ListObjectsResult, type ListPartsOptions, type ListPartsResult, type MultipartUpload, type MultipartUploadPart, type OverridableS3ClientOptions, type PresignableHttpMethod, S3BucketEntry, S3Client, type S3ClientOptions, S3Error, type S3ErrorOptions, S3File, type S3FileDeleteOptions, type S3FileExistsOptions, type S3FilePresignOptions, S3Stat, type S3StatOptions, type StorageClass, type UndiciBodyInit, type UploadPartOptions, type UploadPartResult };
+export { type AbortMultipartUploadOptions, type Acl, type BucketCorsRule, type BucketCorsRules, type BucketCreationOptions, type BucketDeletionOptions, type BucketExistsOptions, type BucketInfo, type BucketLocationInfo, type ByteSource, type ChecksumAlgorithm, type ChecksumType, type CompleteMultipartUploadOptions, type CompleteMultipartUploadResult, type CreateFileInstanceOptions, type CreateMultipartUploadOptions, type CreateMultipartUploadResult, type DeleteBucketCorsOptions, type DeleteObjectsError, type DeleteObjectsOptions, type DeleteObjectsResult, type GetBucketCorsOptions, type GetBucketCorsResult, type HttpMethod, type ListMultipartUploadsOptions, type ListMultipartUploadsResult, type ListObjectsIteratingOptions, type ListObjectsOptions, type ListObjectsResult, type ListPartsOptions, type ListPartsResult, type MultipartUpload, type MultipartUploadPart, type OverridableS3ClientOptions, type PresignableHttpMethod, type PutBucketCorsOptions, S3BucketEntry, S3Client, type S3ClientOptions, S3Error, type S3ErrorOptions, S3File, type S3FileDeleteOptions, type S3FileExistsOptions, type S3FilePresignOptions, type S3FileWriteOptions, S3Stat, type S3StatOptions, type StorageClass, type UndiciBodyInit, type UploadPartOptions, type UploadPartResult };

package/dist/index.js

@@ -404,6 +404,20 @@ var S3Client = class {
       sessionToken
     };
   }
+  // Maybe future API
+  /*
+  cors = {
+  	get: () => {
+  		// TODO: GetBucketCors
+  	},
+  	set: () => {
+  		// TODO: PutBucketCors
+  	},
+  	delete: () => {
+  		// TODO: DeleteBucketCors
+  	},
+  };
+  */
   /**
    * Creates an S3File instance for the given path.
    *
@@ -427,7 +441,6 @@ var S3Client = class {
    *
    * lean-s3 does not enforce these restrictions.
    *
-   * @param {Partial<CreateFileInstanceOptions>} [_options] TODO
    * @example
    * ```js
    * const file = client.file("image.jpg");
@@ -435,17 +448,16 @@ var S3Client = class {
    *
    * const configFile = client.file("config.json", {
    *   type: "application/json",
-   *   acl: "private"
    * });
    * ```
    */
-  file(path, _options) {
+  file(path, options = {}) {
     return new S3File(
       this,
       ensureValidPath(path),
       void 0,
       void 0,
-      void 0
+      options.type ?? void 0
     );
   }
   /**
@@ -466,6 +478,7 @@ var S3Client = class {
     // TODO: Maybe rename this to expiresInSeconds
     storageClass,
     contentLength,
+    type,
     acl,
     region: regionOverride,
     bucket: bucketOverride,
@@ -487,17 +500,21 @@ var S3Client = class {
       `${options.accessKeyId}/${date.date}/${region}/s3/aws4_request`,
       date,
       expiresIn,
-      typeof contentLength === "number" ? "content-length;host" : "host",
+      typeof contentLength === "number" || typeof type === "string" ? typeof contentLength === "number" && typeof type === "string" ? "content-length;content-type;host" : typeof contentLength === "number" ? "content-length;host" : typeof type === "string" ? "content-type;host" : "" : "host",
       unsignedPayload,
       storageClass,
       options.sessionToken,
       acl
     );
-    const dataDigest = typeof contentLength === "number" ? createCanonicalDataDigest(
+    const dataDigest = typeof contentLength === "number" || typeof type === "string" ? createCanonicalDataDigest(
       method,
       res.pathname,
       query,
-      { "content-length": String(contentLength), host: res.host },
+      typeof contentLength === "number" && typeof type === "string" ? {
+        "content-length": String(contentLength),
+        "content-type": type,
+        host: res.host
+      } : typeof contentLength === "number" ? { "content-length": String(contentLength), host: res.host } : typeof type === "string" ? { "content-type": type, host: res.host } : {},
       unsignedPayload
     ) : createCanonicalDataDigestHostOnly(
       method,
@@ -912,6 +929,90 @@ var S3Client = class {
     }
     throw new Error(`Response code not supported: ${response.statusCode}`);
   }
+  //#region bucket cors
+  /**
+   * @remarks Uses [`PutBucketCors`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketCors.html).
+   */
+  async putBucketCors(rules, options = {}) {
+    const body = xmlBuilder.build({
+      CORSConfiguration: {
+        CORSRule: rules.map((r) => ({
+          AllowedOrigin: r.allowedOrigins,
+          AllowedMethod: r.allowedMethods,
+          ExposeHeader: r.exposeHeaders,
+          ID: r.id ?? void 0,
+          MaxAgeSeconds: r.maxAgeSeconds ?? void 0
+        }))
+      }
+    });
+    const response = await this[signedRequest](
+      "PUT",
+      "",
+      "cors=",
+      // "=" is needed by minio for some reason
+      body,
+      {
+        "content-md5": md5Base64(body)
+      },
+      void 0,
+      void 0,
+      ensureValidBucketName(options.bucket ?? this.#options.bucket),
+      options.signal
+    );
+    if (response.statusCode === 200) {
+      response.body.dump();
+      return;
+    }
+    if (400 <= response.statusCode && response.statusCode < 500) {
+      throw await getResponseError(response, "");
+    }
+    throw new Error(
+      `Response code not implemented yet: ${response.statusCode}`
+    );
+  }
+  /**
+   * @remarks Uses [`GetBucketCors`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketCors.html).
+   */
+  async getBucketCors(options = {}) {
+    const response = await this[signedRequest](
+      "GET",
+      "",
+      "cors=",
+      // "=" is needed by minio for some reason
+      void 0,
+      void 0,
+      void 0,
+      void 0,
+      ensureValidBucketName(options.bucket ?? this.#options.bucket),
+      options.signal
+    );
+    if (response.statusCode !== 200) {
+      response.body.dump();
+      throw fromStatusCode(response.statusCode, "");
+    }
+    throw new Error("Not implemented");
+  }
+  /**
+   * @remarks Uses [`DeleteBucketCors`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucketCors.html).
+   */
+  async deleteBucketCors(options = {}) {
+    const response = await this[signedRequest](
+      "DELETE",
+      "",
+      "cors=",
+      // "=" is needed by minio for some reason
+      void 0,
+      void 0,
+      void 0,
+      void 0,
+      ensureValidBucketName(options.bucket ?? this.#options.bucket),
+      options.signal
+    );
+    if (response.statusCode !== 204) {
+      response.body.dump();
+      throw fromStatusCode(response.statusCode, "");
+    }
+  }
   //#endregion
   //#region list objects
   /**
@@ -1449,7 +1550,7 @@ var S3File = class _S3File {
    * @remarks - Uses [`DeleteObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html).
    *          - `versionId` not supported.
    *
-   * @param {Partial<S3FileDeleteOptions>} [options]
+   * @param {S3FileDeleteOptions} [options]
    *
    * @example
    * ```js
@@ -1540,15 +1641,16 @@ var S3File = class _S3File {
   }
   /**
    * @param {ByteSource} data
+   * @param {S3FileWriteOptions} [options.type] Defaults to the Content-Type that was used to create the {@link S3File} instance.
    * @returns {Promise<void>}
    */
-  async write(data) {
+  async write(data, options = {}) {
     const signal = void 0;
     const [bytes, length, hash] = await this.#transformData(data);
     return await this.#client[write](
       this.#path,
       bytes,
-      this.#contentType,
+      options.type ?? this.#contentType,
       length,
       hash,
       this.#start,

package/package.json

@@ -2,7 +2,7 @@
   "name": "lean-s3",
   "author": "Niklas Mollenhauer",
   "license": "MIT",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "A server-side S3 API for the regular user.",
   "keywords": [
     "s3",
@@ -44,19 +44,19 @@
   },
   "dependencies": {
     "fast-xml-parser": "^5.2.5",
-    "undici": "^7.10.0"
+    "undici": "^7.11.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.0.5",
-    "@testcontainers/localstack": "^11.0.3",
-    "@testcontainers/minio": "^11.0.3",
-    "@types/node": "^24.0.4",
-    "@typescript/native-preview": "^7.0.0-dev.20250626.1",
-    "expect": "^30.0.3",
-    "lefthook": "^1.11.14",
+    "@biomejs/biome": "2.0.6",
+    "@testcontainers/localstack": "^11.2.0",
+    "@testcontainers/minio": "^11.2.0",
+    "@types/node": "^24.0.10",
+    "@typescript/native-preview": "^7.0.0-dev.20250705.1",
+    "expect": "^30.0.4",
+    "lefthook": "^1.11.16",
     "tsup": "^8.5.0",
     "tsx": "^4.20.3",
-    "typedoc": "^0.28.5"
+    "typedoc": "^0.28.7"
   },
   "engines": {
     "node": "^20.19.2 || ^22.16.0 || ^24.2.0"