lean-s3 0.4.0 → 0.5.0

package/README.md

@@ -79,7 +79,7 @@ BUT...
 
 Due to the scalability, portability and AWS integrations of @aws-sdk/client-s3, pre-signing URLs is `async` and performs poorly in high-performance scenarios. By taking different trade-offs, lean-s3 can presign URLs much faster. I promise! This is the reason you cannot use lean-s3 in the browser.
 
-lean-s3 is currently about 30x faster than AWS SDK when it comes to pre-signing URLs[^1]:
+lean-s3 is currently about 30x faster than AWS SDK when it comes to pre-signing URLs:
 ```
 benchmark                    avg (min … max) p75 / p99
 -------------------------------------------- ---------
@@ -106,7 +106,9 @@ summary
    30.99x faster than @aws-sdk/s3-request-presigner
 ```
 
-Don't trust this benchmark and run it yourself[^2]. I am just some random internet guy trying to tell you [how much better this s3 client is](https://xkcd.com/927/). For `PUT` operations, it is ~1.45x faster than `@aws-sdk/client-s3`. We still work on improving these numbers.
+Don't trust this benchmark and [run it yourself](./BENCHMARKS.md). I am just some random internet guy trying to tell you [how much better this s3 client is](https://xkcd.com/927/). For `PUT` operations, it is ~1.5x faster than `@aws-sdk/client-s3`. We still work on improving these numbers.
+
+See [BENCHMARKS.md](./BENCHMARKS.md) for more numbers and how to run it yourself. PRs for improving the benchmarks are welcome!
 
 ## Why not lean-s3?
 Don't use lean-s3 if you
@@ -134,6 +136,9 @@ See [DESIGN_DECISIONS.md](./DESIGN_DECISIONS.md) to read about why this library
 - ✅ [`DeleteObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html) via `S3File.delete`
 - ✅ [`PutObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) via `S3File.write`
 - ✅ [`HeadObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html) via `S3File.exists`/`S3File.stat`
+- ✅ [`ListMultipartUploads`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html) via `.listMultipartUploads`
+- ✅ [`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`
 
 ## Example Configurations
 ### Hetzner Object Storage
@@ -171,6 +176,3 @@ const client = new S3Client({
 ```
 
 Popular S3 provider missing? Open an issue or file a PR!
-
-[^1]: Benchmark ran on a `13th Gen Intel(R) Core(TM) i7-1370P` using Node.js `23.11.0`. See `bench/` directory for the used benchmark.
-[^2]: `git clone git@github.com:nikeee/lean-s3.git && cd lean-s3 && npm ci && npm run build && cd bench && npm ci && npm start`

package/dist/index.d.ts

@@ -41,6 +41,7 @@ interface S3FilePresignOptions {
     /** Seconds. */
     expiresIn: number;
     method: PresignableHttpMethod;
+    contentLength: number;
     storageClass: StorageClass;
     acl: Acl;
 }
@@ -59,6 +60,75 @@ type ListObjectsIteratingOptions = {
     signal?: AbortSignal;
     internalPageSize?: number;
 };
+type ListMultipartUploadsOptions = {
+    bucket?: string;
+    delimiter?: string;
+    keyMarker?: string;
+    maxUploads?: number;
+    prefix?: string;
+    uploadIdMarker?: string;
+    signal?: AbortSignal;
+};
+type ListMultipartUploadsResult = {
+    bucket?: string;
+    keyMarker?: string;
+    uploadIdMarker?: string;
+    nextKeyMarker?: string;
+    prefix?: string;
+    delimiter?: string;
+    nextUploadIdMarker?: string;
+    maxUploads?: number;
+    isTruncated?: boolean;
+    uploads: MultipartUpload[];
+};
+type MultipartUpload = {
+    checksumAlgorithm?: ChecksumAlgorithm;
+    checksumType?: ChecksumType;
+    initiated?: Date;
+    /**
+     * Key of the object for which the multipart upload was initiated.
+     * Length Constraints: Minimum length of 1.
+     */
+    key?: string;
+    storageClass?: StorageClass;
+    /**
+     * Upload ID identifying the multipart upload.
+     */
+    uploadId?: string;
+};
+type CreateMultipartUploadOptions = {
+    bucket?: string;
+    signal?: AbortSignal;
+};
+type CreateMultipartUploadResponse = {
+    bucket: string;
+    key: string;
+    uploadId: string;
+};
+type AbortMultipartUploadOptions = {
+    bucket?: string;
+    signal?: AbortSignal;
+};
+type CompleteMultipartUploadOptions = {
+    bucket?: string;
+    signal?: AbortSignal;
+};
+type CompleteMultipartUploadResult = {
+    location?: string;
+    bucket?: string;
+    key?: string;
+    etag?: string;
+    checksumCRC32?: string;
+    checksumCRC32C?: string;
+    checksumCRC64NVME?: string;
+    checksumSHA1?: string;
+    checksumSHA256?: string;
+    checksumType?: ChecksumType;
+};
+type MultipartUploadPart = {
+    partNumber: number;
+    etag: string;
+};
 type ListObjectsResponse = {
     name: string;
     prefix: string | undefined;
@@ -129,7 +199,7 @@ declare class S3Client {
      *
      * lean-s3 does not enforce these restrictions.
      *
-     * @param {Partial<CreateFileInstanceOptions>} [options] TODO
+     * @param {Partial<CreateFileInstanceOptions>} [_options] TODO
      * @example
      * ```js
      * const file = client.file("image.jpg");
@@ -141,7 +211,7 @@ declare class S3Client {
      * });
      * ```
      */
-    file(path: string, options?: Partial<CreateFileInstanceOptions>): S3File;
+    file(path: string, _options?: Partial<CreateFileInstanceOptions>): S3File;
     /**
      * Generate a presigned URL for temporary access to a file.
      * Useful for generating upload/download URLs without exposing credentials.
@@ -155,18 +225,36 @@ declare class S3Client {
      * ```
      */
     presign(path: string, { method, expiresIn, // TODO: Maybe rename this to expiresInSeconds
-    storageClass, acl, region: regionOverride, bucket: bucketOverride, endpoint: endpointOverride, }?: Partial<S3FilePresignOptions & OverridableS3ClientOptions>): string;
+    storageClass, contentLength, acl, region: regionOverride, bucket: bucketOverride, endpoint: endpointOverride, }?: Partial<S3FilePresignOptions & OverridableS3ClientOptions>): string;
+    createMultipartUpload(key: string, options?: CreateMultipartUploadOptions): Promise<CreateMultipartUploadResponse>;
     /**
-     * Uses [`DeleteObjects`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) to delete multiple objects in a single request.
+     * @remarks Uses [`ListMultipartUploads`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html).
+     * @throws {RangeError} If `options.maxKeys` is not between `1` and `1000`.
      */
-    deleteObjects(objects: readonly S3BucketEntry[] | readonly string[], options?: DeleteObjectsOptions): Promise<{
-        errors: {
-            code: any;
-            key: any;
-            message: any;
-            versionId: any;
-        }[];
-    } | null>;
+    listMultipartUploads(options?: ListMultipartUploadsOptions): Promise<ListMultipartUploadsResult>;
+    /**
+     * @remarks Uses [`AbortMultipartUpload`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html).
+     * @throws {RangeError} If `key` is not at least 1 character long.
+     * @throws {Error} If `uploadId` is not provided.
+     */
+    abortMultipartUpload(key: string, uploadId: string, options?: AbortMultipartUploadOptions): Promise<void>;
+    /**
+     * @remarks Uses [`CompleteMultipartUpload`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html).
+     * @throws {RangeError} If `key` is not at least 1 character long.
+     * @throws {Error} If `uploadId` is not provided.
+     */
+    completeMultipartUpload(key: string, uploadId: string, parts: readonly MultipartUploadPart[], options?: CompleteMultipartUploadOptions): Promise<{
+        location: any;
+        bucket: any;
+        key: any;
+        etag: any;
+        checksumCRC32: any;
+        checksumCRC32C: any;
+        checksumCRC64NVME: any;
+        checksumSHA1: any;
+        checksumSHA256: any;
+        checksumType: any;
+    }>;
     /**
      * Creates a new bucket on the S3 server.
      *
@@ -203,8 +291,16 @@ declare class S3Client {
     listIterating(options: ListObjectsIteratingOptions): AsyncGenerator<S3BucketEntry>;
     /**
      * Implements [`ListObjectsV2`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) to iterate over all keys.
+     *
+     * @throws {RangeError} If `maxKeys` is not between `1` and `1000`.
      */
     list(options?: ListObjectsOptions): Promise<ListObjectsResponse>;
+    /**
+     * 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>;
     /**
      * Do not use this. This is an internal method.
      * TODO: Maybe move this into a separate free function?
@@ -338,4 +434,4 @@ type BucketInfo = {
     type?: string;
 };
 
-export { type Acl, type BucketCreationOptions, type BucketDeletionOptions, type BucketExistsOptions, type BucketInfo, type BucketLocationInfo, type ByteSource, type ChecksumAlgorithm, type ChecksumType, type CreateFileInstanceOptions, type DeleteObjectsOptions, type HttpMethod, type ListObjectsIteratingOptions, type ListObjectsOptions, type ListObjectsResponse, 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 };
+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 CreateMultipartUploadResponse, type DeleteObjectsOptions, type HttpMethod, type ListMultipartUploadsOptions, type ListMultipartUploadsResult, type ListObjectsIteratingOptions, type ListObjectsOptions, type ListObjectsResponse, 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 };

package/dist/index.js

@@ -1,28 +1,6 @@
 // src/S3File.ts
 import { Readable } from "stream";
 
-// src/S3Error.ts
-var S3Error = class extends Error {
-  code;
-  path;
-  message;
-  requestId;
-  hostId;
-  constructor(code, path, {
-    message = void 0,
-    requestId = void 0,
-    hostId = void 0,
-    cause = void 0
-  } = {}) {
-    super(message, { cause });
-    this.code = code;
-    this.path = path;
-    this.message = message ?? "Some unknown error occurred.";
-    this.requestId = requestId;
-    this.hostId = hostId;
-  }
-};
-
 // src/S3Stat.ts
 var S3Stat = class _S3Stat {
   etag;
@@ -64,6 +42,28 @@ var S3Stat = class _S3Stat {
 import { request, Agent } from "undici";
 import { XMLParser as XMLParser2, XMLBuilder } from "fast-xml-parser";
 
+// src/S3Error.ts
+var S3Error = class extends Error {
+  code;
+  path;
+  message;
+  requestId;
+  hostId;
+  constructor(code, path, {
+    message = void 0,
+    requestId = void 0,
+    hostId = void 0,
+    cause = void 0
+  } = {}) {
+    super(message, { cause });
+    this.code = code;
+    this.path = path;
+    this.message = message ?? "Some unknown error occurred.";
+    this.requestId = requestId;
+    this.hostId = hostId;
+  }
+};
+
 // src/S3BucketEntry.ts
 var S3BucketEntry = class _S3BucketEntry {
   key;
@@ -238,7 +238,7 @@ function getRangeHeader(start, endExclusive) {
 import { XMLParser } from "fast-xml-parser";
 var xmlParser = new XMLParser();
 async function getResponseError(response, path) {
-  let body = void 0;
+  let body;
   try {
     body = await response.body.text();
   } catch (cause) {
@@ -270,7 +270,7 @@ function fromStatusCode(code, path) {
   }
 }
 function parseAndGetXmlError(body, path) {
-  let error = void 0;
+  let error;
   try {
     error = xmlParser.parse(body);
   } catch (cause) {
@@ -322,7 +322,10 @@ function getAuthorizationHeader(keyCache, method, path, query, date, sortedSigne
 var write = Symbol("write");
 var stream = Symbol("stream");
 var signedRequest = Symbol("signedRequest");
-var xmlParser2 = new XMLParser2();
+var xmlParser2 = new XMLParser2({
+  ignoreAttributes: true,
+  isArray: (_, jPath) => jPath === "ListMultipartUploadsResult.Upload" || jPath === "ListBucketResult.Contents" || jPath === "DeleteResult.Deleted" || jPath === "DeleteResult.Error"
+});
 var xmlBuilder = new XMLBuilder({
   attributeNamePrefix: "$",
   ignoreAttributes: false
@@ -396,7 +399,7 @@ var S3Client = class {
    *
    * lean-s3 does not enforce these restrictions.
    *
-   * @param {Partial<CreateFileInstanceOptions>} [options] TODO
+   * @param {Partial<CreateFileInstanceOptions>} [_options] TODO
    * @example
    * ```js
    * const file = client.file("image.jpg");
@@ -408,7 +411,7 @@ var S3Client = class {
    * });
    * ```
    */
-  file(path, options) {
+  file(path, _options) {
     return new S3File(this, path, void 0, void 0, void 0);
   }
   /**
@@ -428,11 +431,17 @@ var S3Client = class {
     expiresIn = 3600,
     // TODO: Maybe rename this to expiresInSeconds
     storageClass,
+    contentLength,
     acl,
     region: regionOverride,
     bucket: bucketOverride,
     endpoint: endpointOverride
   } = {}) {
+    if (typeof contentLength === "number") {
+      if (contentLength < 0) {
+        throw new RangeError("`contentLength` must be >= 0.");
+      }
+    }
     const now2 = /* @__PURE__ */ new Date();
     const date = getAmzDate(now2);
     const options = this.#options;
@@ -444,13 +453,19 @@ var S3Client = class {
       `${options.accessKeyId}/${date.date}/${region}/s3/aws4_request`,
       date,
       expiresIn,
-      "host",
-      void 0,
+      typeof contentLength === "number" ? "content-length;host" : "host",
+      unsignedPayload,
       storageClass,
       options.sessionToken,
       acl
     );
-    const dataDigest = createCanonicalDataDigestHostOnly(
+    const dataDigest = typeof contentLength === "number" ? createCanonicalDataDigest(
+      method,
+      res.pathname,
+      query,
+      { "content-length": String(contentLength), host: res.host },
+      unsignedPayload
+    ) : createCanonicalDataDigestHostOnly(
       method,
       res.pathname,
       query,
@@ -471,64 +486,189 @@ var S3Client = class {
     res.search = `${query}&X-Amz-Signature=${signature}`;
     return res.toString();
   }
+  //#region multipart uploads
+  async createMultipartUpload(key, options = {}) {
+    if (key.length < 1) {
+      throw new RangeError("`key` must be at least 1 character long.");
+    }
+    const response = await this[signedRequest](
+      "POST",
+      key,
+      "uploads=",
+      void 0,
+      void 0,
+      void 0,
+      void 0,
+      ensureValidBucketName(options.bucket ?? this.#options.bucket),
+      options.signal
+    );
+    if (response.statusCode !== 200) {
+      throw await getResponseError(response, key);
+    }
+    const text = await response.body.text();
+    const res = ensureParsedXml(text).InitiateMultipartUploadResult ?? {};
+    return {
+      bucket: res.Bucket,
+      key: res.Key,
+      uploadId: res.UploadId
+    };
+  }
   /**
-   * Uses [`DeleteObjects`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) to delete multiple objects in a single request.
+   * @remarks Uses [`ListMultipartUploads`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html).
+   * @throws {RangeError} If `options.maxKeys` is not between `1` and `1000`.
    */
-  async deleteObjects(objects, options = {}) {
+  async listMultipartUploads(options = {}) {
+    const bucket = ensureValidBucketName(
+      options.bucket ?? this.#options.bucket
+    );
+    let query = "uploads=";
+    if (options.delimiter) {
+      if (typeof options.delimiter !== "string") {
+        throw new TypeError("`delimiter` should be a `string`.");
+      }
+      query += `&delimiter=${encodeURIComponent(options.delimiter)}`;
+    }
+    if (options.keyMarker) {
+      if (typeof options.keyMarker !== "string") {
+        throw new TypeError("`keyMarker` should be a `string`.");
+      }
+      query += `&key-marker=${encodeURIComponent(options.keyMarker)}`;
+    }
+    if (typeof options.maxUploads !== "undefined") {
+      if (typeof options.maxUploads !== "number") {
+        throw new TypeError("`maxUploads` should be a `number`.");
+      }
+      if (options.maxUploads < 1 || options.maxUploads > 1e3) {
+        throw new RangeError("`maxUploads` should be between 1 and 1000.");
+      }
+      query += `&max-uploads=${options.maxUploads}`;
+    }
+    if (options.prefix) {
+      if (typeof options.prefix !== "string") {
+        throw new TypeError("`prefix` should be a `string`.");
+      }
+      query += `&prefix=${encodeURIComponent(options.prefix)}`;
+    }
+    const response = await this[signedRequest](
+      "GET",
+      "",
+      query,
+      void 0,
+      void 0,
+      void 0,
+      void 0,
+      bucket,
+      options.signal
+    );
+    if (response.statusCode !== 200) {
+      throw await getResponseError(response, "");
+    }
+    const text = await response.body.text();
+    const root = ensureParsedXml(text).ListMultipartUploadsResult ?? {};
+    return {
+      bucket: root.Bucket || void 0,
+      delimiter: root.Delimiter || void 0,
+      prefix: root.Prefix || void 0,
+      keyMarker: root.KeyMarker || void 0,
+      uploadIdMarker: root.UploadIdMarker || void 0,
+      nextKeyMarker: root.NextKeyMarker || void 0,
+      nextUploadIdMarker: root.NextUploadIdMarker || void 0,
+      maxUploads: root.MaxUploads ?? 1e3,
+      // not using || to not override 0; caution: minio supports 10000(!)
+      isTruncated: root.IsTruncated === "true",
+      uploads: root.Upload?.map(
+        // biome-ignore lint/suspicious/noExplicitAny: we're parsing here
+        (u) => ({
+          key: u.Key || void 0,
+          uploadId: u.UploadId || void 0,
+          // TODO: Initiator
+          // TODO: Owner
+          storageClass: u.StorageClass || void 0,
+          checksumAlgorithm: u.ChecksumAlgorithm || void 0,
+          checksumType: u.ChecksumType || void 0,
+          initiated: u.Initiated ? new Date(u.Initiated) : void 0
+        })
+      ) ?? []
+    };
+  }
+  /**
+   * @remarks Uses [`AbortMultipartUpload`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html).
+   * @throws {RangeError} If `key` is not at least 1 character long.
+   * @throws {Error} If `uploadId` is not provided.
+   */
+  async abortMultipartUpload(key, uploadId, options = {}) {
+    if (key.length < 1) {
+      throw new RangeError("`key` must be at least 1 character long.");
+    }
+    if (!uploadId) {
+      throw new Error("`uploadId` is required.");
+    }
+    const response = await this[signedRequest](
+      "DELETE",
+      key,
+      `uploadId=${encodeURIComponent(uploadId)}`,
+      void 0,
+      void 0,
+      void 0,
+      void 0,
+      ensureValidBucketName(options.bucket ?? this.#options.bucket),
+      options.signal
+    );
+    if (response.statusCode !== 204) {
+      throw await getResponseError(response, key);
+    }
+  }
+  /**
+   * @remarks Uses [`CompleteMultipartUpload`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html).
+   * @throws {RangeError} If `key` is not at least 1 character long.
+   * @throws {Error} If `uploadId` is not provided.
+   */
+  async completeMultipartUpload(key, uploadId, parts, options = {}) {
+    if (key.length < 1) {
+      throw new RangeError("`key` must be at least 1 character long.");
+    }
+    if (!uploadId) {
+      throw new Error("`uploadId` is required.");
+    }
     const body = xmlBuilder.build({
-      Delete: {
-        Quiet: true,
-        Object: objects.map((o) => ({
-          Key: typeof o === "string" ? o : o.key
+      CompleteMultipartUpload: {
+        Part: parts.map((part) => ({
+          PartNumber: part.partNumber,
+          ETag: part.etag
         }))
       }
     });
     const response = await this[signedRequest](
       "POST",
-      "",
-      "delete=",
-      // "=" is needed by minio for some reason
+      key,
+      `uploadId=${encodeURIComponent(uploadId)}`,
       body,
-      {
-        "content-md5": md5Base64(body)
-      },
       void 0,
       void 0,
-      this.#options.bucket,
+      void 0,
+      ensureValidBucketName(options.bucket ?? this.#options.bucket),
       options.signal
     );
-    if (response.statusCode === 200) {
-      const text = await response.body.text();
-      let res = void 0;
-      try {
-        res = (xmlParser2.parse(text)?.DeleteResult || void 0)?.Error ?? [];
-      } catch (cause) {
-        throw new S3Error("Unknown", "", {
-          message: "S3 service responded with invalid XML.",
-          cause
-        });
-      }
-      if (!res || !Array.isArray(res)) {
-        throw new S3Error("Unknown", "", {
-          message: "Could not process response."
-        });
-      }
-      const errors = res.map((e) => ({
-        code: e.Code,
-        key: e.Key,
-        message: e.Message,
-        versionId: e.VersionId
-      }));
-      return errors.length > 0 ? { errors } : null;
-    }
-    if (400 <= response.statusCode && response.statusCode < 500) {
-      throw await getResponseError(response, "");
+    if (response.statusCode !== 200) {
+      throw await getResponseError(response, key);
     }
-    response.body.dump();
-    throw new Error(
-      `Response code not implemented yet: ${response.statusCode}`
-    );
+    const text = await response.body.text();
+    const res = ensureParsedXml(text).CompleteMultipartUploadResult ?? {};
+    return {
+      location: res.Location || void 0,
+      bucket: res.Bucket || void 0,
+      key: res.Key || void 0,
+      etag: res.ETag || void 0,
+      checksumCRC32: res.ChecksumCRC32 || void 0,
+      checksumCRC32C: res.ChecksumCRC32C || void 0,
+      checksumCRC64NVME: res.ChecksumCRC64NVME || void 0,
+      checksumSHA1: res.ChecksumSHA1 || void 0,
+      checksumSHA256: res.ChecksumSHA256 || void 0,
+      checksumType: res.ChecksumType || void 0
+    };
   }
+  //#endregion
+  //#region bucket operations
   /**
    * Creates a new bucket on the S3 server.
    *
@@ -544,8 +684,7 @@ var S3Client = class {
    * @remarks Uses [`CreateBucket`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html)
    */
   async createBucket(name, options) {
-    ensureValidBucketName(name);
-    let body = void 0;
+    let body;
     if (options) {
       const location = options.location && (options.location.name || options.location.type) ? {
         Name: options.location.name ?? void 0,
@@ -573,7 +712,7 @@ var S3Client = class {
       additionalSignedHeaders,
       void 0,
       void 0,
-      name,
+      ensureValidBucketName(name),
       options?.signal
     );
     if (400 <= response.statusCode && response.statusCode < 500) {
@@ -593,7 +732,6 @@ var S3Client = class {
    * @remarks Uses [`DeleteBucket`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucket.html).
    */
   async deleteBucket(name, options) {
-    ensureValidBucketName(name);
     const response = await this[signedRequest](
       "DELETE",
       "",
@@ -602,7 +740,7 @@ var S3Client = class {
       void 0,
       void 0,
       void 0,
-      name,
+      ensureValidBucketName(name),
       options?.signal
     );
     if (400 <= response.statusCode && response.statusCode < 500) {
@@ -621,7 +759,6 @@ var S3Client = class {
    * @remarks Uses [`HeadBucket`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadBucket.html).
    */
   async bucketExists(name, options) {
-    ensureValidBucketName(name);
     const response = await this[signedRequest](
       "HEAD",
       "",
@@ -630,7 +767,7 @@ var S3Client = class {
       void 0,
       void 0,
       void 0,
-      name,
+      ensureValidBucketName(name),
       options?.signal
     );
     if (response.statusCode !== 404 && 400 <= response.statusCode && response.statusCode < 500) {
@@ -645,16 +782,16 @@ var S3Client = class {
     }
     throw new Error(`Response code not supported: ${response.statusCode}`);
   }
-  //#region list
+  //#endregion
+  //#region list objects
   /**
    * Uses [`ListObjectsV2`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) to iterate over all keys. Pagination and continuation is handled internally.
    */
   async *listIterating(options) {
     const maxKeys = options?.internalPageSize ?? void 0;
-    let res = void 0;
-    let continuationToken = void 0;
+    let continuationToken;
     do {
-      res = await this.list({
+      const res = await this.list({
         ...options,
         maxKeys,
         continuationToken
@@ -668,6 +805,8 @@ var S3Client = class {
   }
   /**
    * Implements [`ListObjectsV2`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) to iterate over all keys.
+   *
+   * @throws {RangeError} If `maxKeys` is not between `1` and `1000`.
    */
   async list(options = {}) {
     let query = "";
@@ -682,6 +821,9 @@ var S3Client = class {
       if (typeof options.maxKeys !== "number") {
         throw new TypeError("`maxKeys` should be a `number`.");
       }
+      if (options.maxKeys < 1 || options.maxKeys > 1e3) {
+        throw new RangeError("`maxKeys` should be between 1 and 1000.");
+      }
       query += `&max-keys=${options.maxKeys}`;
     }
     if (options.prefix) {
@@ -707,41 +849,88 @@ var S3Client = class {
       options.bucket ?? this.#options.bucket,
       options.signal
     );
+    if (response.statusCode !== 200) {
+      response.body.dump();
+      throw new Error(
+        `Response code not implemented yet: ${response.statusCode}`
+      );
+    }
+    const text = await response.body.text();
+    const res = ensureParsedXml(text).ListBucketResult ?? {};
+    if (!res) {
+      throw new S3Error("Unknown", "", {
+        message: "Could not read bucket contents."
+      });
+    }
+    return {
+      name: res.Name,
+      prefix: res.Prefix,
+      startAfter: res.StartAfter,
+      isTruncated: res.IsTruncated,
+      continuationToken: res.ContinuationToken,
+      maxKeys: res.MaxKeys,
+      keyCount: res.KeyCount,
+      nextContinuationToken: res.NextContinuationToken,
+      contents: res.Contents?.map(S3BucketEntry.parse) ?? []
+    };
+  }
+  //#endregion
+  /**
+   * Uses [`DeleteObjects`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) to delete multiple objects in a single request.
+   */
+  async deleteObjects(objects, options = {}) {
+    const body = xmlBuilder.build({
+      Delete: {
+        Quiet: true,
+        Object: objects.map((o) => ({
+          Key: typeof o === "string" ? o : o.key
+        }))
+      }
+    });
+    const response = await this[signedRequest](
+      "POST",
+      "",
+      "delete=",
+      // "=" is needed by minio for some reason
+      body,
+      {
+        "content-md5": md5Base64(body)
+      },
+      void 0,
+      void 0,
+      this.#options.bucket,
+      options.signal
+    );
     if (response.statusCode === 200) {
       const text = await response.body.text();
-      let res = void 0;
+      let deleteResult;
       try {
-        res = xmlParser2.parse(text)?.ListBucketResult;
+        deleteResult = ensureParsedXml(text).DeleteResult ?? {};
       } catch (cause) {
         throw new S3Error("Unknown", "", {
           message: "S3 service responded with invalid XML.",
           cause
         });
       }
-      if (!res) {
-        throw new S3Error("Unknown", "", {
-          message: "Could not read bucket contents."
-        });
-      }
-      const contents = Array.isArray(res.Contents) ? res.Contents?.map(S3BucketEntry.parse) ?? [] : res.Contents ? [res.Contents] : [];
-      return {
-        name: res.Name,
-        prefix: res.Prefix,
-        startAfter: res.StartAfter,
-        isTruncated: res.IsTruncated,
-        continuationToken: res.ContinuationToken,
-        maxKeys: res.MaxKeys,
-        keyCount: res.KeyCount,
-        nextContinuationToken: res.NextContinuationToken,
-        contents
-      };
+      const errors = (
+        // biome-ignore lint/suspicious/noExplicitAny: parsing
+        deleteResult.Error?.map((e) => ({
+          code: e.Code,
+          key: e.Key,
+          message: e.Message,
+          versionId: e.VersionId
+        })) ?? []
+      );
+      return errors.length > 0 ? { errors } : null;
+    }
+    if (400 <= response.statusCode && response.statusCode < 500) {
+      throw await getResponseError(response, "");
     }
     response.body.dump();
     throw new Error(
       `Response code not implemented yet: ${response.statusCode}`
     );
   }
-  //#endregion
   /**
    * Do not use this. This is an internal method.
    * TODO: Maybe move this into a separate free function?
@@ -819,7 +1008,7 @@ var S3Client = class {
       "x-amz-content-sha256": contentHashStr,
       "x-amz-date": now2.dateTime
     });
-    let response = void 0;
+    let response;
     try {
       response = await request(url, {
         method: "PUT",
@@ -942,10 +1131,9 @@ var S3Client = class {
           }
           if (400 <= status && status < 500) {
             const responseText = void 0;
-            const ct = response.headers["content-type"];
             if (response.headers["content-type"] === "application/xml") {
               return response.body.text().then((body) => {
-                let error = void 0;
+                let error;
                 try {
                   error = xmlParser2.parse(body);
                 } catch (cause) {
@@ -1020,6 +1208,23 @@ function ensureValidBucketName(name) {
   if (name.includes("..")) {
     throw new Error("`name` must not contain two adjacent periods (..)");
   }
+  return name;
+}
+function ensureParsedXml(text) {
+  try {
+    const r = xmlParser2.parse(text);
+    if (!r) {
+      throw new S3Error("Unknown", "", {
+        message: "S3 service responded with empty XML."
+      });
+    }
+    return r;
+  } catch (cause) {
+    throw new S3Error("Unknown", "", {
+      message: "S3 service responded with invalid XML.",
+      cause
+    });
+  }
 }
 
 // src/assertNever.ts

package/package.json

@@ -2,7 +2,7 @@
   "name": "lean-s3",
   "author": "Niklas Mollenhauer",
   "license": "MIT",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A server-side S3 API for the regular user.",
   "keywords": [
     "s3",
@@ -47,13 +47,13 @@
     "undici": "^7.10.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
+    "@biomejs/biome": "^2.0.0",
     "@testcontainers/localstack": "^11.0.3",
     "@testcontainers/minio": "^11.0.3",
-    "@types/node": "^24.0.1",
-    "@typescript/native-preview": "^7.0.0-dev.20250613.1",
-    "expect": "^30.0.0",
-    "lefthook": "^1.11.13",
+    "@types/node": "^24.0.3",
+    "@typescript/native-preview": "^7.0.0-dev.20250619.1",
+    "expect": "^30.0.2",
+    "lefthook": "^1.11.14",
     "tsup": "^8.5.0",
     "tsx": "^4.20.3",
     "typedoc": "^0.28.5"