lean-s3 0.6.1 → 0.6.3

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

@@ -45,6 +45,15 @@ type DeleteObjectsOptions = {
     bucket?: string;
     signal?: AbortSignal;
 };
+type DeleteObjectsResult = {
+    errors: DeleteObjectsError[];
+};
+type DeleteObjectsError = {
+    code: string;
+    key: string;
+    message: string;
+    versionId: string;
+};
 interface S3FilePresignOptions {
     contentHash: Buffer;
     /** Seconds. */
@@ -58,6 +67,7 @@ type ListObjectsOptions = {
     bucket?: string;
     prefix?: string;
     maxKeys?: number;
+    delimiter?: string;
     startAfter?: string;
     continuationToken?: string;
     signal?: AbortSignal;
@@ -198,6 +208,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.
  *
@@ -222,6 +261,11 @@ declare class S3Client {
      * @param  options The default options to use for the S3 client.
      */
     constructor(options: S3ClientOptions);
+    cors: {
+        get: () => void;
+        set: () => void;
+        delete: () => void;
+    };
     /**
      * Creates an S3File instance for the given path.
      *
@@ -335,6 +379,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.
      */
@@ -348,9 +404,7 @@ declare class S3Client {
     /**
      * Uses [`DeleteObjects`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) to delete multiple objects in a single request.
      */
-    deleteObjects(objects: readonly S3BucketEntry[] | readonly string[], options?: DeleteObjectsOptions): Promise<{
-        errors: any;
-    } | null>;
+    deleteObjects(objects: readonly S3BucketEntry[] | readonly string[], options?: DeleteObjectsOptions): Promise<DeleteObjectsResult>;
     /**
      * Do not use this. This is an internal method.
      * TODO: Maybe move this into a separate free function?
@@ -379,9 +433,7 @@ declare class S3Stat {
 
 declare class S3File {
     #private;
-    /**
-     * @internal
-     */
+    /** @internal */
     constructor(client: S3Client, path: ObjectKey, start: number | undefined, end: number | undefined, contentType: string | undefined);
     slice(start?: number | undefined, end?: number | undefined, contentType?: string | undefined): S3File;
     /**
@@ -391,13 +443,13 @@ 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({ signal }?: Partial<S3StatOptions>): Promise<S3Stat>;
+    stat(options?: Partial<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({ signal, }?: Partial<S3FileExistsOptions>): Promise<boolean>;
+    exists(options?: Partial<S3FileExistsOptions>): Promise<boolean>;
     /**
      * Delete a file from the bucket.
      *
@@ -409,18 +461,18 @@ declare class S3File {
      * @example
      * ```js
      * // Simple delete
-     * await client.unlink("old-file.txt");
+     * await client.delete("old-file.txt");
      *
      * // With error handling
      * try {
-     *   await client.unlink("file.dat");
+     *   await client.delete("file.dat");
      *   console.log("File deleted");
      * } catch (err) {
      *   console.error("Delete failed:", err);
      * }
      * ```
      */
-    delete({ signal }?: Partial<S3FileDeleteOptions>): Promise<void>;
+    delete(options?: Partial<S3FileDeleteOptions>): Promise<void>;
     toString(): string;
     json(): Promise<unknown>;
     bytes(): Promise<Uint8Array>;
@@ -484,4 +536,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 DeleteObjectsOptions, 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 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, S3Stat, type S3StatOptions, type StorageClass, type UndiciBodyInit, type UploadPartOptions, type UploadPartResult };

package/dist/index.js

@@ -202,7 +202,7 @@ function buildRequestUrl(endpoint, bucket, region, path) {
   const result = new URL(endpointWithBucketAndRegion);
   const pathPrefix = result.pathname.endsWith("/") ? result.pathname : `${result.pathname}/`;
   const pathSuffix = replacedBucket ? normalizePath(path) : `${normalizedBucket}/${normalizePath(path)}`;
-  result.pathname = pathPrefix + pathSuffix.replaceAll(":", "%3A").replaceAll("+", "%2B").replaceAll("(", "%28").replaceAll(")", "%29");
+  result.pathname = pathPrefix + pathSuffix.replaceAll(":", "%3A").replaceAll("+", "%2B").replaceAll("(", "%28").replaceAll(")", "%29").replaceAll(",", "%2C");
   return result;
 }
 function replaceDomainPlaceholders(endpoint, bucket, region) {
@@ -404,6 +404,14 @@ var S3Client = class {
       sessionToken
     };
   }
+  cors = {
+    get: () => {
+    },
+    set: () => {
+    },
+    delete: () => {
+    }
+  };
   /**
    * Creates an S3File instance for the given path.
    *
@@ -721,7 +729,7 @@ var S3Client = class {
       options.signal
     );
     if (response.statusCode === 200) {
-      await response.body.dump();
+      response.body.dump();
       const etag = response.headers.etag;
       if (typeof etag !== "string" || etag.length === 0) {
         throw new S3Error("Unknown", "", {
@@ -848,7 +856,7 @@ var S3Client = class {
     if (400 <= response.statusCode && response.statusCode < 500) {
       throw await getResponseError(response, "");
     }
-    await response.body.dump();
+    response.body.dump();
     if (response.statusCode === 200) {
       return;
     }
@@ -876,7 +884,7 @@ var S3Client = class {
     if (400 <= response.statusCode && response.statusCode < 500) {
       throw await getResponseError(response, "");
     }
-    await response.body.dump();
+    response.body.dump();
     if (response.statusCode === 204) {
       return;
     }
@@ -903,7 +911,7 @@ var S3Client = class {
     if (response.statusCode !== 404 && 400 <= response.statusCode && response.statusCode < 500) {
       throw await getResponseError(response, "");
     }
-    await response.body.dump();
+    response.body.dump();
     if (response.statusCode === 200) {
       return true;
     }
@@ -912,6 +920,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
   /**
@@ -956,6 +1048,12 @@ var S3Client = class {
       }
       query += `&max-keys=${options.maxKeys}`;
     }
+    if (typeof options.delimiter !== "undefined") {
+      if (typeof options.delimiter !== "string") {
+        throw new TypeError("`delimiter` must be a `string`.");
+      }
+      query += `&delimiter=${options.delimiter === "/" ? "/" : encodeURIComponent(options.delimiter)}`;
+    }
     if (options.prefix) {
       if (typeof options.prefix !== "string") {
         throw new TypeError("`prefix` must be a `string`.");
@@ -1051,7 +1149,7 @@ var S3Client = class {
           versionId: e.VersionId
         })) ?? []
       );
-      return errors.length > 0 ? { errors } : null;
+      return { errors };
     }
     if (400 <= response.statusCode && response.statusCode < 500) {
       throw await getResponseError(response, "");
@@ -1352,9 +1450,7 @@ var S3File = class _S3File {
   #start;
   #end;
   #contentType;
-  /**
-   * @internal
-   */
+  /** @internal */
   constructor(client, path, start, end, contentType) {
     if (typeof start === "number" && start < 0) {
       throw new Error("Invalid slice `start`.");
@@ -1385,7 +1481,7 @@ var S3File = 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.
    */
-  async stat({ signal } = {}) {
+  async stat(options = {}) {
     const response = await this.#client[signedRequest](
       "HEAD",
       this.#path,
@@ -1395,9 +1491,9 @@ var S3File = class _S3File {
       void 0,
       void 0,
       void 0,
-      signal
+      options.signal
     );
-    await response.body.dump();
+    response.body.dump();
     if (200 <= response.statusCode && response.statusCode < 300) {
       const result = S3Stat.tryParseFromHeaders(response.headers);
       if (!result) {
@@ -1416,9 +1512,7 @@ var S3File = class _S3File {
    *
    * @remarks Uses [`HeadObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html).
    */
-  async exists({
-    signal
-  } = {}) {
+  async exists(options = {}) {
     const response = await this.#client[signedRequest](
       "HEAD",
       this.#path,
@@ -1428,9 +1522,9 @@ var S3File = class _S3File {
       void 0,
       void 0,
       void 0,
-      signal
+      options.signal
     );
-    await response.body.dump();
+    response.body.dump();
     if (200 <= response.statusCode && response.statusCode < 300) {
       return true;
     }
@@ -1452,18 +1546,18 @@ var S3File = class _S3File {
    * @example
    * ```js
    * // Simple delete
-   * await client.unlink("old-file.txt");
+   * await client.delete("old-file.txt");
    *
    * // With error handling
    * try {
-   *   await client.unlink("file.dat");
+   *   await client.delete("file.dat");
    *   console.log("File deleted");
    * } catch (err) {
    *   console.error("Delete failed:", err);
    * }
    * ```
    */
-  async delete({ signal } = {}) {
+  async delete(options = {}) {
     const response = await this.#client[signedRequest](
       "DELETE",
       this.#path,
@@ -1473,10 +1567,10 @@ var S3File = class _S3File {
       void 0,
       void 0,
       void 0,
-      signal
+      options.signal
     );
     if (response.statusCode === 204) {
-      await response.body.dump();
+      response.body.dump();
       return;
     }
     throw await getResponseError(response, this.#path);
@@ -1556,10 +1650,6 @@ var S3File = class _S3File {
   }
   /*
   // Future API?
-  writer(): WritableStream<ArrayBufferLike | ArrayBufferView> {
-  	throw new Error("Not implemented");
-  }
-  // Future API?
   setTags(): Promise<void> {
   	throw new Error("Not implemented");
   }

package/package.json

@@ -2,7 +2,7 @@
   "name": "lean-s3",
   "author": "Niklas Mollenhauer",
   "license": "MIT",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "A server-side S3 API for the regular user.",
   "keywords": [
     "s3",
@@ -44,20 +44,19 @@
   },
   "dependencies": {
     "fast-xml-parser": "^5.2.5",
-    "i": "^0.3.7",
-    "undici": "^7.10.0"
+    "undici": "^7.11.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.0.0",
+    "@biomejs/biome": "2.0.6",
     "@testcontainers/localstack": "^11.0.3",
     "@testcontainers/minio": "^11.0.3",
-    "@types/node": "^24.0.3",
-    "@typescript/native-preview": "^7.0.0-dev.20250620.1",
-    "expect": "^30.0.2",
+    "@types/node": "^24.0.7",
+    "@typescript/native-preview": "^7.0.0-dev.20250629.1",
+    "expect": "^30.0.3",
     "lefthook": "^1.11.14",
     "tsup": "^8.5.0",
     "tsx": "^4.20.3",
-    "typedoc": "^0.28.5"
+    "typedoc": "^0.28.6"
   },
   "engines": {
     "node": "^20.19.2 || ^22.16.0 || ^24.2.0"