lean-s3 0.5.0 → 0.6.0

package/README.md

@@ -137,6 +137,8 @@ See [DESIGN_DECISIONS.md](./DESIGN_DECISIONS.md) to read about why this library
 - ✅ [`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`
+- ✅ [`ListParts`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html) via `.listParts`
+- ✅ [`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`
 

package/dist/index.d.ts

@@ -100,7 +100,7 @@ type CreateMultipartUploadOptions = {
     bucket?: string;
     signal?: AbortSignal;
 };
-type CreateMultipartUploadResponse = {
+type CreateMultipartUploadResult = {
     bucket: string;
     key: string;
     uploadId: string;
@@ -129,7 +129,44 @@ type MultipartUploadPart = {
     partNumber: number;
     etag: string;
 };
-type ListObjectsResponse = {
+type UploadPartOptions = {
+    bucket?: string;
+    signal?: AbortSignal;
+};
+type UploadPartResult = {
+    partNumber: number;
+    etag: string;
+};
+type ListPartsOptions = {
+    maxParts?: number;
+    partNumberMarker?: string;
+    bucket?: string;
+    signal?: AbortSignal;
+};
+type ListPartsResult = {
+    bucket: string;
+    key: string;
+    uploadId: string;
+    partNumberMarker?: string;
+    nextPartNumberMarker?: string;
+    maxParts?: number;
+    isTruncated: boolean;
+    parts: Array<{
+        checksumCRC32?: string;
+        checksumCRC32C?: string;
+        checksumCRC64NVME?: string;
+        checksumSHA1?: string;
+        checksumSHA256?: string;
+        etag: string;
+        lastModified: Date;
+        partNumber: number;
+        size: number;
+    }>;
+    storageClass?: StorageClass;
+    checksumAlgorithm?: ChecksumAlgorithm;
+    checksumType?: ChecksumType;
+};
+type ListObjectsResult = {
     name: string;
     prefix: string | undefined;
     startAfter: string | undefined;
@@ -226,7 +263,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;
-    createMultipartUpload(key: string, options?: CreateMultipartUploadOptions): Promise<CreateMultipartUploadResponse>;
+    createMultipartUpload(key: string, options?: CreateMultipartUploadOptions): Promise<CreateMultipartUploadResult>;
     /**
      * @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`.
@@ -243,18 +280,22 @@ declare class S3Client {
      * @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;
-    }>;
+    completeMultipartUpload(key: string, uploadId: string, parts: readonly MultipartUploadPart[], options?: CompleteMultipartUploadOptions): Promise<CompleteMultipartUploadResult>;
+    /**
+     * @remarks Uses [`UploadPart`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html).
+     * @throws {RangeError} If `key` is not at least 1 character long.
+     * @throws {Error} If `uploadId` is not provided.
+     */
+    uploadPart(key: string, uploadId: string, data: UndiciBodyInit, partNumber: number, options?: UploadPartOptions): Promise<UploadPartResult>;
+    /**
+     * @remarks Uses [`ListParts`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html).
+     * @throws {RangeError} If `key` is not at least 1 character long.
+     * @throws {Error} If `uploadId` is not provided.
+     * @throws {TypeError} If `options.maxParts` is not a `number`.
+     * @throws {RangeError} If `options.maxParts` is <= 0.
+     * @throws {TypeError} If `options.partNumberMarker` is not a `string`.
+     */
+    listParts(key: string, uploadId: string, options?: ListPartsOptions): Promise<ListPartsResult>;
     /**
      * Creates a new bucket on the S3 server.
      *
@@ -294,7 +335,7 @@ declare class S3Client {
      *
      * @throws {RangeError} If `maxKeys` is not between `1` and `1000`.
      */
-    list(options?: ListObjectsOptions): Promise<ListObjectsResponse>;
+    list(options?: ListObjectsOptions): Promise<ListObjectsResult>;
     /**
      * Uses [`DeleteObjects`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) to delete multiple objects in a single request.
      */
@@ -434,4 +475,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 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 };
+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 };

package/dist/index.js

@@ -324,7 +324,7 @@ var stream = Symbol("stream");
 var signedRequest = Symbol("signedRequest");
 var xmlParser2 = new XMLParser2({
   ignoreAttributes: true,
-  isArray: (_, jPath) => jPath === "ListMultipartUploadsResult.Upload" || jPath === "ListBucketResult.Contents" || jPath === "DeleteResult.Deleted" || jPath === "DeleteResult.Error"
+  isArray: (_, jPath) => jPath === "ListMultipartUploadsResult.Upload" || jPath === "ListBucketResult.Contents" || jPath === "ListPartsResult.Part" || jPath === "DeleteResult.Deleted" || jPath === "DeleteResult.Error"
 });
 var xmlBuilder = new XMLBuilder({
   attributeNamePrefix: "$",
@@ -524,28 +524,28 @@ var S3Client = class {
     let query = "uploads=";
     if (options.delimiter) {
       if (typeof options.delimiter !== "string") {
-        throw new TypeError("`delimiter` should be a `string`.");
+        throw new TypeError("`delimiter` must be a `string`.");
       }
       query += `&delimiter=${encodeURIComponent(options.delimiter)}`;
     }
     if (options.keyMarker) {
       if (typeof options.keyMarker !== "string") {
-        throw new TypeError("`keyMarker` should be a `string`.");
+        throw new TypeError("`keyMarker` must 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`.");
+        throw new TypeError("`maxUploads` must be a `number`.");
       }
       if (options.maxUploads < 1 || options.maxUploads > 1e3) {
-        throw new RangeError("`maxUploads` should be between 1 and 1000.");
+        throw new RangeError("`maxUploads` has to 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`.");
+        throw new TypeError("`prefix` must be a `string`.");
       }
       query += `&prefix=${encodeURIComponent(options.prefix)}`;
     }
@@ -667,6 +667,112 @@ var S3Client = class {
       checksumType: res.ChecksumType || void 0
     };
   }
+  /**
+   * @remarks Uses [`UploadPart`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html).
+   * @throws {RangeError} If `key` is not at least 1 character long.
+   * @throws {Error} If `uploadId` is not provided.
+   */
+  async uploadPart(key, uploadId, data, partNumber, options = {}) {
+    if (key.length < 1) {
+      throw new RangeError("`key` must be at least 1 character long.");
+    }
+    if (!uploadId) {
+      throw new Error("`uploadId` is required.");
+    }
+    if (!data) {
+      throw new Error("`data` is required.");
+    }
+    if (typeof partNumber !== "number" || partNumber <= 0) {
+      throw new Error("`partNumber` has to be a `number` which is >= 1.");
+    }
+    const response = await this[signedRequest](
+      "PUT",
+      key,
+      `partNumber=${partNumber}&uploadId=${encodeURIComponent(uploadId)}`,
+      data,
+      void 0,
+      void 0,
+      void 0,
+      ensureValidBucketName(options.bucket ?? this.#options.bucket),
+      options.signal
+    );
+    if (response.statusCode === 200) {
+      await response.body.dump();
+      const etag = response.headers.etag;
+      if (typeof etag !== "string" || etag.length === 0) {
+        throw new S3Error("Unknown", "", {
+          message: "Response did not contain an etag."
+        });
+      }
+      return {
+        partNumber,
+        etag
+      };
+    }
+    throw await getResponseError(response, "");
+  }
+  /**
+   * @remarks Uses [`ListParts`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html).
+   * @throws {RangeError} If `key` is not at least 1 character long.
+   * @throws {Error} If `uploadId` is not provided.
+   * @throws {TypeError} If `options.maxParts` is not a `number`.
+   * @throws {RangeError} If `options.maxParts` is <= 0.
+   * @throws {TypeError} If `options.partNumberMarker` is not a `string`.
+   */
+  async listParts(key, uploadId, options = {}) {
+    let query = "";
+    if (options.maxParts) {
+      if (typeof options.maxParts !== "number") {
+        throw new TypeError("`maxParts` must be a `number`.");
+      }
+      if (options.maxParts <= 0) {
+        throw new RangeError("`maxParts` must be >= 1.");
+      }
+      query += `&max-parts=${options.maxParts}`;
+    }
+    if (options.partNumberMarker) {
+      if (typeof options.partNumberMarker !== "string") {
+        throw new TypeError("`partNumberMarker` must be a `string`.");
+      }
+      query += `&part-number-marker=${encodeURIComponent(options.partNumberMarker)}`;
+    }
+    query += `&uploadId=${encodeURIComponent(uploadId)}`;
+    const response = await this[signedRequest](
+      "GET",
+      key,
+      // We always have a leading &, so we can slice the leading & away (this way, we have less conditionals on the hot path); see benchmark-operations.js
+      query.substring(1),
+      void 0,
+      void 0,
+      void 0,
+      void 0,
+      ensureValidBucketName(options.bucket ?? this.#options.bucket),
+      options?.signal
+    );
+    if (response.statusCode === 200) {
+      const text = await response.body.text();
+      const root = ensureParsedXml(text).ListPartsResult ?? {};
+      return {
+        bucket: root.Bucket,
+        key: root.Key,
+        uploadId: root.UploadId,
+        partNumberMarker: root.PartNumberMarker ?? void 0,
+        nextPartNumberMarker: root.NextPartNumberMarker ?? void 0,
+        maxParts: root.MaxParts ?? 1e3,
+        isTruncated: root.IsTruncated ?? false,
+        parts: (
+          // biome-ignore lint/suspicious/noExplicitAny: parsing code
+          root.Part?.map((part) => ({
+            etag: part.ETag,
+            lastModified: part.LastModified ? new Date(part.LastModified) : void 0,
+            partNumber: part.PartNumber ?? void 0,
+            size: part.Size ?? void 0
+          })) ?? []
+        )
+      };
+    }
+    throw await getResponseError(response, key);
+  }
   //#endregion
   //#region bucket operations
   /**
@@ -812,29 +918,29 @@ var S3Client = class {
     let query = "";
     if (typeof options.continuationToken !== "undefined") {
       if (typeof options.continuationToken !== "string") {
-        throw new TypeError("`continuationToken` should be a `string`.");
+        throw new TypeError("`continuationToken` must be a `string`.");
       }
       query += `continuation-token=${encodeURIComponent(options.continuationToken)}&`;
     }
     query += "list-type=2";
     if (typeof options.maxKeys !== "undefined") {
       if (typeof options.maxKeys !== "number") {
-        throw new TypeError("`maxKeys` should be a `number`.");
+        throw new TypeError("`maxKeys` must be a `number`.");
       }
       if (options.maxKeys < 1 || options.maxKeys > 1e3) {
-        throw new RangeError("`maxKeys` should be between 1 and 1000.");
+        throw new RangeError("`maxKeys` has to be between 1 and 1000.");
       }
       query += `&max-keys=${options.maxKeys}`;
     }
     if (options.prefix) {
       if (typeof options.prefix !== "string") {
-        throw new TypeError("`prefix` should be a `string`.");
+        throw new TypeError("`prefix` must be a `string`.");
       }
       query += `&prefix=${encodeURIComponent(options.prefix)}`;
     }
     if (typeof options.startAfter !== "undefined") {
       if (typeof options.startAfter !== "string") {
-        throw new TypeError("`startAfter` should be a `string`.");
+        throw new TypeError("`startAfter` must be a `string`.");
       }
       query += `&start-after=${encodeURIComponent(options.startAfter)}`;
     }

package/package.json

@@ -2,7 +2,7 @@
   "name": "lean-s3",
   "author": "Niklas Mollenhauer",
   "license": "MIT",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A server-side S3 API for the regular user.",
   "keywords": [
     "s3",
@@ -44,14 +44,15 @@
   },
   "dependencies": {
     "fast-xml-parser": "^5.2.5",
+    "i": "^0.3.7",
     "undici": "^7.10.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.0.0",
+    "@biomejs/biome": "2.0.0",
     "@testcontainers/localstack": "^11.0.3",
     "@testcontainers/minio": "^11.0.3",
     "@types/node": "^24.0.3",
-    "@typescript/native-preview": "^7.0.0-dev.20250619.1",
+    "@typescript/native-preview": "^7.0.0-dev.20250620.1",
     "expect": "^30.0.2",
     "lefthook": "^1.11.14",
     "tsup": "^8.5.0",