lean-s3 0.7.6 → 0.7.8

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 import { Readable } from 'node:stream';
-import * as stream_web from 'stream/web';
 import { Dispatcher } from 'undici';
 
 /**
@@ -35,10 +34,41 @@ declare const kStream: unique symbol;
 declare const kSignedRequest: unique symbol;
 declare const kGetEffectiveParams: unique symbol;
 interface S3ClientOptions {
+    /**
+     * The name of the bucket to operate on.
+     * Different S3 providers have different limitations here. All of them require:
+     * - Must be at least 3 characters long
+     * - Must be at most 63 characters long
+     * - Must not start or end with a period (.)
+     * - Must not contain two adjacent periods (..)
+     * - Must only contain lowercase letters, numbers, periods (.), and hyphens (-).
+     */
     bucket: string;
+    /**
+     * The region of the S3 bucket.
+     * This value is required for all S3 proviers. However, some providers don't care about its actual value.
+     */
     region: string;
+    /**
+     * The endpoint of the S3 service.
+     * This is required for all S3 providers.
+     *
+     * The endpoint may contain placeholders for region and bucket, which will be replaced internally with the actual values on use.
+     *
+     * For example, `https://{bucket}.s3.{region}.example.com` will be replaced with `https://my-bucket.s3.us-west-2.example.com` if the bucket is `my-bucket` and the region is `us-west-2`.
+     *
+     * If the endpoint does not contain a placeholder for the bucket, it will be appended to the path of the endpoint.
+     */
     endpoint: string;
+    /**
+     * The access key ID to use for authentication.
+     * This is required for all S3 providers.
+     */
     accessKeyId: string;
+    /**
+     * The secret access key to use for authentication.
+     * This is required for all S3 providers.
+     */
     secretAccessKey: string;
     sessionToken?: string;
 }
@@ -48,7 +78,9 @@ type CreateFileInstanceOptions = {
     type?: string;
 };
 type DeleteObjectsOptions = {
+    /** Set this to override the {@link S3ClientOptions#bucket} that was passed on creation of the {@link S3Client}. */
     bucket?: string;
+    /** Signal to abort the request. */
     signal?: AbortSignal;
 };
 type DeleteObjectsResult = {
@@ -93,31 +125,38 @@ interface S3FilePresignOptions extends OverridableS3ClientOptions {
     };
 }
 type ListObjectsOptions = {
+    /** Set this to override the {@link S3ClientOptions#bucket} that was passed on creation of the {@link S3Client}. */
     bucket?: string;
     prefix?: string;
     maxKeys?: number;
     delimiter?: string;
     startAfter?: string;
     continuationToken?: string;
+    /** Signal to abort the request. */
     signal?: AbortSignal;
 };
 type ListObjectsIteratingOptions = {
+    /** Set this to override the {@link S3ClientOptions#bucket} that was passed on creation of the {@link S3Client}. */
     bucket?: string;
     prefix?: string;
     startAfter?: string;
+    /** Signal to abort the request. */
     signal?: AbortSignal;
     internalPageSize?: number;
 };
 type ListMultipartUploadsOptions = {
+    /** Set this to override the {@link S3ClientOptions#bucket} that was passed on creation of the {@link S3Client}. */
     bucket?: string;
     delimiter?: string;
     keyMarker?: string;
     maxUploads?: number;
     prefix?: string;
     uploadIdMarker?: string;
+    /** Signal to abort the request. */
     signal?: AbortSignal;
 };
 type ListMultipartUploadsResult = {
+    /** Name of the bucket the operation was used upon. */
     bucket?: string;
     keyMarker?: string;
     uploadIdMarker?: string;
@@ -145,32 +184,50 @@ type MultipartUpload = {
     uploadId?: string;
 };
 type CreateMultipartUploadOptions = {
+    /** Set this to override the {@link S3ClientOptions#bucket} that was passed on creation of the {@link S3Client}. */
     bucket?: string;
+    /** Signal to abort the request. */
     signal?: AbortSignal;
 };
 type CreateMultipartUploadResult = {
+    /** Name of the bucket the multipart upload was created in. */
     bucket: string;
     key: string;
     uploadId: string;
 };
 type AbortMultipartUploadOptions = {
+    /** Set this to override the {@link S3ClientOptions#bucket} that was passed on creation of the {@link S3Client}. */
     bucket?: string;
+    /** Signal to abort the request. */
     signal?: AbortSignal;
 };
 type CompleteMultipartUploadOptions = {
+    /** Set this to override the {@link S3ClientOptions#bucket} that was passed on creation of the {@link S3Client}. */
     bucket?: string;
+    /** Signal to abort the request. */
     signal?: AbortSignal;
 };
 type CompleteMultipartUploadResult = {
+    /** The URI that identifies the newly created object. */
     location?: string;
+    /** Name of the bucket the multipart upload was created in. */
     bucket?: string;
     key?: string;
     etag?: string;
+    /** The Base64 encoded, 32-bit `CRC32` checksum of the part. This checksum is present if the multipart upload request was created with the `CRC32` checksum algorithm. */
     checksumCRC32?: string;
+    /** The Base64 encoded, 32-bit `CRC32C` checksum of the part. This checksum is present if the multipart upload request was created with the `CRC32C` checksum algorithm. */
     checksumCRC32C?: string;
+    /** The Base64 encoded, 64-bit `CRC64NVME` checksum of the part. This checksum is present if the multipart upload request was created with the `CRC64NVME` checksum algorithm. */
     checksumCRC64NVME?: string;
+    /** The Base64 encoded, 160-bit `SHA1` checksum of the part. This checksum is present if the multipart upload request was created with the `SHA1` checksum algorithm. */
     checksumSHA1?: string;
+    /** The Base64 encoded, 256-bit `SHA256` checksum of the part. This checksum is present if the multipart upload request was created with the `SHA256` checksum algorithm. */
     checksumSHA256?: string;
+    /**
+     * The checksum type, which determines how part-level checksums are combined to create an object-level checksum for multipart objects.
+     * You can use this header as a data integrity check to verify that the checksum type that is received is the same checksum type that was specified during the `CreateMultipartUpload` request.
+     */
     checksumType?: ChecksumType;
 };
 type MultipartUploadPart = {
@@ -178,7 +235,9 @@ type MultipartUploadPart = {
     etag: string;
 };
 type UploadPartOptions = {
+    /** Set this to override the {@link S3ClientOptions#bucket} that was passed on creation of the {@link S3Client}. */
     bucket?: string;
+    /** Signal to abort the request. */
     signal?: AbortSignal;
 };
 type UploadPartResult = {
@@ -188,10 +247,13 @@ type UploadPartResult = {
 type ListPartsOptions = {
     maxParts?: number;
     partNumberMarker?: string;
+    /** Set this to override the {@link S3ClientOptions#bucket} that was passed on creation of the {@link S3Client}. */
     bucket?: string;
+    /** Signal to abort the request. */
     signal?: AbortSignal;
 };
 type ListPartsResult = {
+    /** Name of the bucket. */
     bucket: string;
     key: string;
     uploadId: string;
@@ -200,10 +262,15 @@ type ListPartsResult = {
     maxParts?: number;
     isTruncated: boolean;
     parts: Array<{
+        /** The Base64 encoded, 32-bit `CRC32` checksum of the part. This checksum is present if the multipart upload request was created with the `CRC32` checksum algorithm. */
         checksumCRC32?: string;
+        /** The Base64 encoded, 32-bit `CRC32C` checksum of the part. This checksum is present if the multipart upload request was created with the `CRC32C` checksum algorithm. */
         checksumCRC32C?: string;
+        /** The Base64 encoded, 64-bit `CRC64NVME` checksum of the part. This checksum is present if the multipart upload request was created with the `CRC64NVME` checksum algorithm. */
         checksumCRC64NVME?: string;
+        /** The Base64 encoded, 160-bit `SHA1` checksum of the part. This checksum is present if the multipart upload request was created with the `SHA1` checksum algorithm. */
         checksumSHA1?: string;
+        /** The Base64 encoded, 256-bit `SHA256` checksum of the part. This checksum is present if the multipart upload request was created with the `SHA256` checksum algorithm. */
         checksumSHA256?: string;
         etag: string;
         lastModified: Date;
@@ -226,17 +293,22 @@ type ListObjectsResult = {
     contents: readonly S3BucketEntry[];
 };
 type BucketCreationOptions = {
+    /** Set this to override the {@link S3ClientOptions#endpoint} that was passed on creation of the {@link S3Client}. */
     endpoint?: string;
+    /** Set this to override the {@link S3ClientOptions#region} that was passed on creation of the {@link S3Client}. */
     region?: string;
     locationConstraint?: string;
     location?: BucketLocationInfo;
     info?: BucketInfo;
+    /** Signal to abort the request. */
     signal?: AbortSignal;
 };
 type BucketDeletionOptions = {
+    /** Signal to abort the request. */
     signal?: AbortSignal;
 };
 type BucketExistsOptions = {
+    /** Signal to abort the request. */
     signal?: AbortSignal;
 };
 type BucketCorsRules = readonly BucketCorsRule[];
@@ -254,15 +326,21 @@ type BucketCorsRule = {
     maxAgeSeconds?: number;
 };
 type PutBucketCorsOptions = {
+    /** The CORS rules to set on the bucket. Set this to override the {@link S3ClientOptions#bucket} that was passed on creation of the {@link S3Client}. */
     bucket?: string;
+    /** Signal to abort the request. */
     signal?: AbortSignal;
 };
 type DeleteBucketCorsOptions = {
+    /** The name of the bucket to delete the CORS configuration for. Set this to override the {@link S3ClientOptions#bucket} that was passed on creation of the {@link S3Client}. */
     bucket?: string;
+    /** Signal to abort the request. */
     signal?: AbortSignal;
 };
 type GetBucketCorsOptions = {
+    /** The name of the bucket to get the CORS configuration for. Set this to override the {@link S3ClientOptions#bucket} that was passed on creation of the {@link S3Client}. */
     bucket?: string;
+    /** Signal to abort the request. */
     signal?: AbortSignal;
 };
 type GetBucketCorsResult = {
@@ -377,7 +455,7 @@ declare class S3Client {
      * @throws {RangeError} If `key` is not at least 1 character long.
      * @throws {Error} If `uploadId` is not provided.
      */
-    uploadPart(path: string, uploadId: string, data: UndiciBodyInit, partNumber: number, options?: UploadPartOptions): Promise<UploadPartResult>;
+    uploadPart(path: string, uploadId: string, data: string | Buffer | Uint8Array | Readable, 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.
@@ -448,16 +526,13 @@ declare class S3Client {
      * TODO: Maybe move this into a separate free function?
      * @internal
      */
-    [kSignedRequest](region: Region, endpoint: Endpoint, bucket: BucketName, method: HttpMethod, pathWithoutBucket: ObjectKey, query: string | undefined, body: UndiciBodyInit | undefined, additionalSignedHeaders: Record<string, string> | undefined, additionalUnsignedHeaders: Record<string, string> | undefined, contentHash: Buffer | undefined, signal: AbortSignal | undefined): Promise<Dispatcher.ResponseData<null>>;
-    /**
-     * @internal
-     * @param {import("./index.d.ts").UndiciBodyInit} data TODO
-     */
-    [kWrite](path: ObjectKey, data: UndiciBodyInit, contentType: string, contentLength: number | undefined, contentHash: Buffer | undefined, rageStart: number | undefined, rangeEndExclusive: number | undefined, signal?: AbortSignal | undefined): Promise<void>;
+    [kSignedRequest](region: Region, endpoint: Endpoint, bucket: BucketName, method: HttpMethod, pathWithoutBucket: ObjectKey, query: string | undefined, body: string | Buffer | Uint8Array | Readable | undefined, additionalSignedHeaders: Record<string, string> | undefined, additionalUnsignedHeaders: Record<string, string> | undefined, contentHash: Buffer | undefined, signal: AbortSignal | undefined): Promise<Dispatcher.ResponseData<null>>;
+    /** @internal */
+    [kWrite](path: ObjectKey, data: string | Buffer | Uint8Array | Readable, contentType: string, contentLength: number | undefined, contentHash: Buffer | undefined, rageStart: number | undefined, rangeEndExclusive: number | undefined, signal?: AbortSignal | undefined): Promise<void>;
     /**
      * @internal
      */
-    [kStream](path: ObjectKey, contentHash: Buffer | undefined, rageStart: number | undefined, rangeEndExclusive: number | undefined): stream_web.ReadableStream<Uint8Array<ArrayBufferLike>>;
+    [kStream](path: ObjectKey, contentHash: Buffer | undefined, rageStart: number | undefined, rangeEndExclusive: number | undefined): ReadableStream<Uint8Array>;
 }
 
 declare class S3Stat {
@@ -469,10 +544,6 @@ 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 */
@@ -533,7 +604,6 @@ declare class S3File {
     arrayBuffer(): Promise<ArrayBuffer>;
     text(): Promise<string>;
     blob(): Promise<Blob>;
-    /** @returns {ReadableStream<Uint8Array>} */
     stream(): ReadableStream<Uint8Array>;
     /**
      * @param {ByteSource} data
@@ -543,14 +613,23 @@ declare class S3File {
     write(data: ByteSource, options?: S3FileWriteOptions): Promise<void>;
 }
 interface S3FileDeleteOptions extends OverridableS3ClientOptions {
+    /** Signal to abort the request. */
     signal?: AbortSignal;
 }
 interface S3StatOptions extends OverridableS3ClientOptions {
+    /** Signal to abort the request. */
     signal?: AbortSignal;
 }
 interface S3FileExistsOptions extends OverridableS3ClientOptions {
+    /** Signal to abort the request. */
     signal?: AbortSignal;
 }
+type S3FileWriteOptions = {
+    /** Content-Type of the file. */
+    type?: string;
+    /** Signal to abort the request. */
+    signal?: AbortSignal;
+};
 
 declare class S3Error extends Error {
     readonly code: string;
@@ -573,9 +652,7 @@ type ChecksumAlgorithm = "CRC32" | "CRC32C" | "CRC64NVME" | "SHA1" | "SHA256";
 type ChecksumType = "COMPOSITE" | "FULL_OBJECT";
 type PresignableHttpMethod = "GET" | "DELETE" | "PUT" | "HEAD";
 type HttpMethod = PresignableHttpMethod | "POST";
-/** Body values supported by undici. */
-type UndiciBodyInit = string | Buffer | Uint8Array | Readable;
-type ByteSource = UndiciBodyInit | Blob;
+type ByteSource = string | Buffer | Uint8Array | Readable | Blob;
 /**
  * Implements [LocationInfo](https://docs.aws.amazon.com/AmazonS3/latest/API/API_LocationInfo.html)
  */
@@ -602,4 +679,4 @@ type AttachmentContentDisposition = {
     filename?: string;
 };
 
-export { type AbortMultipartUploadOptions, type Acl, type AttachmentContentDisposition, 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 ContentDisposition, type CreateFileInstanceOptions, type CreateMultipartUploadOptions, type CreateMultipartUploadResult, type DeleteBucketCorsOptions, type DeleteObjectsError, type DeleteObjectsOptions, type DeleteObjectsResult, type GetBucketCorsOptions, type GetBucketCorsResult, type HttpMethod, type InlineContentDisposition, 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 };
+export { type AbortMultipartUploadOptions, type Acl, type AttachmentContentDisposition, 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 ContentDisposition, type CreateFileInstanceOptions, type CreateMultipartUploadOptions, type CreateMultipartUploadResult, type DeleteBucketCorsOptions, type DeleteObjectsError, type DeleteObjectsOptions, type DeleteObjectsResult, type GetBucketCorsOptions, type GetBucketCorsResult, type HttpMethod, type InlineContentDisposition, 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 UploadPartOptions, type UploadPartResult };

package/dist/index.js

@@ -1293,10 +1293,7 @@ var S3Client = class {
       });
     }
   }
-  /**
-   * @internal
-   * @param {import("./index.d.ts").UndiciBodyInit} data TODO
-   */
+  /** @internal */
   async [kWrite](path, data, contentType, contentLength, contentHash, rageStart, rangeEndExclusive, signal = void 0) {
     const bucket = this.#options.bucket;
     const endpoint = this.#options.endpoint;
@@ -1363,7 +1360,6 @@ var S3Client = class {
     const contentHashStr = contentHash?.toString("hex") ?? unsignedPayload;
     const headersToBeSigned = prepareHeadersForSigning({
       "amz-sdk-invocation-id": crypto.randomUUID(),
-      // TODO: Maybe support retries and do "amz-sdk-request": attempt=1; max=3
       host: url.host,
       range,
       // Hetzner doesnt care if the x-amz-content-sha256 header is missing, R2 requires it to be present
@@ -1683,7 +1679,6 @@ var S3File = class _S3File {
       headers: { "Content-Type": this.#contentType }
     }).blob();
   }
-  /** @returns {ReadableStream<Uint8Array>} */
   stream() {
     return this.#client[kStream](this.#path, void 0, this.#start, this.#end);
   }
@@ -1726,7 +1721,6 @@ var S3File = class _S3File {
    * @returns {Promise<void>}
    */
   async write(data, options = {}) {
-    const signal = void 0;
     const [bytes, length, hash] = await this.#transformData(data);
     return await this.#client[kWrite](
       this.#path,
@@ -1736,7 +1730,7 @@ var S3File = class _S3File {
       hash,
       this.#start,
       this.#end,
-      signal
+      options.signal
     );
   }
 };

package/package.json

@@ -2,7 +2,7 @@
   "name": "lean-s3",
   "author": "Niklas Mollenhauer",
   "license": "MIT",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "description": "A server-side S3 API for the regular user.",
   "keywords": [
     "s3",
@@ -44,17 +44,17 @@
   },
   "dependencies": {
     "fast-xml-parser": "^5.2.5",
-    "undici": "^7.11.0"
+    "undici": "^7.12.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.1.1",
-    "@testcontainers/localstack": "^11.2.1",
-    "@testcontainers/minio": "^11.2.1",
-    "@types/node": "^24.0.13",
-    "@typescript/native-preview": "^7.0.0-dev.20250711.1",
-    "expect": "^30.0.4",
+    "@biomejs/biome": "2.1.2",
+    "@testcontainers/localstack": "^11.3.2",
+    "@testcontainers/minio": "^11.3.2",
+    "@types/node": "^24.1.0",
+    "@typescript/native-preview": "^7.0.0-dev.20250723.1",
+    "expect": "^30.0.5",
     "lefthook": "^1.12.2",
-    "testcontainers": "^11.2.1",
+    "testcontainers": "^11.3.2",
     "tsup": "^8.5.0",
     "tsx": "^4.20.3",
     "typedoc": "^0.28.7"