lean-s3 0.8.12 → 0.9.0

package/README.md

@@ -189,6 +189,19 @@ const client = new S3Client({
 });
 ```
 
+### Backblaze B2
+```js
+// Docs: https://www.backblaze.com/apidocs/introduction-to-the-s3-compatible-api
+const client = new S3Client({
+    // keep {region} placeholders (it is used internally).
+    endpoint: "https://s3.{region}.backblazeb2.com",
+    region: "<your-region>", // something like "eu-central-003"
+    bucket: "<your-bucket-name>",
+    accessKeyId: process.env.S3_ACCESS_KEY_ID, // <your-application-key-id>,
+    secretAccessKey: process.env.S3_SECRET_KEY, // <your-application-key>,
+});
+```
+
 Popular S3 provider missing? Open an issue or file a PR!
 
 ## Tested On
@@ -197,6 +210,9 @@ To ensure compability across various providers and self-hosted services, all tes
 - Hetzner Object Storage
 - Cloudflare R2
 - Garage
+- Backblaze B2
 - Minio
 - LocalStack
+- RustFS
 - Ceph
+- S3Mock

package/dist/{index.d.ts → index.d.mts}

@@ -1,3 +1,4 @@
+import * as nodeUtil from "node:util";
 import { Readable } from "node:stream";
 import { Dispatcher } from "undici";
 
@@ -97,7 +98,10 @@ type DeleteObjectsError = {
 };
 interface S3FilePresignOptions extends OverridableS3ClientOptions {
   contentHash?: Buffer;
-  /** Seconds. */
+  /**
+   * In seconds.
+   * @default 3600 (1 hour)
+   */
   expiresIn?: number;
   method?: PresignableHttpMethod;
   contentLength?: number;
@@ -127,6 +131,25 @@ interface S3FilePresignOptions extends OverridableS3ClientOptions {
     contentDisposition?: ContentDisposition;
   };
 }
+/**
+ * Ref: https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-HTTPPOSTConstructPolicy.html#sigv4-ConditionMatching
+ */
+type ConditionMatchType = "starts-with" | "eq" | "content-length-range";
+type PostPolicyCondition = [string, string] | [ConditionMatchType, string | number, string | number];
+interface PresignPostOptions extends OverridableS3ClientOptions {
+  key: string;
+  /**
+   * In seconds.
+   * @default 3600 (1 hour)
+   */
+  expiresIn?: number;
+  fields?: Record<string, string>;
+  conditions?: PostPolicyCondition[];
+}
+type PresignPostResult = {
+  url: string;
+  fields: Record<string, string>;
+};
 type CopyObjectOptions = {
   /** Set this to override the {@link S3ClientOptions#bucket} that was passed on creation of the {@link S3Client}. */
   sourceBucket?: string;
@@ -386,7 +409,7 @@ declare class S3Client {
   /**
    * Create a new instance of an S3 bucket so that credentials can be managed from a single instance instead of being passed to every method.
    *
-   * @param  options The default options to use for the S3 client.
+   * @param options The default options to use for the S3 client.
    */
   constructor(options: S3ClientOptions);
   /** @internal */
@@ -451,6 +474,7 @@ declare class S3Client {
    * ```
    */
   presign(path: string, options?: S3FilePresignOptions): string;
+  presignPost(options: PresignPostOptions): PresignPostResult;
   /**
    * Copies an object from a source to a destination.
    * @remarks Uses [`CopyObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html).
@@ -557,6 +581,7 @@ declare class S3Client {
    * @internal
    */
   [kStream](path: ObjectKey, contentHash: Buffer | undefined, rageStart: number | undefined, rangeEndExclusive: number | undefined): ReadableStream<Uint8Array>;
+  [nodeUtil.inspect.custom](_depth?: number, options?: nodeUtil.InspectOptions): string;
 }
 //#endregion
 //#region src/S3Stat.d.ts
@@ -643,6 +668,7 @@ declare class S3File {
    * @param options Options for the copy operation.
    */
   copyTo(destination: string, options?: CopyObjectOptions): Promise<void>;
+  [nodeUtil.inspect.custom](_depth?: number, options?: nodeUtil.InspectOptions): string;
 }
 interface S3FileDeleteOptions extends OverridableS3ClientOptions {
   /** Signal to abort the request. */
@@ -666,22 +692,21 @@ type S3FileWriteOptions = {
 //#region src/S3Error.d.ts
 declare class S3Error extends Error {
   readonly code: string;
+  /** Path/key of the affected object. */
   readonly path: string;
   readonly message: string;
-  readonly requestId: string | undefined;
-  readonly hostId: string | undefined;
+  /** The HTTP status code. */
+  readonly status: number | undefined;
   constructor(code: string, path: string, {
     message,
-    requestId,
-    hostId,
-    cause
+    cause,
+    status
   }?: S3ErrorOptions);
 }
 type S3ErrorOptions = {
   message?: string | undefined;
-  requestId?: string | undefined;
-  hostId?: string | undefined;
   cause?: unknown;
+  status?: number;
 };
 //#endregion
 //#region src/index.d.ts

package/dist/{index.js → index.mjs}

@@ -1,3 +1,4 @@
+import * as nodeUtil from "node:util";
 import { Readable } from "node:stream";
 import { Agent, request } from "undici";
 import { XMLBuilder, XMLParser } from "fast-xml-parser";
@@ -34,17 +35,17 @@ var S3Stat = class S3Stat {
 //#region src/S3Error.ts
 var S3Error = class extends Error {
 	code;
+	/** Path/key of the affected object. */
 	path;
 	message;
-	requestId;
-	hostId;
-	constructor(code, path, { message = void 0, requestId = void 0, hostId = void 0, cause = void 0 } = {}) {
+	/** The HTTP status code. */
+	status;
+	constructor(code, path, { message = void 0, cause = void 0, status = void 0 } = {}) {
 		super(message, { cause });
 		this.code = code;
 		this.path = path;
 		this.message = message ?? "Some unknown error occurred.";
-		this.requestId = requestId;
-		this.hostId = hostId;
+		this.status = status;
 	}
 };
 
@@ -83,8 +84,11 @@ var S3BucketEntry = class S3BucketEntry {
 function deriveSigningKey(date, region, secretAccessKey) {
 	return createHmac("sha256", createHmac("sha256", createHmac("sha256", createHmac("sha256", `AWS4${secretAccessKey}`).update(date).digest()).update(region).digest()).update("s3").digest()).update("aws4_request").digest();
 }
-function signCanonicalDataHash(signinKey, canonicalDataHash, date, region) {
-	return createHmac("sha256", signinKey).update(`AWS4-HMAC-SHA256\n${date.dateTime}\n${date.date}/${region}/s3/aws4_request\n${canonicalDataHash}`).digest("hex");
+function signEncodedPolicy(signingKey, encodedPolicy) {
+	return createHmac("sha256", signingKey).update(encodedPolicy).digest("hex");
+}
+function signCanonicalDataHash(signingKey, canonicalDataHash, date, region) {
+	return createHmac("sha256", signingKey).update(`AWS4-HMAC-SHA256\n${date.dateTime}\n${date.date}/${region}/s3/aws4_request\n${canonicalDataHash}`).digest("hex");
 }
 const unsignedPayload = "UNSIGNED-PAYLOAD";
 /**
@@ -345,7 +349,7 @@ var S3Client = class {
 	/**
 	* Create a new instance of an S3 bucket so that credentials can be managed from a single instance instead of being passed to every method.
 	*
-	* @param  options The default options to use for the S3 client.
+	* @param options The default options to use for the S3 client.
 	*/
 	constructor(options) {
 		if (!options) throw new Error("`options` is required.");
@@ -456,6 +460,76 @@ var S3Client = class {
 		res.search = `${query}&X-Amz-Signature=${signCanonicalDataHash(signingKey, dataDigest, date, region)}`;
 		return res.toString();
 	}
+	presignPost(options) {
+		const now$1 = /* @__PURE__ */ new Date();
+		const date = getAmzDate(now$1);
+		const key = options.key;
+		const region = ensureValidRegion(options.region ?? this.#options.region);
+		const bucket = ensureValidBucketName(options.bucket ?? this.#options.bucket);
+		const endpoint = ensureValidEndpoint(options.endpoint ?? this.#options.endpoint);
+		const expiresIn = options.expiresIn ?? 3600;
+		const credential = `${this.#options.accessKeyId}/${date.date}/${region}/s3/aws4_request`;
+		const fields = {
+			...options.fields,
+			bucket,
+			"X-Amz-Algorithm": "AWS4-HMAC-SHA256",
+			"X-Amz-Credential": credential,
+			"X-Amz-Date": date.dateTime,
+			...this.#options.sessionToken ? { "X-Amz-Security-Token": this.#options.sessionToken } : void 0
+		};
+		const policy = {
+			expiration: new Date(now$1.getTime() + expiresIn * 1e3).toISOString().replace(/\.\d{3}Z$/, "Z"),
+			conditions: [
+				[
+					"eq",
+					"$bucket",
+					bucket
+				],
+				key.endsWith("{{filename}}") ? [
+					"starts-with",
+					"$key",
+					key.substring(0, key.lastIndexOf("{{filename}}"))
+				] : [
+					"eq",
+					"$key",
+					key
+				],
+				...options.conditions ? options.conditions : [],
+				[
+					"eq",
+					"$x-amz-algorithm",
+					"AWS4-HMAC-SHA256"
+				],
+				[
+					"eq",
+					"$x-amz-credential",
+					credential
+				],
+				[
+					"eq",
+					"$x-amz-date",
+					date.dateTime
+				]
+			]
+		};
+		if (this.#options.sessionToken) policy.conditions.push([
+			"eq",
+			"$x-amz-security-token",
+			this.#options.sessionToken
+		]);
+		const policyJson = JSON.stringify(policy);
+		const encodedPolicy = Buffer.from(policyJson).toString("base64");
+		const signingKey = this.#keyCache.computeIfAbsent(date, region, this.#options.accessKeyId, this.#options.secretAccessKey);
+		return {
+			url: buildRequestUrl(endpoint, bucket, region, "").toString(),
+			fields: {
+				...fields,
+				key,
+				Policy: encodedPolicy,
+				"X-Amz-Signature": signEncodedPolicy(signingKey, encodedPolicy)
+			}
+		};
+	}
 	/**
 	* Copies an object from a source to a destination.
 	* @remarks Uses [`CopyObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html).
@@ -977,12 +1051,17 @@ var S3Client = class {
 							} catch (cause) {
 								return controller.error(new S3Error("Unknown", path, {
 									message: "Could not parse XML error response.",
+									status: response.statusCode,
 									cause
 								}));
 							}
-							return controller.error(new S3Error(error.Error.Code || "Unknown", path, { message: error.Error.Message || void 0 }));
+							return controller.error(new S3Error(error.Error.Code || "Unknown", path, {
+								message: error.Error.Message || void 0,
+								status: response.statusCode
+							}));
 						}, onNetworkError);
 						return controller.error(new S3Error("Unknown", path, {
+							status: response.statusCode,
 							message: void 0,
 							cause: responseText
 						}));
@@ -995,6 +1074,17 @@ var S3Client = class {
 			}
 		});
 	}
+	[nodeUtil.inspect.custom](_depth, options = {}) {
+		if (options.depth === null) options.depth = 2;
+		options.colors ??= true;
+		const properties = {
+			endpoint: this.#options.endpoint,
+			bucket: this.#options.bucket,
+			region: this.#options.region,
+			accessKeyId: this.#options.accessKeyId
+		};
+		return `S3Client ${nodeUtil.formatWithOptions(options, properties)}`;
+	}
 };
 function buildSearchParams(amzCredential, date, expiresIn, headerList, contentHashStr, storageClass, sessionToken, acl, responseContentDisposition) {
 	let res = "";
@@ -1179,6 +1269,17 @@ var S3File = class S3File {
 	async copyTo(destination, options = {}) {
 		await this.#client.copyObject(this.#path, destination, options);
 	}
+	[nodeUtil.inspect.custom](_depth, options = {}) {
+		if (options.depth === null) options.depth = 2;
+		options.colors ??= true;
+		const properties = {
+			path: this.#path,
+			start: this.#start,
+			end: this.#end,
+			contentType: this.#contentType
+		};
+		return `S3File ${nodeUtil.formatWithOptions(options, properties)}`;
+	}
 };
 
 //#endregion

package/package.json

@@ -2,7 +2,7 @@
   "name": "lean-s3",
   "author": "Niklas Mollenhauer",
   "license": "MIT",
-  "version": "0.8.12",
+  "version": "0.9.0",
   "description": "A server-side S3 API for the regular user.",
   "keywords": [
     "s3",
@@ -26,12 +26,12 @@
     "type": "git",
     "url": "https://github.com/nikeee/lean-s3"
   },
-  "exports": {
-    "types": "./dist/index.d.ts",
-    "default": "./dist/index.js"
-  },
-  "types": "./dist/index.d.ts",
+  "types": "./dist/index.d.mts",
+  "main": "./dist/index.mjs",
   "type": "module",
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsdown",
     "test": "tsgo && tsx --test src/*.test.ts src/test/*.test.ts",
@@ -39,27 +39,28 @@
     "ci": "biome ci ./src",
     "docs": "typedoc",
     "lint": "biome lint ./src",
-    "format": "biome format --write ./src && biome lint --write ./src && biome check --write ./src",
+    "format": "biome check --write ./src",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "fast-xml-parser": "^5.3.0",
+    "fast-xml-parser": "^5.3.2",
     "undici": "^7.16.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.3.2",
-    "@testcontainers/localstack": "^11.7.2",
-    "@testcontainers/minio": "^11.7.2",
-    "@types/node": "^24.9.2",
-    "@typescript/native-preview": "^7.0.0-dev.20251029.1",
+    "@biomejs/biome": "2.3.6",
+    "@testcontainers/localstack": "^11.8.1",
+    "@testcontainers/minio": "^11.8.1",
+    "@testcontainers/s3mock": "^11.8.1",
+    "@types/node": "^24.10.1",
+    "@typescript/native-preview": "^7.0.0-dev.20251118.1",
     "expect": "^30.2.0",
-    "lefthook": "^2.0.2",
-    "testcontainers": "^11.7.2",
-    "tsdown": "^0.15.12",
+    "lefthook": "^2.0.4",
+    "testcontainers": "^11.8.1",
+    "tsdown": "^0.16.5",
     "tsx": "^4.20.6",
     "typedoc": "^0.28.14"
   },
   "engines": {
-    "node": "^20.19.3 || ^22.17.0 || ^24.4.0 || ^25"
+    "node": "^20.19.5 || ^22.21.1 || ^24.11.0 || ^25.1.0"
   }
 }

package/tsdown.config.ts

@@ -1,6 +0,0 @@
-import { defineConfig } from "tsdown";
-
-export default defineConfig({
-	entry: ["src/index.ts"],
-	target: "esnext",
-});