bun-types 1.3.2-canary.20251105T140650 → 1.3.2

package/docs/{api/s3.md → runtime/s3.mdx}

@@ -1,16 +1,19 @@
-Production servers often read, upload, and write files to S3-compatible object storage services instead of the local filesystem. Historically, that means local filesystem APIs you use in development can't be used in production. When you use Bun, things are different.
+---
+title: S3
+description: Bun provides fast, native bindings for interacting with S3-compatible object storage services.
+---
 
-{% callout %}
+Production servers often read, upload, and write files to S3-compatible object storage services instead of the local filesystem. Historically, that means local filesystem APIs you use in development can't be used in production. When you use Bun, things are different.
 
 ### Bun's S3 API is fast
 
-{% image src="https://bun.com/bun-s3-node.gif" alt="Bun's S3 API is fast" caption="Left: Bun v1.1.44. Right: Node.js v23.6.0" /%}
-
-{% /callout %}
+<Frame caption="Left: Bun v1.1.44. Right: Node.js v23.6.0">
+  <img src="/images/bun-s3-node.gif" alt="Bun's S3 API is fast" />
+</Frame>
 
 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
+```ts s3.ts icon="/icons/typescript.svg"
 import { s3, write, S3Client } from "bun";
 
 // Bun.s3 reads environment variables for credentials
@@ -52,7 +55,7 @@ There are several ways to interact with Bun's S3 API.
 
 To explicitly set credentials, pass them to the `Bun.S3Client` constructor.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg"
 import { S3Client } from "bun";
 
 const client = new S3Client({
@@ -74,7 +77,7 @@ const client = new S3Client({
 
 The **`file`** method in `S3Client` returns a **lazy reference to a file on S3**.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg"
 // A lazy reference to a file on S3
 const s3file: S3File = client.file("123.json");
 ```
@@ -85,7 +88,7 @@ Like `Bun.file(path)`, the `S3Client`'s `file` method is synchronous. It does ze
 
 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
+```ts s3.ts icon="/icons/typescript.svg"
 // Read an S3File as text
 const text = await s3file.text();
 
@@ -117,7 +120,7 @@ These helper methods not only simplify the API, they also make it faster.
 
 Writing to S3 is just as simple.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg"
 // Write a string (replacing the file)
 await s3file.write("Hello World!");
 
@@ -146,7 +149,7 @@ await Bun.write(s3file, "Hello World!");
 
 Bun automatically handles multipart uploads for large files and provides streaming capabilities. The same API that works for local files also works for S3 files.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg"
 // Write a large file
 const bigFile = Buffer.alloc(10 * 1024 * 1024); // 10MB
 const writer = s3file.writer({
@@ -166,6 +169,8 @@ for (let i = 0; i < 10; i++) {
 await writer.end();
 ```
 
+---
+
 ## Presigning URLs
 
 When your production service needs to let users upload files to your server, it's often more reliable for the user to upload directly to S3 instead of your server acting as an intermediary.
@@ -174,7 +179,7 @@ To facilitate this, you can presign URLs for S3 files. This generates a URL with
 
 The default behaviour is to generate a `GET` URL that expires in 24 hours. Bun attempts to infer the content type from the file extension. If inference is not possible, it will default to `application/octet-stream`.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg"
 import { s3 } from "bun";
 
 // Generate a presigned URL that expires in 24 hours (default)
@@ -198,7 +203,7 @@ const presignedFile = myFile.presign({
 
 To set an ACL (access control list) on a presigned URL, pass the `acl` option:
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg"
 const url = s3file.presign({
   acl: "public-read",
   expiresIn: 3600,
@@ -222,7 +227,7 @@ You can pass any of the following ACLs:
 
 To set an expiration time for a presigned URL, pass the `expiresIn` option.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg"
 const url = s3file.presign({
   // Seconds
   expiresIn: 3600, // 1 hour
@@ -239,7 +244,7 @@ const url = s3file.presign({
 
 To set the HTTP method for a presigned URL, pass the `method` option.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg"
 const url = s3file.presign({
   method: "PUT",
   // method: "DELETE",
@@ -254,14 +259,14 @@ const url = s3file.presign({
 
 To quickly redirect users to a presigned URL for an S3 file, pass an `S3File` instance to a `Response` object as the body.
 
-```ts
+This will automatically redirect the user to the presigned URL for the S3 file, saving you the memory, time, and bandwidth cost of downloading the file to your server and sending it back to the user.
+
+```ts s3.ts icon="/icons/typescript.svg"
 const response = new Response(s3file);
 console.log(response);
 ```
 
-This will automatically redirect the user to the presigned URL for the S3 file, saving you the memory, time, and bandwidth cost of downloading the file to your server and sending it back to the user.
-
-```ts
+```txt
 Response (0 KB) {
   ok: false,
   url: "",
@@ -275,6 +280,8 @@ Response (0 KB) {
 }
 ```
 
+---
+
 ## Support for S3-Compatible Services
 
 Bun's S3 implementation works with any S3-compatible storage service. Just specify the appropriate endpoint:
@@ -283,7 +290,7 @@ Bun's S3 implementation works with any S3-compatible storage service. Just speci
 
 AWS S3 is the default. You can also pass a `region` option instead of an `endpoint` option for AWS S3.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg"
 import { S3Client } from "bun";
 
 // AWS S3
@@ -300,7 +307,7 @@ const s3 = new S3Client({
 
 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
+```ts s3.ts icon="/icons/typescript.svg" highlight={8}
 import { S3Client } from "bun";
 
 // Google Cloud Storage
@@ -316,7 +323,7 @@ const gcs = new S3Client({
 
 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
+```ts s3.ts icon="/icons/typescript.svg" highlight={8}
 import { S3Client } from "bun";
 
 // CloudFlare R2
@@ -332,7 +339,7 @@ const r2 = new S3Client({
 
 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.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg" highlight={8}
 import { S3Client } from "bun";
 
 const spaces = new S3Client({
@@ -348,7 +355,7 @@ const spaces = new S3Client({
 
 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
+```ts s3.ts icon="/icons/typescript.svg" highlight={10}
 import { S3Client } from "bun";
 
 const minio = new S3Client({
@@ -364,9 +371,9 @@ const minio = new S3Client({
 
 ### Using Bun's S3Client with supabase
 
-To use Bun's S3 client with [supabase](https://supabase.com/), set `endpoint` to the supabase endpoint in the `S3Client` constructor. The supabase endpoint includes your account ID and /storage/v1/s3 path. Make sure to set Enable connection via S3 protocol on in the supabase dashboard in https://supabase.com/dashboard/project/<account-id>/settings/storage and to set the region informed in the same section.
+To use Bun's S3 client with [supabase](https://supabase.com/), set `endpoint` to the supabase endpoint in the `S3Client` constructor. The supabase endpoint includes your account ID and /storage/v1/s3 path. Make sure to set Enable connection via S3 protocol on in the supabase dashboard in `https://supabase.com/dashboard/project/<account-id>/settings/storage` and to set the region informed in the same section.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg" highlight={3-10}
 import { S3Client } from "bun";
 
 const supabase = new S3Client({
@@ -380,9 +387,15 @@ const supabase = new S3Client({
 
 ### Using Bun's S3Client with S3 Virtual Hosted-Style endpoints
 
-When using a S3 Virtual Hosted-Style endpoint, you need to set the `virtualHostedStyle` option to `true` and if no endpoint is provided, Bun will use region and bucket to infer the endpoint to AWS S3, if no region is provided it will use `us-east-1`. If you provide a the endpoint, there are no need to provide the bucket name.
+When using a S3 Virtual Hosted-Style endpoint, you need to set the `virtualHostedStyle` option to `true`.
 
-```ts
+<Note>
+  - If you don’t specify an endpoint, Bun will automatically determine the AWS S3 endpoint using the provided region and
+  bucket. - If no region is specified, Bun defaults to us-east-1. - If you explicitly provide an endpoint, you don’t
+  need to specify a bucket name.
+</Note>
+
+```ts s3.ts icon="/icons/typescript.svg" highlight={17, 25}
 import { S3Client } from "bun";
 
 // AWS S3 endpoint inferred from region and bucket
@@ -390,7 +403,7 @@ const s3 = new S3Client({
   accessKeyId: "access-key",
   secretAccessKey: "secret-key",
   bucket: "my-bucket",
-  virtualHostedStyle: true,
+  virtualHostedStyle: true, // [!code ++]
   // endpoint: "https://my-bucket.s3.us-east-1.amazonaws.com",
   // region: "us-east-1",
 });
@@ -400,7 +413,7 @@ const s3WithEndpoint = new S3Client({
   accessKeyId: "access-key",
   secretAccessKey: "secret-key",
   endpoint: "https://<bucket-name>.s3.<region>.amazonaws.com",
-  virtualHostedStyle: true,
+  virtualHostedStyle: true, // [!code ++]
 });
 
 // Cloudflare R2
@@ -408,10 +421,12 @@ const r2WithEndpoint = new S3Client({
   accessKeyId: "access-key",
   secretAccessKey: "secret-key",
   endpoint: "https://<bucket-name>.<account-id>.r2.cloudflarestorage.com",
-  virtualHostedStyle: true,
+  virtualHostedStyle: true, // [!code ++]
 });
 ```
 
+---
+
 ## Credentials
 
 Credentials are one of the hardest parts of using S3, and we've tried to make it as easy as possible. By default, Bun reads the following environment variables for credentials.
@@ -436,7 +451,7 @@ If the `S3_*` environment variable is not set, Bun will also check for the `AWS_
 | `bucket`          | `AWS_BUCKET`                  |
 | `sessionToken`    | `AWS_SESSION_TOKEN`           |
 
-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 environment variables are read from [`.env` files](/runtime/environment-variables) or from the process environment at initialization time (`process.env` is not used for this).
 
 These defaults are overridden by the options you pass to `s3.file(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.file()` function without having to specify all the credentials again.
 
@@ -444,7 +459,7 @@ These defaults are overridden by the options you pass to `s3.file(credentials)`,
 
 When you're not using environment variables or using multiple buckets, you can create a `S3Client` object to explicitly set credentials.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg" highlight={3-11}
 import { S3Client } from "bun";
 
 const client = new S3Client({
@@ -474,13 +489,14 @@ await file.delete();
 
 To upload or write a file to S3, call `write` on the `S3Client` instance.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg" highlight={8, 9}
 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 client.write("my-file.txt", "Hello World!");
 await client.write("my-file.txt", new Response("Hello World!"));
 
@@ -492,7 +508,7 @@ await client.write("my-file.txt", new Response("Hello World!"));
 
 To delete a file from S3, call `delete` on the `S3Client` instance.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg" highlight={7}
 const client = new Bun.S3Client({
   accessKeyId: "your-access-key",
   secretAccessKey: "your-secret-key",
@@ -508,7 +524,7 @@ await client.delete("my-file.txt");
 
 To check if a file exists in S3, call `exists` on the `S3Client` instance.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg" highlight={7}
 const client = new Bun.S3Client({
   accessKeyId: "your-access-key",
   secretAccessKey: "your-secret-key",
@@ -524,7 +540,7 @@ const exists = await client.exists("my-file.txt");
 
 `S3File` instances are created by calling the `S3Client` instance method or the `s3.file()` function. Like `Bun.file()`, `S3File` instances are lazy. They don't refer to something that necessarily exists at the time of creation. That's why all the methods that don't involve network requests are fully synchronous.
 
-```ts
+```ts Type Reference icon="/icons/typescript.svg"  expandable
 interface S3File extends Blob {
   slice(start: number, end?: number): S3File;
   exists(): Promise<boolean>;
@@ -536,14 +552,7 @@ interface S3File extends Blob {
   arrayBuffer(): Promise<ArrayBuffer>;
   stream(options: S3Options): ReadableStream;
   write(
-    data:
-      | string
-      | Uint8Array
-      | ArrayBuffer
-      | Blob
-      | ReadableStream
-      | Response
-      | Request,
+    data: string | Uint8Array | ArrayBuffer | Blob | ReadableStream | Response | Request,
     options?: BlobPropertyBag,
   ): Promise<number>;
 
@@ -580,7 +589,7 @@ That means using `S3File` instances with `fetch()`, `Response`, and other web AP
 
 To read a partial range of a file, you can use the `slice` method.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg"  highlight={1}
 const partial = s3file.slice(0, 1024);
 
 // Read the partial range as a Uint8Array
@@ -596,7 +605,7 @@ Internally, this works by using the HTTP `Range` header to request only the byte
 
 To delete a file from S3, you can use the `delete` method.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg" highlight={1}
 await s3file.delete();
 // await s3File.unlink();
 ```
@@ -624,7 +633,7 @@ The `S3Client` class provides several static methods for interacting with S3.
 
 To write data directly to a path in the bucket, you can use the `S3Client.write` static method.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg" highlight={12, 15-18, 22, 25-29}
 import { S3Client } from "bun";
 
 const credentials = {
@@ -662,7 +671,7 @@ This is equivalent to calling `new S3Client(credentials).write("my-file.txt", "H
 
 To generate a presigned URL for an S3 file, you can use the `S3Client.presign` static method.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg" highlight={11-14}
 import { S3Client } from "bun";
 
 const credentials = {
@@ -685,10 +694,10 @@ This is equivalent to calling `new S3Client(credentials).presign("my-file.txt",
 
 To list some or all (up to 1,000) objects in a bucket, you can use the `S3Client.list` static method.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg" highlight={12, 15-20, 24-29}
 import { S3Client } from "bun";
 
-const credentials = {
+const credentials = { ... }
   accessKeyId: "your-access-key",
   secretAccessKey: "your-secret-key",
   bucket: "my-bucket",
@@ -724,7 +733,7 @@ This is equivalent to calling `new S3Client(credentials).list()`.
 
 To check if an S3 file exists, you can use the `S3Client.exists` static method.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg"  highlight={11}
 import { S3Client } from "bun";
 
 const credentials = {
@@ -740,12 +749,13 @@ const exists = await S3Client.exists("my-file.txt", credentials);
 
 The same method also works on `S3File` instances.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg" highlight=7}
 import { s3 } from "bun";
 
 const s3file = s3.file("my-file.txt", {
-  ...credentials,
+  // ...credentials,
 });
+
 const exists = await s3file.exists();
 ```
 
@@ -753,7 +763,7 @@ const exists = await s3file.exists();
 
 To quickly check the size of S3 file without downloading it, you can use the `S3Client.size` static method.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg" highlight={11}
 import { S3Client } from "bun";
 
 const credentials = {
@@ -773,7 +783,7 @@ This is equivalent to calling `new S3Client(credentials).size("my-file.txt")`.
 
 To get the size, etag, and other metadata of an S3 file, you can use the `S3Client.stat` static method.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg"
 import { S3Client } from "bun";
 
 const credentials = {
@@ -785,19 +795,22 @@ const credentials = {
 };
 
 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",
-// }
+```
+
+```txt
+{
+  etag: "\"7a30b741503c0b461cc14157e2df4ad8\"",
+  lastModified: 2025-01-07T00:19:10.000Z,
+  size: 1024,
+  type: "text/plain;charset=utf-8",
+}
 ```
 
 ### `S3Client.delete` (static)
 
 To delete an S3 file, you can use the `S3Client.delete` static method.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg" highlight={10, 15}
 import { S3Client } from "bun";
 
 const credentials = {
@@ -819,14 +832,14 @@ await S3Client.unlink("my-file.txt", credentials);
 
 To make it easier to use the same code for local files and S3 files, the `s3://` protocol is supported in `fetch` and `Bun.file()`.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg"
 const response = await fetch("s3://my-bucket/my-file.txt");
 const file = Bun.file("s3://my-bucket/my-file.txt");
 ```
 
 You can additionally pass `s3` options to the `fetch` and `Bun.file` functions.
 
-```ts
+```ts s3.ts icon="/icons/typescript.svg" highlight={2-6}
 const response = await fetch("s3://my-bucket/my-file.txt", {
   s3: {
     accessKeyId: "your-access-key",
@@ -834,7 +847,7 @@ const response = await fetch("s3://my-bucket/my-file.txt", {
     endpoint: "https://s3.us-east-1.amazonaws.com",
   },
   headers: {
-    "range": "bytes=0-1023",
+    range: "bytes=0-1023",
   },
 });
 ```

package/docs/{api/secrets.md → runtime/secrets.mdx}

@@ -1,8 +1,13 @@
+---
+title: Secrets
+description: Use Bun's Secrets API to store and retrieve sensitive credentials securely
+---
+
 Store and retrieve sensitive credentials securely using the operating system's native credential storage APIs.
 
-**Experimental:** This API is new and experimental. It may change in the future.
+<Warning>This API is new and experimental. It may change in the future.</Warning>
 
-```typescript
+```typescript index.ts icon="/icons/typescript.svg"
 import { secrets } from "bun";
 
 const githubToken = await secrets.get({
@@ -12,7 +17,7 @@ const githubToken = await secrets.get({
 
 if (!githubToken) {
   const response = await fetch("https://api.github.com/name", {
-    headers: { "Authorization": `token ${githubToken}` },
+    headers: { Authorization: `token ${githubToken}` },
   });
   console.log("Please enter your GitHub token");
 } else {
@@ -25,6 +30,8 @@ if (!githubToken) {
 }
 ```
 
+---
+
 ## Overview
 
 `Bun.secrets` provides a cross-platform API for managing sensitive credentials that CLI tools and development applications typically store in plaintext files like `~/.npmrc`, `~/.aws/credentials`, or `.env` files. It uses:
@@ -35,7 +42,12 @@ if (!githubToken) {
 
 All operations are asynchronous and non-blocking, running on Bun's threadpool.
 
-Note: in the future, we may add an additional `provider` option to make this better for production deployment secrets, but today this API is mostly useful for local development tools.
+<Note>
+  In the future, we may add an additional `provider` option to make this better for production deployment secrets, but
+  today this API is mostly useful for local development tools.
+</Note>
+
+---
 
 ## API
 
@@ -112,6 +124,8 @@ const deleted = await Bun.secrets.delete({
 
 - `Promise<boolean>` - `true` if a credential was deleted, `false` if not found
 
+---
+
 ## Examples
 
 ### Storing CLI Tool Credentials
@@ -143,7 +157,7 @@ const token = await Bun.secrets.get({
 if (token) {
   const response = await fetch("https://api.github.com/name", {
     headers: {
-      "Authorization": `token ${token}`,
+      Authorization: `token ${token}`,
     },
   });
 }
@@ -218,6 +232,8 @@ await Bun.secrets.set({
 // The old password is replaced
 ```
 
+---
+
 ## Platform Behavior
 
 ### macOS (Keychain)
@@ -259,6 +275,8 @@ await Bun.secrets.set({
   - macOS: Keychain Access must be available
   - Windows: Credential Manager service must be enabled
 
+---
+
 ## Comparison with Environment Variables
 
 Unlike environment variables, `Bun.secrets`:
@@ -271,6 +289,8 @@ Unlike environment variables, `Bun.secrets`:
 - ❌ Requires OS credential service
 - ❌ Not very useful for deployment secrets (use environment variables in production)
 
+---
+
 ## Best Practices
 
 1. **Use descriptive service names**: Match the tool or application name
@@ -294,6 +314,8 @@ Unlike environment variables, `Bun.secrets`:
    - ✅ Personal API keys for testing
    - ❌ Production servers (use proper secret management)
 
+---
+
 ## TypeScript
 
 ```typescript
@@ -312,8 +334,3 @@ namespace Bun {
   const secrets: Secrets;
 }
 ```
-
-## See Also
-
-- [Environment Variables](./env.md) - For deployment configuration
-- [Bun.password](./password.md) - For password hashing and verification

package/docs/{api/semver.md → runtime/semver.mdx}

@@ -1,12 +1,17 @@
+---
+title: Semver
+description: Use Bun's semantic versioning API
+---
+
 Bun implements a semantic versioning API which can be used to compare versions and determine if a version is compatible with another range of versions. The versions and ranges are designed to be compatible with `node-semver`, which is used by npm clients.
 
 It's about 20x faster than `node-semver`.
 
-![Benchmark](https://github.com/oven-sh/bun/assets/709451/94746adc-8aba-4baf-a143-3c355f8e0f78)
+<Frame>![Benchmark](https://github.com/oven-sh/bun/assets/709451/94746adc-8aba-4baf-a143-3c355f8e0f78)</Frame>
 
-Currently, this API provides two functions :
+Currently, this API provides two functions:
 
-#### `Bun.semver.satisfies(version: string, range: string): boolean`
+## `Bun.semver.satisfies(version: string, range: string): boolean`
 
 Returns `true` if `version` satisfies `range`, otherwise `false`.
 
@@ -31,7 +36,7 @@ semver.satisfies("1.0.0", "1.0.0 - 1.0.1"); // true
 
 If `range` is invalid, it returns false. If `version` is invalid, it returns false.
 
-#### `Bun.semver.order(versionA: string, versionB: string): 0 | 1 | -1`
+## `Bun.semver.order(versionA: string, versionB: string): 0 | 1 | -1`
 
 Returns `0` if `versionA` and `versionB` are equal, `1` if `versionA` is greater than `versionB`, and `-1` if `versionA` is less than `versionB`.