bun-types 1.1.43-canary.20250106T140553 → 1.1.43-canary.20250108T140520

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",
@@ -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 overridden 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,102 @@ 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);
+// {
+//   etag: "\"7a30b741503c0b461cc14157e2df4ad8\"",
+//   lastModified: 2025-01-07T00:19:10.000Z,
+//   size: 1024,
+//   type: "text/plain;charset=utf-8",
+// }
 ```
 
-### `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 +652,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: {
+    "range": "bytes=0-1023",
+  },
+});
+```
+
+### 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/api/sqlite.md

@@ -82,7 +82,7 @@ const strict = new Database(
 // throws error because of the typo:
 const query = strict
   .query("SELECT $message;")
-  .all({ messag: "Hello world" });
+  .all({ message: "Hello world" });
 
 const notStrict = new Database(
   ":memory:"
@@ -90,7 +90,7 @@ const notStrict = new Database(
 // does not throw error:
 notStrict
   .query("SELECT $message;")
-  .all({ messag: "Hello world" });
+  .all({ message: "Hello world" });
 ```
 
 ### Load via ES module import

package/docs/api/utils.md

@@ -121,7 +121,7 @@ const id = randomUUIDv7();
 
 A UUID v7 is a 128-bit value that encodes the current timestamp, a random value, and a counter. The timestamp is encoded using the lowest 48 bits, and the random value and counter are encoded using the remaining bits.
 
-The `timestamp` parameter defaults to the current time in milliseconds. When the timestamp changes, the counter is reset to a psuedo-random integer wrapped to 4096. This counter is atomic and threadsafe, meaning that using `Bun.randomUUIDv7()` in many Workers within the same process running at the same timestamp will not have colliding counter values.
+The `timestamp` parameter defaults to the current time in milliseconds. When the timestamp changes, the counter is reset to a pseudo-random integer wrapped to 4096. This counter is atomic and threadsafe, meaning that using `Bun.randomUUIDv7()` in many Workers within the same process running at the same timestamp will not have colliding counter values.
 
 The final 8 bytes of the UUID are a cryptographically secure random value. It uses the same random number generator used by `crypto.randomUUID()` (which comes from BoringSSL, which in turn comes from the platform-specific system random number generator usually provided by the underlying hardware).
 

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/cli/filter.md

@@ -1,4 +1,51 @@
-Use the `--filter` flag to execute lifecycle scripts in multiple packages at once:
+The `--filter` (or `-F`) flag is used for selecting packages by pattern in a monorepo. Patterns can be used to match package names or package paths, with full glob syntax support.
+
+Currently `--filter` is supported by `bun install` and `bun outdated`, and can also be used to run scripts for multiple packages at once.
+
+## Matching
+
+### Package Name `--filter <pattern>`
+
+Name patterns select packages based on the package name, as specified in `package.json`. For example, if you have packages `pkg-a`, `pkg-b` and `other`, you can match all packages with `*`, only `pkg-a` and `pkg-b` with `pkg*`, and a specific package by providing the full name of the package.
+
+### Package Path `--filter ./<glob>`
+
+Path patterns are specified by starting the pattern with `./`, and will select all packages in directories that match the pattern. For example, to match all packages in subdirectories of `packages`, you can use `--filter './packages/**'`. To match a package located in `packages/foo`, use `--filter ./packages/foo`.
+
+## `bun install` and `bun outdated`
+
+Both `bun install` and `bun outdated` support the `--filter` flag.
+
+`bun install` by default will install dependencies for all packages in the monorepo. To install dependencies for specific packages, use `--filter`.
+
+Given a monorepo with workspaces `pkg-a`, `pkg-b`, and `pkg-c` under `./packages`:
+
+```bash
+# Install dependencies for all workspaces except `pkg-c`
+$ bun install --filter '!pkg-c'
+
+# Install dependencies for packages in `./packages` (`pkg-a`, `pkg-b`, `pkg-c`)
+$ bun install --filter './packages/*'
+
+# Save as above, but exclude the root package.json
+$ bun install --filter --filter '!./' --filter './packages/*'
+```
+
+Similarly, `bun outdated` will display outdated dependencies for all packages in the monorepo, and `--filter` can be used to restrict the command to a subset of the packages:
+
+```bash
+# Display outdated dependencies for workspaces starting with `pkg-`
+$ bun outdated --filter 'pkg-*'
+
+# Display outdated dependencies for only the root package.json
+$ bun outdated --filter './'
+```
+
+For more information on both these commands, see [`bun install`](https://bun.sh/docs/cli/install) and [`bun outdated`](https://bun.sh/docs/cli/outdated).
+
+## Running scripts with `--filter`
+
+Use the `--filter` flag to execute scripts in multiple packages at once:
 
 ```bash
 bun --filter <pattern> <script>
@@ -24,19 +71,7 @@ bun --filter '*' dev
 Both commands will be run in parallel, and you will see a nice terminal UI showing their respective outputs:
 ![Terminal Output](https://github.com/oven-sh/bun/assets/48869301/2a103e42-9921-4c33-948f-a1ad6e6bac71)
 
-## Matching
-
-`--filter` accepts a pattern to match specific packages, either by name or by path. Patterns have full support for glob syntax.
-
-### Package Name `--filter <pattern>`
-
-Name patterns select packages based on the package name, as specified in `package.json`. For example, if you have packages `pkga`, `pkgb` and `other`, you can match all packages with `*`, only `pkga` and `pkgb` with `pkg*`, and a specific package by providing the full name of the package.
-
-### Package Path `--filter ./<glob>`
-
-Path patterns are specified by starting the pattern with `./`, and will select all packages in directories that match the pattern. For example, to match all packages in subdirectories of `packages`, you can use `--filter './packages/**'`. To match a package located in `pkgs/foo`, use `--filter ./pkgs/foo`.
-
-## Workspaces
+### Running scripts in workspaces
 
 Filters respect your [workspace configuration](https://bun.sh/docs/install/workspaces): If you have a `package.json` file that specifies which packages are part of the workspace,
 `--filter` will be restricted to only these packages. Also, in a workspace you can use `--filter` to run scripts in packages that are located anywhere in the workspace:
@@ -50,8 +85,6 @@ Filters respect your [workspace configuration](https://bun.sh/docs/install/works
 bun run --filter foo myscript
 ```
 
-## Dependency Order
+### Dependency Order
 
 Bun will respect package dependency order when running scripts. Say you have a package `foo` that depends on another package `bar` in your workspace, and both packages have a `build` script. When you run `bun --filter '*' build`, you will notice that `foo` will only start running once `bar` is done.
-
-### Cyclic Dependencies

package/docs/cli/install.md

@@ -81,6 +81,20 @@ Bun supports `"workspaces"` in package.json. For complete documentation refer to
 }
 ```
 
+## Installing dependencies for specific packages
+
+In a monorepo, you can install the dependencies for a subset of packages using the `--filter` flag.
+
+```bash
+# Install dependencies for all workspaces except `pkg-c`
+$ bun install --filter '!pkg-c'
+
+# Install dependencies for only `pkg-a` in `./packages/pkg-a`
+$ bun install --filter './packages/pkg-a'
+```
+
+For more information on filtering with `bun install`, refer to [Package Manager > Filtering](https://bun.sh/docs/cli/install#bun-install-and-bun-outdated)
+
 ## Overrides and resolutions
 
 Bun supports npm's `"overrides"` and Yarn's `"resolutions"` in `package.json`. These are mechanisms for specifying a version range for _metadependencies_—the dependencies of your dependencies. Refer to [Package manager > Overrides and resolutions](https://bun.sh/docs/install/overrides) for complete documentation.

package/docs/cli/outdated.md

@@ -59,3 +59,5 @@ If you want to do the same, but exclude the `./apps/api` workspace:
 ```sh
 $ bun outdated --filter './apps/*' --filter '!./apps/api'
 ```
+
+Refer to [Package Manager > Filtering](https://bun.sh/docs/cli/filter#bun-install-and-bun-outdated) for more information on `--filter`.

package/docs/cli/run.md

@@ -153,7 +153,7 @@ $ bun run --bun vite
 
 ### Filtering
 
-in monorepos containing multiple packages, you can use the `--filter` argument to execute scripts in many packages at once.
+In monorepos containing multiple packages, you can use the `--filter` argument to execute scripts in many packages at once.
 
 Use `bun run --filter <name_pattern> <script>` to execute `<script>` in all packages whose name matches `<name_pattern>`.
 For example, if you have subdirectories containing packages named `foo`, `bar` and `baz`, running
@@ -164,7 +164,7 @@ bun run --filter 'ba*' <script>
 
 will execute `<script>` in both `bar` and `baz`, but not in `foo`.
 
-Find more details in the docs page for [filter](https://bun.sh/docs/cli/filter).
+Find more details in the docs page for [filter](https://bun.sh/docs/cli/filter#running-scripts-with-filter).
 
 ## `bun run -` to pipe code from stdin
 

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/lockfile.md

@@ -100,7 +100,7 @@ $ head -n3 bun.lock
   "workspaces": {
 ```
 
-Once `bun.lock` is generated, Bun will use it for all subsequent installs and updates through commands that read and modify the lockfile. If both lockfiles exist, `bun.lock` will be choosen over `bun.lockb`.
+Once `bun.lock` is generated, Bun will use it for all subsequent installs and updates through commands that read and modify the lockfile. If both lockfiles exist, `bun.lock` will be chosen over `bun.lockb`.
 
 Bun v1.2.0 will switch the default lockfile format to `bun.lock`.
 

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/docs/runtime/shell.md

@@ -102,7 +102,7 @@ The default handling of non-zero exit codes can be configured by calling `.nothr
 import { $ } from "bun";
 // shell promises will not throw, meaning you will have to
 // check for `exitCode` manually on every shell command.
-$.nothrow(); // equivilent to $.throws(false)
+$.nothrow(); // equivalent to $.throws(false)
 
 // default behavior, non-zero exit codes will throw an error
 $.throws(true);

package/package.json

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

package/test.d.ts

@@ -1104,22 +1104,24 @@ declare module "bun:test" {
 		toContainAllValues(expected: unknown): void;
 
 		/**
-     * Asserts that an `object` contain any provided value.
-     *
-     * The value must be an object
-     *
-     * @example
-     * const o = { a: 'foo', b: 'bar', c: 'baz' };
-  `  * expect(o).toContainAnyValues(['qux', 'foo']);
-     * expect(o).toContainAnyValues(['qux', 'bar']);
-     * expect(o).toContainAnyValues(['qux', 'baz']);
-     * expect(o).not.toContainAnyValues(['qux']);
-     * @param expected the expected value
-     */
+		 * Asserts that an `object` contain any provided value.
+		 *
+		 * The value must be an object
+		 *
+		 * @example
+		 * const o = { a: 'foo', b: 'bar', c: 'baz' };
+		 * expect(o).toContainAnyValues(['qux', 'foo']);
+		 * expect(o).toContainAnyValues(['qux', 'bar']);
+		 * expect(o).toContainAnyValues(['qux', 'baz']);
+		 * expect(o).not.toContainAnyValues(['qux']);
+		 * @param expected the expected value
+		 */
 		toContainAnyValues(expected: unknown): void;
 
 		/**
 		 * Asserts that an `object` contains all the provided keys.
+		 *
+		 * @example
 		 * expect({ a: 'foo', b: 'bar', c: 'baz' }).toContainKeys(['a', 'b']);
 		 * expect({ a: 'foo', b: 'bar', c: 'baz' }).toContainKeys(['a', 'b', 'c']);
 		 * expect({ a: 'foo', b: 'bar', c: 'baz' }).not.toContainKeys(['a', 'b', 'e']);