lean-s3 0.6.0 → 0.6.1

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,6 +42,7 @@ interface S3ClientOptions {
 type OverridableS3ClientOptions = Pick<S3ClientOptions, "region" | "bucket" | "endpoint">;
 type CreateFileInstanceOptions = {};
 type DeleteObjectsOptions = {
+    bucket?: string;
     signal?: AbortSignal;
 };
 interface S3FilePresignOptions {
@@ -274,19 +283,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 +304,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.
      *
@@ -347,7 +356,7 @@ declare class S3Client {
      * 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
@@ -373,7 +382,7 @@ declare class S3File {
     /**
      * @internal
      */
-    constructor(client: S3Client, path: string, start: number | undefined, end: number | undefined, contentType: string | undefined);
+    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.

package/dist/index.js

@@ -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,
@@ -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
@@ -952,7 +976,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 +1028,7 @@ var S3Client = class {
       },
       void 0,
       void 0,
-      this.#options.bucket,
+      ensureValidBucketName(options.bucket ?? this.#options.bucket),
       options.signal
     );
     if (response.statusCode === 200) {
@@ -1299,23 +1323,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);

package/package.json

@@ -2,7 +2,7 @@
   "name": "lean-s3",
   "author": "Niklas Mollenhauer",
   "license": "MIT",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "A server-side S3 API for the regular user.",
   "keywords": [
     "s3",