lean-s3 0.7.4 → 0.7.6

package/README.md

@@ -181,3 +181,13 @@ const client = new S3Client({
 ```
 
 Popular S3 provider missing? Open an issue or file a PR!
+
+## Tested On
+To ensure compability across various providers and self-hosted services, all tests are run on:
+- Amazon AWS S3
+- Hetzner Object Storage
+- Cloudflare R2
+- Garage
+- Minio
+- LocalStack
+- Ceph

package/dist/index.d.ts

@@ -226,6 +226,8 @@ type ListObjectsResult = {
     contents: readonly S3BucketEntry[];
 };
 type BucketCreationOptions = {
+    endpoint?: string;
+    region?: string;
     locationConstraint?: string;
     location?: BucketLocationInfo;
     info?: BucketInfo;
@@ -290,7 +292,8 @@ declare class S3Client {
      * @param  options The default options to use for the S3 client.
      */
     constructor(options: S3ClientOptions);
-    [kGetEffectiveParams](region: string | undefined | null, endpoint: string | undefined | null, bucket: string | undefined | null): [region: Region, endpoint: Endpoint, bucket: BucketName];
+    /** @internal */
+    [kGetEffectiveParams](options: OverridableS3ClientOptions): [region: Region, endpoint: Endpoint, bucket: BucketName];
     /**
      * Creates an S3File instance for the given path.
      *
@@ -445,7 +448,7 @@ 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>>;
+    [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

package/dist/index.js

@@ -319,29 +319,51 @@ function getAuthorizationHeader(keyCache, method, path, query, date, sortedSigne
 }
 
 // src/branded.ts
-function ensureValidBucketName(name) {
-  if (typeof name !== "string") {
-    throw new TypeError("`name` must be a `string`.");
+function ensureValidBucketName(bucket) {
+  if (typeof bucket !== "string") {
+    throw new TypeError("`bucket` is required and must be a `string`.");
   }
-  if (name.length < 3 || name.length > 63) {
-    throw new Error("`name` must be between 3 and 63 characters long.");
+  if (bucket.length < 3 || bucket.length > 63) {
+    throw new Error("`bucket` 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 (bucket.startsWith(".") || bucket.endsWith(".")) {
+    throw new Error("`bucket` must not start or end with a period (.)");
   }
-  if (!/^[a-z0-9.-]+$/.test(name)) {
+  if (!/^[a-z0-9.-]+$/.test(bucket)) {
     throw new Error(
-      "`name` can only contain lowercase letters, numbers, periods (.), and hyphens (-)."
+      "`bucket` can only contain lowercase letters, numbers, periods (.), and hyphens (-)."
     );
   }
-  if (name.includes("..")) {
-    throw new Error("`name` must not contain two adjacent periods (..)");
+  if (bucket.includes("..")) {
+    throw new Error("`bucket` must not contain two adjacent periods (..)");
   }
-  return name;
+  return bucket;
+}
+function ensureValidAccessKeyId(accessKeyId) {
+  if (typeof accessKeyId !== "string") {
+    throw new TypeError("`AccessKeyId` is required and must be a `string`.");
+  }
+  if (accessKeyId.length < 1) {
+    throw new RangeError("`AccessKeyId` must be at least 1 character long.");
+  }
+  return accessKeyId;
+}
+function ensureValidSecretAccessKey(secretAccessKey) {
+  if (typeof secretAccessKey !== "string") {
+    throw new TypeError(
+      "`SecretAccessKey` is required and must be a `string`."
+    );
+  }
+  if (secretAccessKey.length < 1) {
+    throw new RangeError(
+      "`SecretAccessKey` must be at least 1 character long."
+    );
+  }
+  return secretAccessKey;
 }
 function ensureValidPath(path) {
   if (typeof path !== "string") {
-    throw new TypeError("`path` must be a `string`.");
+    throw new TypeError("`path` is required and must be a `string`.");
   }
   if (path.length < 1) {
     throw new RangeError("`path` must be at least 1 character long.");
@@ -350,7 +372,7 @@ function ensureValidPath(path) {
 }
 function ensureValidEndpoint(endpoint) {
   if (typeof endpoint !== "string") {
-    throw new TypeError("`endpoint` must be a `string`.");
+    throw new TypeError("`endpoint` is required and must be a `string`.");
   }
   if (endpoint.length < 1) {
     throw new RangeError("`endpoint` must be at least 1 character long.");
@@ -359,7 +381,7 @@ function ensureValidEndpoint(endpoint) {
 }
 function ensureValidRegion(region) {
   if (typeof region !== "string") {
-    throw new TypeError("`region` must be a `string`.");
+    throw new TypeError("`region` is required and must be a `string`.");
   }
   if (region.length < 1) {
     throw new RangeError("`region` must be at least 1 character long.");
@@ -420,43 +442,21 @@ var S3Client = class {
     if (!options) {
       throw new Error("`options` is required.");
     }
-    const {
-      accessKeyId,
-      secretAccessKey,
-      endpoint,
-      region,
-      bucket,
-      sessionToken
-    } = options;
-    if (!accessKeyId || typeof accessKeyId !== "string") {
-      throw new Error("`accessKeyId` is required.");
-    }
-    if (!secretAccessKey || typeof secretAccessKey !== "string") {
-      throw new Error("`secretAccessKey` is required.");
-    }
-    if (!endpoint || typeof endpoint !== "string") {
-      throw new Error("`endpoint` is required.");
-    }
-    if (!region || typeof region !== "string") {
-      throw new Error("`region` is required.");
-    }
-    if (!bucket || typeof bucket !== "string") {
-      throw new Error("`bucket` is required.");
-    }
     this.#options = {
-      accessKeyId,
-      secretAccessKey,
+      accessKeyId: ensureValidAccessKeyId(options.accessKeyId),
+      secretAccessKey: ensureValidSecretAccessKey(options.secretAccessKey),
       endpoint: ensureValidEndpoint(options.endpoint),
       region: ensureValidRegion(options.region),
       bucket: ensureValidBucketName(options.bucket),
-      sessionToken
+      sessionToken: options.sessionToken
     };
   }
-  [kGetEffectiveParams](region, endpoint, bucket) {
+  /** @internal */
+  [kGetEffectiveParams](options) {
     return [
-      ensureValidRegion(region ?? this.#options.region),
-      ensureValidEndpoint(endpoint ?? this.#options.endpoint),
-      ensureValidBucketName(bucket ?? this.#options.bucket)
+      options.region ? ensureValidRegion(options.region) : this.#options.region,
+      options.endpoint ? ensureValidEndpoint(options.endpoint) : this.#options.endpoint,
+      options.bucket ? ensureValidBucketName(options.bucket) : this.#options.bucket
     ];
   }
   /**
@@ -535,11 +535,7 @@ var S3Client = class {
     }
     const method = options.method ?? "GET";
     const contentType = options.type ?? void 0;
-    const [region, endpoint, bucket] = this[kGetEffectiveParams](
-      options.region,
-      options.endpoint,
-      options.bucket
-    );
+    const [region, endpoint, bucket] = this[kGetEffectiveParams](options);
     const responseOptions = options.response;
     const contentDisposition = responseOptions?.contentDisposition;
     const responseContentDisposition = contentDisposition ? getContentDispositionHeader(contentDisposition) : void 0;
@@ -595,8 +591,6 @@ var S3Client = class {
   }
   //#region multipart uploads
   async createMultipartUpload(key, options = {}) {
-    if (key.length < 1) {
-    }
     const response = await this[kSignedRequest](
       this.#options.region,
       this.#options.endpoint,
@@ -895,7 +889,7 @@ var S3Client = class {
    * @throws {S3Error} If the bucket could not be created, e.g. if it already exists.
    * @remarks Uses [`CreateBucket`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html)
    */
-  async createBucket(name, options) {
+  async createBucket(name, options = {}) {
     let body;
     if (options) {
       const location = options.location && (options.location.name || options.location.type) ? {
@@ -917,8 +911,8 @@ var S3Client = class {
     }
     const additionalSignedHeaders = body ? { "content-md5": md5Base64(body) } : void 0;
     const response = await this[kSignedRequest](
-      this.#options.region,
-      this.#options.endpoint,
+      options.region ? ensureValidRegion(options.region) : this.#options.region,
+      options.endpoint ? ensureValidEndpoint(options.endpoint) : this.#options.endpoint,
       ensureValidBucketName(name),
       "PUT",
       "",
@@ -927,7 +921,7 @@ var S3Client = class {
       additionalSignedHeaders,
       void 0,
       void 0,
-      options?.signal
+      options.signal
     );
     if (400 <= response.statusCode && response.statusCode < 500) {
       throw await getResponseError(response, "");
@@ -1254,7 +1248,7 @@ var S3Client = class {
    * TODO: Maybe move this into a separate free function?
    * @internal
    */
-  async [kSignedRequest](region, endpoint, bucket, method, pathWithoutBucket, query, body, additionalSignedHeaders, additionalUnsignedHeaders, contentHash, signal = void 0) {
+  async [kSignedRequest](region, endpoint, bucket, method, pathWithoutBucket, query, body, additionalSignedHeaders, additionalUnsignedHeaders, contentHash, signal) {
     const url = buildRequestUrl(endpoint, bucket, region, pathWithoutBucket);
     if (query) {
       url.search = query;
@@ -1567,11 +1561,7 @@ var S3File = class _S3File {
    * @throws {Error} If the server returns an invalid response.
    */
   async stat(options = {}) {
-    const [region, endpoint, bucket] = this.#client[kGetEffectiveParams](
-      options.region,
-      options.endpoint,
-      options.bucket
-    );
+    const [region, endpoint, bucket] = this.#client[kGetEffectiveParams](options);
     const response = await this.#client[kSignedRequest](
       region,
       endpoint,
@@ -1605,11 +1595,7 @@ var S3File = class _S3File {
    * @remarks Uses [`HeadObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html).
    */
   async exists(options = {}) {
-    const [region, endpoint, bucket] = this.#client[kGetEffectiveParams](
-      options.region,
-      options.endpoint,
-      options.bucket
-    );
+    const [region, endpoint, bucket] = this.#client[kGetEffectiveParams](options);
     const response = await this.#client[kSignedRequest](
       region,
       endpoint,
@@ -1657,11 +1643,7 @@ var S3File = class _S3File {
    * ```
    */
   async delete(options = {}) {
-    const [region, endpoint, bucket] = this.#client[kGetEffectiveParams](
-      options.region,
-      options.endpoint,
-      options.bucket
-    );
+    const [region, endpoint, bucket] = this.#client[kGetEffectiveParams](options);
     const response = await this.#client[kSignedRequest](
       region,
       endpoint,
@@ -1757,15 +1739,6 @@ var S3File = class _S3File {
       signal
     );
   }
-  /*
-  // Future API?
-  setTags(): Promise<void> {
-  	throw new Error("Not implemented");
-  }
-  getTags(): Promise<unknown> {
-  	throw new Error("Not implemented");
-  }
-  */
 };
 export {
   S3BucketEntry,

package/package.json

@@ -2,7 +2,7 @@
   "name": "lean-s3",
   "author": "Niklas Mollenhauer",
   "license": "MIT",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "description": "A server-side S3 API for the regular user.",
   "keywords": [
     "s3",
@@ -34,8 +34,8 @@
   "type": "module",
   "scripts": {
     "build": "tsup",
-    "test": "tsgo && tsx --test src/*.test.ts",
-    "test:integration": "tsgo && tsx --test src/test.integration.ts",
+    "test": "tsgo && tsx --test src/*.test.ts src/test/*.test.ts",
+    "test:integration": "tsgo && tsx --test src/test/test.integration.ts",
     "ci": "biome ci ./src",
     "docs": "typedoc",
     "lint": "biome lint ./src",
@@ -50,16 +50,16 @@
     "@biomejs/biome": "2.1.1",
     "@testcontainers/localstack": "^11.2.1",
     "@testcontainers/minio": "^11.2.1",
-    "@types/node": "^24.0.10",
-    "@typescript/native-preview": "^7.0.0-dev.20250708.1",
+    "@types/node": "^24.0.13",
+    "@typescript/native-preview": "^7.0.0-dev.20250711.1",
     "expect": "^30.0.4",
-    "lefthook": "^1.12.0",
+    "lefthook": "^1.12.2",
     "testcontainers": "^11.2.1",
     "tsup": "^8.5.0",
     "tsx": "^4.20.3",
     "typedoc": "^0.28.7"
   },
   "engines": {
-    "node": "^20.19.2 || ^22.16.0 || ^24.2.0"
+    "node": "^20.19.3 || ^22.17.0 || ^24.4.0"
   }
 }