lean-s3 0.6.0 → 0.6.2

package/dist/index.d.ts

@@ -20,6 +20,14 @@ declare class S3BucketEntry {
     static parse(source: any): S3BucketEntry;
 }
 
+declare const __brand: unique symbol;
+type Brand<B> = {
+    [__brand]: B;
+};
+type Branded<T, B> = T & Brand<B>;
+type BucketName = Branded<string, "BucketName">;
+type ObjectKey = Branded<string, "ObjectKey">;
+
 declare const write: unique symbol;
 declare const stream: unique symbol;
 declare const signedRequest: unique symbol;
@@ -34,8 +42,18 @@ interface S3ClientOptions {
 type OverridableS3ClientOptions = Pick<S3ClientOptions, "region" | "bucket" | "endpoint">;
 type CreateFileInstanceOptions = {};
 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. */
@@ -49,6 +67,7 @@ type ListObjectsOptions = {
     bucket?: string;
     prefix?: string;
     maxKeys?: number;
+    delimiter?: string;
     startAfter?: string;
     continuationToken?: string;
     signal?: AbortSignal;
@@ -274,19 +293,19 @@ declare class S3Client {
      * @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>;
+    abortMultipartUpload(path: 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<CompleteMultipartUploadResult>;
+    completeMultipartUpload(path: 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>;
+    uploadPart(path: 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.
@@ -295,7 +314,7 @@ declare class S3Client {
      * @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>;
+    listParts(path: string, uploadId: string, options?: ListPartsOptions): Promise<ListPartsResult>;
     /**
      * Creates a new bucket on the S3 server.
      *
@@ -339,15 +358,13 @@ 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?
      * @internal
      */
-    [signedRequest](method: HttpMethod, pathWithoutBucket: string, query: string | undefined, body: UndiciBodyInit | undefined, additionalSignedHeaders: Record<string, string> | undefined, additionalUnsignedHeaders: Record<string, string> | undefined, contentHash: Buffer | undefined, bucket: string | undefined, signal?: AbortSignal | undefined): Promise<Dispatcher.ResponseData<null>>;
+    [signedRequest](method: HttpMethod, pathWithoutBucket: ObjectKey, query: string | undefined, body: UndiciBodyInit | undefined, additionalSignedHeaders: Record<string, string> | undefined, additionalUnsignedHeaders: Record<string, string> | undefined, contentHash: Buffer | undefined, bucket: BucketName | undefined, signal?: AbortSignal | undefined): Promise<Dispatcher.ResponseData<null>>;
     /**
      * @internal
      * @param {import("./index.d.ts").UndiciBodyInit} data TODO
@@ -370,10 +387,8 @@ declare class S3Stat {
 
 declare class S3File {
     #private;
-    /**
-     * @internal
-     */
-    constructor(client: S3Client, path: string, start: number | undefined, end: number | undefined, contentType: string | undefined);
+    /** @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;
     /**
      *  Get the stat of a file in the bucket. Uses `HEAD` request to check existence.
@@ -382,13 +397,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.
      *
@@ -400,18 +415,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>;
@@ -475,4 +490,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 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 };

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) {
@@ -318,6 +318,34 @@ function getAuthorizationHeader(keyCache, method, path, query, date, sortedSigne
   return `AWS4-HMAC-SHA256 Credential=${credentialSpec}, SignedHeaders=${signedHeadersSpec}, Signature=${signature}`;
 }
 
+// src/branded.ts
+function ensureValidBucketName(name) {
+  if (name.length < 3 || name.length > 63) {
+    throw new Error("`name` must be between 3 and 63 characters long.");
+  }
+  if (name.startsWith(".") || name.endsWith(".")) {
+    throw new Error("`name` must not start or end with a period (.)");
+  }
+  if (!/^[a-z0-9.-]+$/.test(name)) {
+    throw new Error(
+      "`name` can only contain lowercase letters, numbers, periods (.), and hyphens (-)."
+    );
+  }
+  if (name.includes("..")) {
+    throw new Error("`name` must not contain two adjacent periods (..)");
+  }
+  return name;
+}
+function ensureValidPath(path) {
+  if (typeof path !== "string") {
+    throw new TypeError("`path` must be a `string`.");
+  }
+  if (path.length < 1) {
+    throw new RangeError("`path` must be at least 1 character long.");
+  }
+  return path;
+}
+
 // src/S3Client.ts
 var write = Symbol("write");
 var stream = Symbol("stream");
@@ -412,7 +440,13 @@ var S3Client = class {
    * ```
    */
   file(path, _options) {
-    return new S3File(this, path, void 0, void 0, void 0);
+    return new S3File(
+      this,
+      ensureValidPath(path),
+      void 0,
+      void 0,
+      void 0
+    );
   }
   /**
    * Generate a presigned URL for temporary access to a file.
@@ -489,11 +523,10 @@ var S3Client = class {
   //#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,
+      ensureValidPath(key),
       "uploads=",
       void 0,
       void 0,
@@ -596,16 +629,13 @@ var S3Client = class {
    * @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.");
-    }
+  async abortMultipartUpload(path, uploadId, options = {}) {
     if (!uploadId) {
       throw new Error("`uploadId` is required.");
     }
     const response = await this[signedRequest](
       "DELETE",
-      key,
+      ensureValidPath(path),
       `uploadId=${encodeURIComponent(uploadId)}`,
       void 0,
       void 0,
@@ -615,7 +645,7 @@ var S3Client = class {
       options.signal
     );
     if (response.statusCode !== 204) {
-      throw await getResponseError(response, key);
+      throw await getResponseError(response, path);
     }
   }
   /**
@@ -623,10 +653,7 @@ var S3Client = class {
    * @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.");
-    }
+  async completeMultipartUpload(path, uploadId, parts, options = {}) {
     if (!uploadId) {
       throw new Error("`uploadId` is required.");
     }
@@ -640,7 +667,7 @@ var S3Client = class {
     });
     const response = await this[signedRequest](
       "POST",
-      key,
+      ensureValidPath(path),
       `uploadId=${encodeURIComponent(uploadId)}`,
       body,
       void 0,
@@ -650,7 +677,7 @@ var S3Client = class {
       options.signal
     );
     if (response.statusCode !== 200) {
-      throw await getResponseError(response, key);
+      throw await getResponseError(response, path);
     }
     const text = await response.body.text();
     const res = ensureParsedXml(text).CompleteMultipartUploadResult ?? {};
@@ -672,10 +699,7 @@ var S3Client = class {
    * @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.");
-    }
+  async uploadPart(path, uploadId, data, partNumber, options = {}) {
     if (!uploadId) {
       throw new Error("`uploadId` is required.");
     }
@@ -687,7 +711,7 @@ var S3Client = class {
     }
     const response = await this[signedRequest](
       "PUT",
-      key,
+      ensureValidPath(path),
       `partNumber=${partNumber}&uploadId=${encodeURIComponent(uploadId)}`,
       data,
       void 0,
@@ -697,7 +721,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", "", {
@@ -719,7 +743,7 @@ var S3Client = class {
    * @throws {RangeError} If `options.maxParts` is <= 0.
    * @throws {TypeError} If `options.partNumberMarker` is not a `string`.
    */
-  async listParts(key, uploadId, options = {}) {
+  async listParts(path, uploadId, options = {}) {
     let query = "";
     if (options.maxParts) {
       if (typeof options.maxParts !== "number") {
@@ -739,7 +763,7 @@ var S3Client = class {
     query += `&uploadId=${encodeURIComponent(uploadId)}`;
     const response = await this[signedRequest](
       "GET",
-      key,
+      ensureValidPath(path),
       // 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,
@@ -771,7 +795,7 @@ var S3Client = class {
         )
       };
     }
-    throw await getResponseError(response, key);
+    throw await getResponseError(response, path);
   }
   //#endregion
   //#region bucket operations
@@ -824,7 +848,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;
     }
@@ -852,7 +876,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;
     }
@@ -879,7 +903,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;
     }
@@ -932,6 +956,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`.");
@@ -952,7 +982,7 @@ var S3Client = class {
       void 0,
       void 0,
       void 0,
-      options.bucket ?? this.#options.bucket,
+      ensureValidBucketName(options.bucket ?? this.#options.bucket),
       options.signal
     );
     if (response.statusCode !== 200) {
@@ -1004,7 +1034,7 @@ var S3Client = class {
       },
       void 0,
       void 0,
-      this.#options.bucket,
+      ensureValidBucketName(options.bucket ?? this.#options.bucket),
       options.signal
     );
     if (response.statusCode === 200) {
@@ -1027,7 +1057,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, "");
@@ -1299,23 +1329,6 @@ function buildSearchParams(amzCredential, date, expiresIn, headerList, contentHa
   }
   return res;
 }
-function ensureValidBucketName(name) {
-  if (name.length < 3 || name.length > 63) {
-    throw new Error("`name` must be between 3 and 63 characters long.");
-  }
-  if (name.startsWith(".") || name.endsWith(".")) {
-    throw new Error("`name` must not start or end with a period (.)");
-  }
-  if (!/^[a-z0-9.-]+$/.test(name)) {
-    throw new Error(
-      "`name` can only contain lowercase letters, numbers, periods (.), and hyphens (-)."
-    );
-  }
-  if (name.includes("..")) {
-    throw new Error("`name` must not contain two adjacent periods (..)");
-  }
-  return name;
-}
 function ensureParsedXml(text) {
   try {
     const r = xmlParser2.parse(text);
@@ -1345,9 +1358,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`.");
@@ -1378,7 +1389,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,
@@ -1388,9 +1399,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) {
@@ -1409,9 +1420,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,
@@ -1421,9 +1430,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;
     }
@@ -1445,18 +1454,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,
@@ -1466,10 +1475,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);
@@ -1549,10 +1558,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.0",
+  "version": "0.6.2",
   "description": "A server-side S3 API for the regular user.",
   "keywords": [
     "s3",
@@ -44,16 +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.5",
     "@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.4",
+    "@typescript/native-preview": "^7.0.0-dev.20250626.1",
+    "expect": "^30.0.3",
     "lefthook": "^1.11.14",
     "tsup": "^8.5.0",
     "tsx": "^4.20.3",