bun-types 1.1.43-canary.20250106T140553 → 1.1.43-canary.20250107T145807

package/bun.d.ts

@@ -21,6 +21,7 @@ declare module "bun" {
 		EphemeralKeyInfo,
 		PeerCertificate,
 	} from "tls";
+	import type { Stats } from "node:fs";
 	interface Env {
 		NODE_ENV?: string;
 		/**
@@ -1274,118 +1275,14 @@ declare module "bun" {
 		 * Finish the upload. This also flushes the internal buffer.
 		 */
 		end(error?: Error): number | Promise<number>;
-	}
-
-	type S3 = {
-		/**
-		 * 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. Can be
-		 * overriden by passing options to the methods.
-		 *
-		 * ## Keep S3 credentials in a single instance
-		 *
-		 * @example
-		 *     const bucket = new Bun.S3({
-		 *       accessKeyId: "your-access-key",
-		 *       secretAccessKey: "your-secret-key",
-		 *       bucket: "my-bucket",
-		 *       endpoint: "https://s3.us-east-1.amazonaws.com",
-		 *       sessionToken: "your-session-token",
-		 *     });
-		 *
-		 *     // S3Bucket is callable, so you can do this:
-		 *     const file = bucket("my-file.txt");
-		 *
-		 *     // or this:
-		 *     await file.write("Hello Bun!");
-		 *     await file.text();
-		 *
-		 *     // To delete the file:
-		 *     await bucket.delete("my-file.txt");
-		 *
-		 *     // To write a file without returning the instance:
-		 *     await bucket.write("my-file.txt", "Hello Bun!");
-		 *
-		 */
-		new (options?: S3Options): S3Bucket;
 
 		/**
-		 * Delete a file from an S3-compatible object storage service.
-		 *
-		 * @param path The path to the file.
-		 * @param options The options to use for the S3 client.
-		 *
-		 * For an instance method version, {@link S3File.unlink}. You can also use {@link S3Bucket.unlink}.
-		 *
-		 * @example
-		 *     import { S3 } from "bun";
-		 *     await S3.unlink("s3://my-bucket/my-file.txt", {
-		 *       accessKeyId: "your-access-key",
-		 *       secretAccessKey: "your-secret-key",
-		 *     });
-		 *
-		 * @example
-		 *     await S3.unlink("key", {
-		 *       bucket: "my-bucket",
-		 *       accessKeyId: "your-access-key",
-		 *       secretAccessKey: "your-secret-key",
-		 *     });
-		 */
-		delete(path: string, options?: S3Options): Promise<void>;
-		/**
-		 * unlink is an alias for {@link S3.delete}
+		 * Get the stat of the file.
 		 */
-		unlink: S3["delete"];
+		stat(): Promise<Stats>;
+	}
 
-		/**
-		 * Writes data to an S3-compatible storage service.
-		 * Supports various input types and handles large files with multipart uploads.
-		 *
-		 * @param path The path or key where the file will be written
-		 * @param data The data to write
-		 * @param options S3 configuration and upload options
-		 * @returns promise that resolves with the number of bytes written
-		 *
-		 * @example
-		 *   // Writing a string
-		 *   await S3.write("hello.txt", "Hello World!", {
-		 *     bucket: "my-bucket",
-		 *     type: "text/plain"
-		 *   });
-		 *
-		 * @example
-		 *   // Writing JSON
-		 *   await S3.write(
-		 *     "data.json",
-		 *     JSON.stringify({ hello: "world" }),
-		 *     { type: "application/json" }
-		 *   );
-		 *
-		 * @example
-		 *   // Writing a large file with multipart upload
-		 *   await S3.write("large-file.dat", largeBuffer, {
-		 *     partSize: 10 * 1024 * 1024, // 10MB parts
-		 *     queueSize: 4, // Upload 4 parts in parallel
-		 *     retry: 3 // Retry failed parts up to 3 times
-		 *   });
-		 */
-		write(
-			path: string,
-			data:
-				| string
-				| ArrayBufferView
-				| ArrayBufferLike
-				| Response
-				| Request
-				| ReadableStream
-				| Blob
-				| File,
-			options?: S3Options,
-		): Promise<number>;
-	};
-	var S3: S3;
+	var S3Client: S3Client;
 
 	/**
 	 * Creates a new S3File instance for working with a single file.
@@ -1528,7 +1425,7 @@ declare module "bun" {
 		endpoint?: string;
 
 		/**
-		 * The size of each part in multipart uploads (in MiB).
+		 * The size of each part in multipart uploads (in bytes).
 		 * - Minimum: 5 MiB
 		 * - Maximum: 5120 MiB
 		 * - Default: 5 MiB
@@ -1536,7 +1433,7 @@ declare module "bun" {
 		 * @example
 		 *     // Configuring multipart uploads
 		 *     const file = s3("large-file.dat", {
-		 *       partSize: 10, // 10 MiB parts
+		 *       partSize: 10 * 1024 * 1024, // 10 MiB parts
 		 *       queueSize: 4  // Upload 4 parts in parallel
 		 *     });
 		 *
@@ -1630,6 +1527,13 @@ declare module "bun" {
 		method?: "GET" | "POST" | "PUT" | "DELETE" | "HEAD";
 	}
 
+	interface S3Stats {
+		size: number;
+		lastModified: Date;
+		etag: string;
+		type: string;
+	}
+
 	/**
 	 * Represents a file in an S3-compatible storage service.
 	 * Extends the Blob interface for compatibility with web APIs.
@@ -1908,6 +1812,13 @@ declare module "bun" {
 		 * await file.unlink();
 		 */
 		unlink: S3File["delete"];
+
+		/**
+		 * Get the stat of a file in an S3-compatible storage service.
+		 *
+		 * @returns Promise resolving to S3Stat
+		 */
+		stat(): Promise<S3Stats>;
 	}
 
 	/**
@@ -1917,7 +1828,7 @@ declare module "bun" {
 	 *
 	 * @example
 	 *     // Basic bucket setup
-	 *     const bucket = new S3({
+	 *     const bucket = new S3Client({
 	 *       bucket: "my-bucket",
 	 *       accessKeyId: "key",
 	 *       secretAccessKey: "secret"
@@ -1931,19 +1842,53 @@ declare module "bun" {
 	 *     const url = bucket.presign("file.pdf");
 	 *     await bucket.unlink("old.txt");
 	 */
-	type S3Bucket = {
+	type 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. Can be
+		 * overriden by passing options to the methods.
+		 *
+		 * ## Keep S3 credentials in a single instance
+		 *
+		 * @example
+		 *     const bucket = new Bun.S3Client({
+		 *       accessKeyId: "your-access-key",
+		 *       secretAccessKey: "your-secret-key",
+		 *       bucket: "my-bucket",
+		 *       endpoint: "https://s3.us-east-1.amazonaws.com",
+		 *       sessionToken: "your-session-token",
+		 *     });
+		 *
+		 *     // S3Client is callable, so you can do this:
+		 *     const file = bucket.file("my-file.txt");
+		 *
+		 *     // or this:
+		 *     await file.write("Hello Bun!");
+		 *     await file.text();
+		 *
+		 *     // To delete the file:
+		 *     await bucket.delete("my-file.txt");
+		 *
+		 *     // To write a file without returning the instance:
+		 *     await bucket.write("my-file.txt", "Hello Bun!");
+		 *
+		 */
+		new (options?: S3Options): S3Client;
+
 		/**
 		 * Creates an S3File instance for the given path.
 		 *
 		 * @example
-		 * const file = bucket("image.jpg");
+		 * const file = bucket.file("image.jpg");
 		 * await file.write(imageData);
 		 * const configFile = bucket("config.json", {
 		 *   type: "application/json",
 		 *   acl: "private"
 		 * });
 		 */
-		(path: string, options?: S3Options): S3File;
+		file(path: string, options?: S3Options): S3File;
 
 		/**
 		 * Writes data directly to a path in the bucket.
@@ -2028,6 +1973,7 @@ declare module "bun" {
 		 *     }
 		 */
 		unlink(path: string, options?: S3Options): Promise<void>;
+		delete: S3Client["unlink"];
 
 		/**
 		 * Get the size of a file in bytes.
@@ -2066,6 +2012,13 @@ declare module "bun" {
 		 *     }
 		 */
 		exists(path: string, options?: S3Options): Promise<boolean>;
+		/**
+		 * Get the stat of a file in an S3-compatible storage service.
+		 *
+		 * @param path The path to the file.
+		 * @param options The options to use for the S3 client.
+		 */
+		stat(path: string, options?: S3Options): Promise<S3Stats>;
 	};
 
 	/**

package/docs/api/s3.md

@@ -3,14 +3,11 @@ Production servers often read, upload, and write files to S3-compatible object s
 Bun provides fast, native bindings for interacting with S3-compatible object storage services. Bun's S3 API is designed to be simple and feel similar to fetch's `Response` and `Blob` APIs (like Bun's local filesystem APIs).
 
 ```ts
-import { s3, write, S3 } from "bun";
+import { s3, write, S3Client } from "bun";
 
-const metadata = await s3("123.json", {
-  accessKeyId: "your-access-key",
-  secretAccessKey: "your-secret-key",
-  bucket: "my-bucket",
-  // endpoint: "https://s3.us-east-1.amazonaws.com",
-});
+// Bun.s3 reads environment variables for credentials
+// file() returns a lazy reference to a file on S3
+const metadata = s3.file("123.json");
 
 // Download from S3 as JSON
 const data = await metadata.json();
@@ -23,9 +20,12 @@ const url = metadata.presign({
   acl: "public-read",
   expiresIn: 60 * 60 * 24, // 1 day
 });
+
+// Delete the file
+await metadata.delete();
 ```
 
-S3 is the [de facto standard](https://en.wikipedia.org/wiki/De_facto_standard) internet filesystem. You can use Bun's S3 API with S3-compatible storage services like:
+S3 is the [de facto standard](https://en.wikipedia.org/wiki/De_facto_standard) internet filesystem. Bun's S3 API works with S3-compatible storage services like:
 
 - AWS S3
 - Cloudflare R2
@@ -38,28 +38,45 @@ S3 is the [de facto standard](https://en.wikipedia.org/wiki/De_facto_standard) i
 
 There are several ways to interact with Bun's S3 API.
 
-### Using `Bun.s3()`
+### `Bun.S3Client` & `Bun.s3`
+
+`Bun.s3` is equivalent to `new Bun.S3Client()`, relying on environment variables for credentials.
 
-The `s3()` helper function is used to create one-off `S3File` instances for a single file.
+To explicitly set credentials, pass them to the `Bun.S3Client` constructor.
 
 ```ts
-import { s3 } from "bun";
+import { S3Client } from "bun";
 
-// Using the s3() helper
-const s3file = s3("my-file.txt", {
+const client = new S3Client({
   accessKeyId: "your-access-key",
   secretAccessKey: "your-secret-key",
   bucket: "my-bucket",
-  // endpoint: "https://s3.us-east-1.amazonaws.com", // optional
+  // sessionToken: "..."
+  // acl: "public-read",
+  // endpoint: "https://s3.us-east-1.amazonaws.com",
   // endpoint: "https://<account-id>.r2.cloudflarestorage.com", // Cloudflare R2
   // endpoint: "https://<region>.digitaloceanspaces.com", // DigitalOcean Spaces
   // endpoint: "http://localhost:9000", // MinIO
 });
+
+// Bun.s3 is a global singleton that is equivalent to `new Bun.S3Client()`
+Bun.s3 = client;
+```
+
+### Working with S3 Files
+
+The **`file`** method in `S3Client` returns a **lazy reference to a file on S3**.
+
+```ts
+// A lazy reference to a file on S3
+const s3file: S3File = client.file("123.json");
 ```
 
-### Reading Files
+Like `Bun.file(path)`, the `S3Client`'s `file` method is synchronous. It does zero network requests until you call a method that depends on a network request.
+
+### Reading files from S3
 
-You can read files from S3 using similar methods to Bun's file system APIs:
+If you've used the `fetch` API, you're familiar with the `Response` and `Blob` APIs. `S3File` extends `Blob`. The same methods that work on `Blob` also work on `S3File`.
 
 ```ts
 // Read an S3File as text
@@ -81,14 +98,28 @@ for await (const chunk of stream) {
 }
 ```
 
-## Writing Files
+#### Memory optimization
+
+Methods like `text()`, `json()`, `bytes()`, or `arrayBuffer()` avoid duplicating the string or bytes in memory when possible.
+
+If the text happens to be ASCII, Bun directly transfers the string to JavaScriptCore (the engine) without transcoding and without duplicating the string in memory. When you use `.bytes()` or `.arrayBuffer()`, it will also avoid duplicating the bytes in memory.
 
-Writing to S3 is just as simple:
+These helper methods not only simplify the API, they also make it faster.
+
+### Writing & uploading files to S3
+
+Writing to S3 is just as simple.
 
 ```ts
 // Write a string (replacing the file)
 await s3file.write("Hello World!");
 
+// Write a Buffer (replacing the file)
+await s3file.write(Buffer.from("Hello World!"));
+
+// Write a Response (replacing the file)
+await s3file.write(new Response("Hello World!"));
+
 // Write with content type
 await s3file.write(JSON.stringify({ name: "John", age: 30 }), {
   type: "application/json",
@@ -119,7 +150,7 @@ const writer = s3file.writer({
   queueSize: 10,
 
   // Upload in 5 MB chunks
-  partSize: 5 * 1024 * 1024,
+  partSize: 5,
 });
 for (let i = 0; i < 10; i++) {
   await writer.write(bigFile);
@@ -134,20 +165,11 @@ When your production service needs to let users upload files to your server, it'
 To facilitate this, you can presign URLs for S3 files. This generates a URL with a signature that allows a user to securely upload that specific file to S3, without exposing your credentials or granting them unnecessary access to your bucket.
 
 ```ts
-// Generate a presigned URL that expires in 24 hours (default)
-const url = s3file.presign();
-
-// Custom expiration time (in seconds)
-const url2 = s3file.presign({ expiresIn: 3600 }); // 1 hour
+import { s3 } from "bun";
 
-// Using static method
-const url3 = Bun.S3.presign("my-file.txt", {
-  bucket: "my-bucket",
-  accessKeyId: "your-access-key",
-  secretAccessKey: "your-secret-key",
-  // endpoint: "https://s3.us-east-1.amazonaws.com",
-  // endpoint: "https://<account-id>.r2.cloudflarestorage.com", // Cloudflare R2
-  expiresIn: 3600,
+// Generate a presigned URL that expires in 24 hours (default)
+const url = s3.presign("my-file.txt", {
+  expiresIn: 3600, // 1 hour
 });
 ```
 
@@ -183,6 +205,12 @@ To set an expiration time for a presigned URL, pass the `expiresIn` option.
 const url = s3file.presign({
   // Seconds
   expiresIn: 3600, // 1 hour
+
+  // access control list
+  acl: "public-read",
+
+  // HTTP method
+  method: "PUT",
 });
 ```
 
@@ -203,7 +231,7 @@ const url = s3file.presign({
 
 ### `new Response(S3File)`
 
-To quickly redirect users to a presigned URL for an S3 file, you can pass an `S3File` instance to a `Response` object as the body.
+To quickly redirect users to a presigned URL for an S3 file, pass an `S3File` instance to a `Response` object as the body.
 
 ```ts
 const response = new Response(s3file);
@@ -230,30 +258,85 @@ Response (0 KB) {
 
 Bun's S3 implementation works with any S3-compatible storage service. Just specify the appropriate endpoint:
 
+### Using Bun's S3Client with AWS S3
+
+AWS S3 is the default. You can also pass a `region` option instead of an `endpoint` option for AWS S3.
+
 ```ts
-import { s3 } from "bun";
+import { S3Client } from "bun";
+
+// AWS S3
+const s3 = new S3Client({
+  accessKeyId: "access-key",
+  secretAccessKey: "secret-key",
+  bucket: "my-bucket",
+  // endpoint: "https://s3.us-east-1.amazonaws.com",
+  // region: "us-east-1",
+});
+```
+
+### Using Bun's S3Client with Google Cloud Storage
+
+To use Bun's S3 client with [Google Cloud Storage](https://cloud.google.com/storage), set `endpoint` to `"https://storage.googleapis.com"` in the `S3Client` constructor.
+
+```ts
+import { S3Client } from "bun";
+
+// Google Cloud Storage
+const gcs = new S3Client({
+  accessKeyId: "access-key",
+  secretAccessKey: "secret-key",
+  bucket: "my-bucket",
+  endpoint: "https://storage.googleapis.com",
+});
+```
+
+### Using Bun's S3Client with Cloudflare R2
+
+To use Bun's S3 client with [Cloudflare R2](https://developers.cloudflare.com/r2/), set `endpoint` to the R2 endpoint in the `S3Client` constructor. The R2 endpoint includes your account ID.
+
+```ts
+import { S3Client } from "bun";
 
 // CloudFlare R2
-const r2file = s3("my-file.txt", {
+const r2 = new S3Client({
   accessKeyId: "access-key",
   secretAccessKey: "secret-key",
   bucket: "my-bucket",
   endpoint: "https://<account-id>.r2.cloudflarestorage.com",
 });
+```
+
+### Using Bun's S3Client with DigitalOcean Spaces
+
+To use Bun's S3 client with [DigitalOcean Spaces](https://www.digitalocean.com/products/spaces/), set `endpoint` to the DigitalOcean Spaces endpoint in the `S3Client` constructor.
 
-// DigitalOcean Spaces
-const spacesFile = s3("my-file.txt", {
+```ts
+import { S3Client } from "bun";
+
+const spaces = new S3Client({
   accessKeyId: "access-key",
   secretAccessKey: "secret-key",
   bucket: "my-bucket",
+  // region: "nyc3",
   endpoint: "https://<region>.digitaloceanspaces.com",
 });
+```
+
+### Using Bun's S3Client with MinIO
 
-// MinIO
-const minioFile = s3("my-file.txt", {
+To use Bun's S3 client with [MinIO](https://min.io/), set `endpoint` to the URL that MinIO is running on in the `S3Client` constructor.
+
+```ts
+import { S3Client } from "bun";
+
+const minio = new S3Client({
   accessKeyId: "access-key",
   secretAccessKey: "secret-key",
   bucket: "my-bucket",
+
+  // Make sure to use the correct endpoint URL
+  // It might not be localhost in production!
   endpoint: "http://localhost:9000",
 });
 ```
@@ -284,16 +367,16 @@ If the `S3_*` environment variable is not set, Bun will also check for the `AWS_
 
 These environment variables are read from [`.env` files](/docs/runtime/env) or from the process environment at initialization time (`process.env` is not used for this).
 
-These defaults are overriden by the options you pass to `s3(credentials)`, `new Bun.S3(credentials)`, or any of the methods that accept credentials. So if, for example, you use the same credentials for different buckets, you can set the credentials once in your `.env` file and then pass `bucket: "my-bucket"` to the `s3()` helper function without having to specify all the credentials again.
+These defaults are overriden by the options you pass to `s3(credentials)`, `new Bun.S3Client(credentials)`, or any of the methods that accept credentials. So if, for example, you use the same credentials for different buckets, you can set the credentials once in your `.env` file and then pass `bucket: "my-bucket"` to the `s3()` helper function without having to specify all the credentials again.
 
-### `S3` Buckets
+### `S3Client` objects
 
-Passing around all of these credentials can be cumbersome. To make it easier, you can create a `S3` bucket instance.
+When you're not using environment variables or using multiple buckets, you can create a `S3Client` object to explicitly set credentials.
 
 ```ts
-import { S3 } from "bun";
+import { S3Client } from "bun";
 
-const bucket = new S3({
+const client = new S3Client({
   accessKeyId: "your-access-key",
   secretAccessKey: "your-secret-key",
   bucket: "my-bucket",
@@ -303,15 +386,6 @@ const bucket = new S3({
   // endpoint: "http://localhost:9000", // MinIO
 });
 
-// bucket is a function that creates `S3File` instances (lazy)
-const file = bucket("my-file.txt");
-
-// Write to S3
-await file.write("Hello World!");
-
-// Read from S3
-const text = await file.text();
-
 // Write using a Response
 await file.write(new Response("Hello World!"));
 
@@ -322,65 +396,57 @@ const url = file.presign({
 });
 
 // Delete the file
-await file.unlink();
+await file.delete();
 ```
 
-#### Read a file from an `S3` bucket
+### `S3Client.prototype.write`
 
-The `S3` bucket instance is itself a function that creates `S3File` instances. It provides a more convenient API for interacting with S3.
+To upload or write a file to S3, call `write` on the `S3Client` instance.
 
 ```ts
-const s3file = bucket("my-file.txt");
-const text = await s3file.text();
-const json = await s3file.json();
-const bytes = await s3file.bytes();
-const arrayBuffer = await s3file.arrayBuffer();
-```
-
-#### Write a file to S3
-
-To write a file to the bucket, you can use the `write` method.
-
-```ts
-const bucket = new Bun.S3({
+const client = new Bun.S3Client({
   accessKeyId: "your-access-key",
   secretAccessKey: "your-secret-key",
   endpoint: "https://s3.us-east-1.amazonaws.com",
   bucket: "my-bucket",
 });
-await bucket.write("my-file.txt", "Hello World!");
-await bucket.write("my-file.txt", new Response("Hello World!"));
-```
-
-You can also call `.write` on the `S3File` instance created by the `S3` bucket instance.
+await client.write("my-file.txt", "Hello World!");
+await client.write("my-file.txt", new Response("Hello World!"));
 
-```ts
-const s3file = bucket("my-file.txt");
-await s3file.write("Hello World!", {
-  type: "text/plain",
-});
-await s3file.write(new Response("Hello World!"));
+// equivalent to
+// await client.file("my-file.txt").write("Hello World!");
 ```
 
-#### Delete a file from S3
+### `S3Client.prototype.delete`
 
-To delete a file from the bucket, you can use the `delete` method.
+To delete a file from S3, call `delete` on the `S3Client` instance.
 
 ```ts
-const bucket = new Bun.S3({
+const client = new Bun.S3Client({
   accessKeyId: "your-access-key",
   secretAccessKey: "your-secret-key",
   bucket: "my-bucket",
 });
 
-await bucket.delete("my-file.txt");
+await client.delete("my-file.txt");
+// equivalent to
+// await client.file("my-file.txt").delete();
 ```
 
-You can also use the `unlink` method, which is an alias for `delete`.
+### `S3Client.prototype.exists`
+
+To check if a file exists in S3, call `exists` on the `S3Client` instance.
 
 ```ts
-// "delete" and "unlink" are aliases of each other.
-await bucket.unlink("my-file.txt");
+const client = new Bun.S3Client({
+  accessKeyId: "your-access-key",
+  secretAccessKey: "your-secret-key",
+  bucket: "my-bucket",
+});
+
+const exists = await client.exists("my-file.txt");
+// equivalent to
+// const exists = await client.file("my-file.txt").exists();
 ```
 
 ## `S3File`
@@ -410,7 +476,18 @@ interface S3File extends Blob {
     options?: BlobPropertyBag,
   ): Promise<void>;
 
-  readonly size: Promise<number>;
+  exists(options?: S3Options): Promise<boolean>;
+  unlink(options?: S3Options): Promise<void>;
+  delete(options?: S3Options): Promise<void>;
+  presign(options?: S3Options): string;
+
+  stat(options?: S3Options): Promise<S3Stat>;
+  /**
+   * Size is not synchronously available because it requires a network request.
+   *
+   * @deprecated Use `stat()` instead.
+   */
+  size: NaN;
 
   // ... more omitted for brevity
 }
@@ -428,7 +505,7 @@ Like `Bun.file()`, `S3File` extends [`Blob`](https://developer.mozilla.org/en-US
 
 That means using `S3File` instances with `fetch()`, `Response`, and other web APIs that accept `Blob` instances just works.
 
-### Partial reads
+### Partial reads with `slice`
 
 To read a partial range of a file, you can use the `slice` method.
 
@@ -444,6 +521,17 @@ const text = await partial.text();
 
 Internally, this works by using the HTTP `Range` header to request only the bytes you want. This `slice` method is the same as [`Blob.prototype.slice`](https://developer.mozilla.org/en-US/docs/Web/API/Blob/slice).
 
+### Deleting files from S3
+
+To delete a file from S3, you can use the `delete` method.
+
+```ts
+await s3file.delete();
+// await s3File.unlink();
+```
+
+`delete` is the same as `unlink`.
+
 ## Error codes
 
 When Bun's S3 API throws an error, it will have a `code` property that matches one of the following values:
@@ -457,82 +545,101 @@ When Bun's S3 API throws an error, it will have a `code` property that matches o
 
 When the S3 Object Storage service returns an error (that is, not Bun), it will be an `S3Error` instance (an `Error` instance with the name `"S3Error"`).
 
-## `S3` static methods
+## `S3Client` static methods
 
-The `S3` class provides several static methods for interacting with S3.
+The `S3Client` class provides several static methods for interacting with S3.
 
-### `S3.presign`
+### `S3Client.presign` (static)
 
-To generate a presigned URL for an S3 file, you can use the `S3.presign` method.
+To generate a presigned URL for an S3 file, you can use the `S3Client.presign` static method.
 
 ```ts
-import { S3 } from "bun";
+import { S3Client } from "bun";
 
-const url = S3.presign("my-file.txt", {
+const credentials = {
   accessKeyId: "your-access-key",
   secretAccessKey: "your-secret-key",
   bucket: "my-bucket",
-  expiresIn: 3600,
   // endpoint: "https://s3.us-east-1.amazonaws.com",
   // endpoint: "https://<account-id>.r2.cloudflarestorage.com", // Cloudflare R2
+};
+
+const url = S3Client.presign("my-file.txt", {
+  ...credentials,
+  expiresIn: 3600,
 });
 ```
 
-This is the same as `S3File.prototype.presign` and `new S3(credentials).presign`, as a static method on the `S3` class.
+This is equivalent to calling `new S3Client(credentials).presign("my-file.txt", { expiresIn: 3600 })`.
 
-### `S3.exists`
+### `S3Client.exists` (static)
 
-To check if an S3 file exists, you can use the `S3.exists` method.
+To check if an S3 file exists, you can use the `S3Client.exists` static method.
 
 ```ts
-import { S3 } from "bun";
+import { S3Client } from "bun";
 
-const exists = await S3.exists("my-file.txt", {
+const credentials = {
   accessKeyId: "your-access-key",
   secretAccessKey: "your-secret-key",
   bucket: "my-bucket",
   // endpoint: "https://s3.us-east-1.amazonaws.com",
-});
+};
+
+const exists = await S3Client.exists("my-file.txt", credentials);
 ```
 
 The same method also works on `S3File` instances.
 
 ```ts
 const s3file = Bun.s3("my-file.txt", {
-  accessKeyId: "your-access-key",
-  secretAccessKey: "your-secret-key",
-  bucket: "my-bucket",
+  ...credentials,
 });
 const exists = await s3file.exists();
 ```
 
-### `S3.size`
+### `S3Client.stat` (static)
 
-To get the size of an S3 file, you can use the `S3.size` method.
+To get the size, etag, and other metadata of an S3 file, you can use the `S3Client.stat` static method.
 
 ```ts
-import { S3 } from "bun";
-const size = await S3.size("my-file.txt", {
+import { S3Client } from "bun";
+
+const credentials = {
   accessKeyId: "your-access-key",
   secretAccessKey: "your-secret-key",
   bucket: "my-bucket",
   // endpoint: "https://s3.us-east-1.amazonaws.com",
-});
+};
+
+const stat = await S3Client.stat("my-file.txt", credentials);
+// {
+//   size: 1024,
+//   etag: "1234567890",
+//   lastModified: new Date(),
+// }
 ```
 
-### `S3.unlink`
+### `S3Client.delete` (static)
 
-To delete an S3 file, you can use the `S3.unlink` method.
+To delete an S3 file, you can use the `S3Client.delete` static method.
 
 ```ts
-import { S3 } from "bun";
+import { S3Client } from "bun";
 
-await S3.unlink("my-file.txt", {
+const credentials = {
   accessKeyId: "your-access-key",
   secretAccessKey: "your-secret-key",
   bucket: "my-bucket",
   // endpoint: "https://s3.us-east-1.amazonaws.com",
-});
+};
+
+await S3Client.delete("my-file.txt", credentials);
+// equivalent to
+// await new S3Client(credentials).delete("my-file.txt");
+
+// S3Client.unlink is alias of S3Client.delete
+await S3Client.unlink("my-file.txt", credentials);
 ```
 
 ## s3:// protocol
@@ -544,6 +651,27 @@ const response = await fetch("s3://my-bucket/my-file.txt");
 const file = Bun.file("s3://my-bucket/my-file.txt");
 ```
 
-This is the equivalent of calling `Bun.s3("my-file.txt", { bucket: "my-bucket" })`.
+You can additionally pass `s3` options to the `fetch` and `Bun.file` functions.
+
+```ts
+const response = await fetch("s3://my-bucket/my-file.txt", {
+  s3: {
+    accessKeyId: "your-access-key",
+    secretAccessKey: "your-secret-key",
+    endpoint: "https://s3.us-east-1.amazonaws.com",
+  },
+  headers: {
+    "x-amz-meta-foo": "bar",
+  },
+});
+```
+
+### UTF-8, UTF-16, and BOM (byte order mark)
+
+Like `Response` and `Blob`, `S3File` assumes UTF-8 encoding by default.
+
+When calling one of the `text()` or `json()` methods on an `S3File`:
 
-This `s3://` protocol exists to make it easier to use the same code for local files and S3 files.
+- When a UTF-16 byte order mark (BOM) is detected, it will be treated as UTF-16. JavaScriptCore natively supports UTF-16, so it skips the UTF-8 transcoding process (and strips the BOM). This is mostly good, but it does mean if you have invalid surrogate pairs characters in your UTF-16 string, they will be passed through to JavaScriptCore (same as source code).
+- When a UTF-8 BOM is detected, it gets stripped before the string is passed to JavaScriptCore and invalid UTF-8 codepoints are replaced with the Unicode replacement character (`\uFFFD`).
+- UTF-32 is not supported.

package/docs/cli/add.md

@@ -33,6 +33,14 @@ To add a package as an optional dependency (`"optionalDependencies"`):
 $ bun add --optional lodash
 ```
 
+## `--peer`
+
+To add a package as a peer dependency (`"peerDependencies"`):
+
+```bash
+$ bun add --peer @types/bun
+```
+
 ## `--exact`
 
 {% callout %}

package/docs/guides/install/add-optional.md

@@ -2,7 +2,7 @@
 name: Add an optional dependency
 ---
 
-To add an npm package as a peer dependency, use the `--optional` flag.
+To add an npm package as an optional dependency, use the `--optional` flag.
 
 ```sh
 $ bun add zod --optional

package/docs/install/index.md

@@ -143,6 +143,12 @@ To add a package as an optional dependency (`"optionalDependencies"`):
 $ bun add --optional lodash
 ```
 
+To add a package as a peer dependency (`"peerDependencies"`):
+
+```bash
+$ bun add --peer @types/bun
+```
+
 To install a package globally:
 
 ```bash

package/docs/install/workspaces.md

@@ -53,6 +53,16 @@ Each workspace has it's own `package.json`. When referencing other packages in t
 }
 ```
 
+`bun install` will install dependencies for all workspaces in the monorepo, de-duplicating packages if possible. If you only want to install dependencies for specific workspaces, you can use the `--filter` flag.
+
+```bash
+# Install dependencies for all workspaces starting with `pkg-` except for `pkg-c`
+$ bun install --filter "pkg-*" --filter "!pkg-c"
+
+# Paths can also be used. This is equivalent to the command above.
+$ bun install --filter "./packages/pkg-*" --filter "!pkg-c" # or --filter "!./packages/pkg-c"
+```
+
 Workspaces have a couple major benefits.
 
 - **Code can be split into logical parts.** If one package relies on another, you can simply add it as a dependency in `package.json`. If package `b` depends on `a`, `bun install` will install your local `packages/a` directory into `node_modules` instead of downloading it from the npm registry.

package/docs/runtime/nodejs-apis.md

@@ -341,7 +341,7 @@ The table below lists all globals implemented by Node.js and Bun's current compa
 
 ### [`process`](https://nodejs.org/api/process.html)
 
-🟡 Missing `domain` `initgroups` `setegid` `seteuid` `setgid` `setgroups` `setuid` `allowedNodeEnvironmentFlags` `getActiveResourcesInfo` `setActiveResourcesInfo` `moduleLoadList` `setSourceMapsEnabled`. `process.binding` is partially implemented.
+🟡 Missing `initgroups` `allowedNodeEnvironmentFlags` `getActiveResourcesInfo` `setActiveResourcesInfo` `moduleLoadList` `setSourceMapsEnabled`. `process.binding` is partially implemented.
 
 ### [`queueMicrotask()`](https://developer.mozilla.org/en-US/docs/Web/API/queueMicrotask)
 

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "1.1.43-canary.20250106T140553",
+	"version": "1.1.43-canary.20250107T145807",
 	"name": "bun-types",
 	"license": "MIT",
 	"main": "",