bun-types 1.3.2-canary.20251106T140813 → 1.3.2

package/docs/guides/runtime/import-json.mdx

@@ -0,0 +1,46 @@
+---
+title: Import a JSON file
+sidebarTitle: Import JSON
+mode: center
+---
+
+Bun natively supports `.json` imports.
+
+```json package.json icon="file-json"
+{
+  "name": "bun",
+  "version": "1.0.0",
+  "author": {
+    "name": "John Dough",
+    "email": "john@dough.com"
+  }
+}
+```
+
+---
+
+Import the file like any other source file.
+
+```ts data.ts icon="/icons/typescript.svg"
+import data from "./package.json";
+
+data.name; // => "bun"
+data.version; // => "1.0.0"
+data.author.name; // => "John Dough"
+```
+
+---
+
+Bun also supports [Import Attributes](https://github.com/tc39/proposal-import-attributes/) and [JSON modules](https://github.com/tc39/proposal-json-modules) syntax.
+
+```ts data.ts icon="/icons/typescript.svg"
+import data from "./package.json" with { type: "json" };
+
+data.name; // => "bun"
+data.version; // => "1.0.0"
+data.author.name; // => "John Dough"
+```
+
+---
+
+See [Docs > Runtime > TypeScript](https://bun.com/docs/runtime/typescript) for more information on using TypeScript with Bun.

package/docs/guides/runtime/import-toml.mdx

@@ -0,0 +1,32 @@
+---
+title: Import a TOML file
+sidebarTitle: Import TOML
+mode: center
+---
+
+Bun natively supports importing `.toml` files.
+
+```toml data.toml icon="file-code"
+name = "bun"
+version = "1.0.0"
+
+[author]
+name = "John Dough"
+email = "john@dough.com"
+```
+
+---
+
+Import the file like any other source file.
+
+```ts data.ts icon="/icons/typescript.svg"
+import data from "./data.toml";
+
+data.name; // => "bun"
+data.version; // => "1.0.0"
+data.author.name; // => "John Dough"
+```
+
+---
+
+See [Docs > Runtime > TypeScript](https://bun.com/docs/runtime/typescript) for more information on using TypeScript with Bun.

package/docs/guides/runtime/import-yaml.mdx

@@ -0,0 +1,104 @@
+---
+title: Import a YAML file
+sidebarTitle: Import YAML
+mode: center
+---
+
+Bun natively supports `.yaml` and `.yml` imports.
+
+```yaml config.yaml icon="file-code"
+database:
+  host: localhost
+  port: 5432
+  name: myapp
+
+server:
+  port: 3000
+  timeout: 30
+
+features:
+  auth: true
+  rateLimit: true
+```
+
+---
+
+Import the file like any other source file.
+
+```ts config.ts icon="/icons/typescript.svg"
+import config from "./config.yaml";
+
+config.database.host; // => "localhost"
+config.server.port; // => 3000
+config.features.auth; // => true
+```
+
+---
+
+You can also use named imports to destructure top-level properties:
+
+```ts config.ts icon="/icons/typescript.svg"
+import { database, server, features } from "./config.yaml";
+
+console.log(database.name); // => "myapp"
+console.log(server.timeout); // => 30
+console.log(features.rateLimit); // => true
+```
+
+---
+
+Bun also supports [Import Attributes](https://github.com/tc39/proposal-import-attributes) syntax:
+
+```ts config.ts icon="/icons/typescript.svg"
+import config from "./config.yaml" with { type: "yaml" };
+
+config.database.port; // => 5432
+```
+
+---
+
+For parsing YAML strings at runtime, use `Bun.YAML.parse()`:
+
+```ts config.ts icon="/icons/typescript.svg"
+const yamlString = `
+name: John Doe
+age: 30
+hobbies:
+  - reading
+  - coding
+`;
+
+const data = Bun.YAML.parse(yamlString);
+console.log(data.name); // => "John Doe"
+console.log(data.hobbies); // => ["reading", "coding"]
+```
+
+---
+
+## TypeScript Support
+
+To add TypeScript support for your YAML imports, create a declaration file with `.d.ts` appended to the YAML filename (e.g., `config.yaml` → `config.yaml.d.ts`);
+
+```ts config.yaml.d.ts icon="/icons/typescript.svg"
+const contents: {
+  database: {
+    host: string;
+    port: number;
+    name: string;
+  };
+  server: {
+    port: number;
+    timeout: number;
+  };
+  features: {
+    auth: boolean;
+    rateLimit: boolean;
+  };
+};
+
+export = contents;
+```
+
+---
+
+See [Docs > API > YAML](https://bun.com/docs/api/yaml) for complete documentation on YAML support in Bun.

package/docs/guides/runtime/read-env.mdx

@@ -0,0 +1,37 @@
+---
+title: Read environment variables
+sidebarTitle: Read env variables
+mode: center
+---
+
+The current environment variables can be accessed via `process.env`.
+
+```ts index.ts icon="/icons/typescript.svg"
+process.env.API_TOKEN; // => "secret"
+```
+
+---
+
+Bun also exposes these variables via `Bun.env`, which is a simple alias of `process.env`.
+
+```ts index.ts icon="/icons/typescript.svg"
+Bun.env.API_TOKEN; // => "secret"
+```
+
+---
+
+To print all currently-set environment variables to the command line, run `bun --print process.env`. This is useful for debugging.
+
+```sh terminal icon="terminal"
+bun --print process.env
+```
+
+```txt
+BAZ=stuff
+FOOBAR=aaaaaa
+<lots more lines>
+```
+
+---
+
+See [Docs > Runtime > Environment variables](https://bun.com/docs/runtime/env) for more information on using environment variables with Bun.

package/docs/guides/runtime/set-env.mdx

@@ -0,0 +1,51 @@
+---
+title: Set environment variables
+sidebarTitle: Set env variables
+mode: center
+---
+
+The current environment variables can be accessed via `process.env` or `Bun.env`.
+
+```ts index.ts icon="/icons/typescript.svg"
+Bun.env.API_TOKEN; // => "secret"
+process.env.API_TOKEN; // => "secret"
+```
+
+---
+
+Set these variables in a `.env` file.
+
+Bun reads the following files automatically (listed in order of increasing precedence).
+
+- `.env`
+- `.env.production`, `.env.development`, `.env.test` (depending on value of `NODE_ENV`)
+- `.env.local` (not loaded when `NODE_ENV=test`)
+
+```txt .env icon="settings"
+FOO=hello
+BAR=world
+```
+
+---
+
+Variables can also be set via the command line.
+
+<CodeGroup>
+
+```sh Linux/macOS icon="terminal"
+FOO=helloworld bun run dev
+```
+
+```sh Windows icon="windows"
+# Using CMD
+set FOO=helloworld && bun run dev
+
+# Using PowerShell
+$env:FOO="helloworld"; bun run dev
+```
+
+</CodeGroup>
+
+---
+
+See [Docs > Runtime > Environment variables](https://bun.com/docs/runtime/env) for more information on using environment variables with Bun.

package/docs/guides/runtime/shell.mdx

@@ -0,0 +1,42 @@
+---
+title: Run a Shell Command
+sidebarTitle: Run shell command
+mode: center
+---
+
+Bun Shell is a cross-platform bash-like shell built in to Bun.
+
+It provides a simple way to run shell commands in JavaScript and TypeScript. To get started, import the `$` function from the `bun` package and use it to run shell commands.
+
+```ts foo.ts icon="/icons/typescript.svg"
+import { $ } from "bun";
+
+await $`echo Hello, world!`; // => "Hello, world!"
+```
+
+---
+
+The `$` function is a tagged template literal that runs the command and returns a promise that resolves with the command's output.
+
+```ts foo.ts icon="/icons/typescript.svg"
+import { $ } from "bun";
+
+const output = await $`ls -l`.text();
+console.log(output);
+```
+
+---
+
+To get each line of the output as an array, use the `lines` method.
+
+```ts foo.ts icon="/icons/typescript.svg"
+import { $ } from "bun";
+
+for await (const line of $`ls -l`.lines()) {
+  console.log(line);
+}
+```
+
+---
+
+See [Docs > API > Shell](https://bun.com/docs/runtime/shell) for complete documentation.

package/docs/guides/runtime/timezone.mdx

@@ -0,0 +1,38 @@
+---
+title: Set a time zone in Bun
+sidebarTitle: Set time zone
+mode: center
+---
+
+Bun supports programmatically setting a default time zone for the lifetime of the `bun` process. To do set, set the value of the `TZ` environment variable to a [valid timezone identifier](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+
+<Note>
+When running a file with `bun`, the timezone defaults to your system's configured local time zone.
+
+When running tests with `bun test`, the timezone is set to `UTC` to make tests more deterministic.
+
+</Note>
+
+```ts process.ts icon="/icons/typescript.svg"
+process.env.TZ = "America/New_York";
+```
+
+---
+
+Alternatively, this can be set from the command line when running a Bun command.
+
+```sh terminal icon="terminal"
+TZ=America/New_York bun run dev
+```
+
+---
+
+Once `TZ` is set, any `Date` instances will have that time zone. By default all dates use your system's configured time zone.
+
+```ts process.ts icon="/icons/typescript.svg"
+new Date().getHours(); // => 18
+
+process.env.TZ = "America/New_York";
+
+new Date().getHours(); // => 21
+```

package/docs/guides/runtime/tsconfig-paths.mdx

@@ -0,0 +1,31 @@
+---
+title: Re-map import paths
+sidebarTitle: Re-map import paths
+mode: center
+---
+
+Bun reads the `paths` field in your `tsconfig.json` to re-write import paths. This is useful for aliasing package names or avoiding long relative paths.
+
+```json tsconfig.json icon="file-json"
+{
+  "compilerOptions": {
+    "paths": {
+      "my-custom-name": ["zod"],
+      "@components/*": ["./src/components/*"]
+    }
+  }
+}
+```
+
+---
+
+With the above `tsconfig.json`, the following imports will be re-written:
+
+```ts tsconfig.ts icon="/icons/typescript.svg"
+import { z } from "my-custom-name"; // imports from "zod"
+import { Button } from "@components/Button"; // imports from "./src/components/Button"
+```
+
+---
+
+See [Docs > Runtime > TypeScript](https://bun.com/docs/runtime/typescript) for more information on using TypeScript with Bun.

package/docs/guides/runtime/typescript.mdx

@@ -0,0 +1,51 @@
+---
+title: Install TypeScript declarations for Bun
+sidebarTitle: TypeScript types
+mode: center
+---
+
+To install TypeScript definitions for Bun's built-in APIs in your project, install `@types/bun`.
+
+```sh terminal icon="terminal"
+bun add -d @types/bun # dev dependency
+```
+
+---
+
+Below is the full set of recommended `compilerOptions` for a Bun project. With this `tsconfig.json`, you can use top-level await, extensioned or extensionless imports, and JSX.
+
+```json package.json icon="file-json"
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}
+```
+
+---
+
+Refer to [Ecosystem > TypeScript](https://bun.com/docs/runtime/typescript) for a complete guide to TypeScript support in Bun.

package/docs/guides/runtime/vscode-debugger.mdx

@@ -0,0 +1,48 @@
+---
+title: Debugging Bun with the VS Code extension
+sidebarTitle: VS Code debugger
+mode: center
+---
+
+<Note>
+  VSCode extension support is currently buggy. We recommend the [Web
+  Debugger](https://bun.com/guides/runtime/web-debugger) for now.
+</Note>
+
+Bun speaks the [WebKit Inspector Protocol](https://github.com/oven-sh/bun/blob/main/packages/bun-inspector-protocol/src/protocol/jsc/index.d.ts) so you can debug your code with an interactive debugger.
+
+---
+
+To install the extension, visit the [Bun for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=oven.bun-vscode) page on the VS Code marketplace website, then click Install.
+
+<Frame>![VS Code extension](https://github.com/oven-sh/bun/assets/3084745/7c8c80e6-d49e-457a-a45e-45ebed946d56)</Frame>
+
+---
+
+Alternatively, search `bun-vscode` in the Extensions tab of VS Code.
+
+<Frame>![VS Code extension](https://github.com/oven-sh/bun/assets/3084745/664b4c40-944c-4076-a4c2-f812aebd3dc9)</Frame>
+
+---
+
+Make sure you are installing the extension published by the verified Oven organization.
+
+<Frame>![VS Code extension](https://github.com/oven-sh/bun/assets/3084745/73e6b09f-9ff1-4d85-b725-c5eb7215b6ae)</Frame>
+
+---
+
+Once installed, two new Bun-specific commands will appear in the Command Palette. To open the palette, click View > Command Palette, or type `Ctrl+Shift+P` (Windows, Linux) or `Cmd+Shift+P` on (Mac).
+
+---
+
+The `Bun: Run File` command will execute your code and print the output to the Debug Console in VS Code. Breakpoints will be ignored; this is similar to executing the file with `bun <file>` from the command line.
+
+<Frame>![VS Code extension](https://github.com/oven-sh/bun/assets/3084745/1b2c7fd9-fbb9-486a-84d0-eb7ec135ded3)</Frame>
+
+---
+
+The `Bun: Debug File` command will execute your code and print the output to the Debug Console in VS Code. You can set breakpoints in your code by clicking to the left of a line number; a red dot should appear.
+
+When you run the file with `Bun: Debug File`, execution will pause at the breakpoint. You can inspect the variables in scope and step through the code line-by-line using the VS Code controls.
+
+<Frame>![VS Code extension](https://github.com/oven-sh/bun/assets/3084745/c579a36c-eb21-4a58-bc9c-74612aad82af)</Frame>

package/docs/guides/runtime/web-debugger.mdx

@@ -0,0 +1,103 @@
+---
+title: Debugging Bun with the web debugger
+sidebarTitle: Web debugger
+mode: center
+---
+
+Bun speaks the [WebKit Inspector Protocol](https://github.com/oven-sh/bun/blob/main/packages/bun-vscode/types/jsc.d.ts). To enable debugging when running code with Bun, use the `--inspect` flag. For demonstration purposes, consider the following simple web server.
+
+```ts server.ts icon="/icons/typescript.svg"
+Bun.serve({
+  fetch(req) {
+    console.log(req.url);
+    return new Response("Hello, world!");
+  },
+});
+```
+
+---
+
+Let's run this file with the `--inspect` flag.
+
+This automatically starts a WebSocket server on an available port that can be used to introspect the running Bun process. Various debugging tools can connect to this server to provide an interactive debugging experience.
+
+Bun hosts a web-based debugger at [debug.bun.sh](https://debug.bun.sh). It is a modified version of WebKit's [Web Inspector Interface](https://webkit.org/web-inspector/web-inspector-interface/), which will look familiar to Safari users.
+
+```sh terminal icon="terminal"
+bun --inspect server.ts
+```
+
+```txt
+------------------ Bun Inspector ------------------
+Listening at:
+  ws://localhost:6499/0tqxs9exrgrm
+
+Inspect in browser:
+  https://debug.bun.sh/#localhost:6499/0tqxs9exrgrm
+------------------ Bun Inspector ------------------
+```
+
+---
+
+Open the provided `debug.bun.sh` URL in your browser to start a debugging session. From this interface, you'll be able to view the source code of the running file, view and set breakpoints, and execute code with the built-in console.
+
+<Frame>
+  ![Screenshot of Bun debugger, Console
+  tab](https://github.com/oven-sh/bun/assets/3084745/e6a976a8-80cc-4394-8925-539025cc025d)
+</Frame>
+
+---
+
+Let's set a breakpoint. Navigate to the Sources tab; you should see the code from earlier. Click on the line number `3` to set a breakpoint on our `console.log(req.url)` statement.
+
+<Frame>
+  ![screenshot of Bun debugger](https://github.com/oven-sh/bun/assets/3084745/3b69c7e9-25ff-4f9d-acc4-caa736862935)
+</Frame>
+
+---
+
+Then visit [`http://localhost:3000`](http://localhost:3000) in your web browser. This will send an HTTP request to our `localhost` web server. It will seem like the page isn't loading. Why? Because the program has paused execution at the breakpoint we set earlier.
+
+Note how the UI has changed.
+
+<Frame>
+  ![screenshot of Bun debugger](https://github.com/oven-sh/bun/assets/3084745/8b565e58-5445-4061-9bc4-f41090dfe769)
+</Frame>
+
+---
+
+At this point there's a lot we can do to introspect the current execution environment. We can use the console at the bottom to run arbitrary code in the context of the program, with full access to the variables in scope at our breakpoint.
+
+<Frame>
+  ![Bun debugger console](https://github.com/oven-sh/bun/assets/3084745/f4312b76-48ba-4a7d-b3b6-6205968ac681)
+</Frame>
+
+---
+
+On the right side of the Sources pane, we can see all local variables currently in scope, and drill down to see their properties and methods. Here, we're inspecting the `req` variable.
+
+<Frame>
+  ![Bun debugger variables panel](https://github.com/oven-sh/bun/assets/3084745/63d7f843-5180-489c-aa94-87c486e68646)
+</Frame>
+
+---
+
+In the upper left of the Sources pane, we can control the execution of the program.
+
+<Frame>
+  ![Bun debugger controls](https://github.com/oven-sh/bun/assets/3084745/41b76deb-7371-4461-9d5d-81b5a6d2f7a4)
+</Frame>
+
+---
+
+Here's a cheat sheet explaining the functions of the control flow buttons.
+
+- _Continue script execution_ — continue running the program until the next breakpoint or exception.
+- _Step over_ — The program will continue to the next line.
+- _Step into_ — If the current statement contains a function call, the debugger will "step into" the called function.
+- _Step out_ — If the current statement is a function call, the debugger will finish executing the call, then "step out" of the function to the location where it was called.
+
+<Frame>
+  ![Debugger control buttons cheat
+  sheet](https://github-production-user-asset-6210df.s3.amazonaws.com/3084745/261510346-6a94441c-75d3-413a-99a7-efa62365f83d.png)
+</Frame>

package/docs/guides/streams/node-readable-to-arraybuffer.mdx

@@ -0,0 +1,13 @@
+---
+title: Convert a Node.js Readable to an ArrayBuffer
+sidebarTitle: Readable to ArrayBuffer
+mode: center
+---
+
+To convert a Node.js `Readable` stream to an `ArrayBuffer` in Bun, you can create a new `Response` object with the stream as the body, then use `arrayBuffer()` to read the stream into an `ArrayBuffer`.
+
+```ts
+import { Readable } from "stream";
+const stream = Readable.from(["Hello, ", "world!"]);
+const buf = await new Response(stream).arrayBuffer();
+```

package/docs/guides/streams/node-readable-to-blob.mdx

@@ -0,0 +1,13 @@
+---
+title: Convert a Node.js Readable to a Blob
+sidebarTitle: Readable to Blob
+mode: center
+---
+
+To convert a Node.js `Readable` stream to a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) in Bun, you can create a new [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object with the stream as the body, then use [`response.blob()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/blob) to read the stream into a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob).
+
+```ts
+import { Readable } from "stream";
+const stream = Readable.from(["Hello, ", "world!"]);
+const blob = await new Response(stream).blob();
+```

package/docs/guides/streams/node-readable-to-json.mdx

@@ -0,0 +1,14 @@
+---
+title: Convert a Node.js Readable to JSON
+sidebarTitle: Readable to JSON
+mode: center
+---
+
+To convert a Node.js `Readable` stream to a JSON object in Bun, you can create a new [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object with the stream as the body, then use [`response.json()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/json) to read the stream into a JSON object.
+
+```ts
+import { Readable } from "stream";
+const stream = Readable.from([JSON.stringify({ hello: "world" })]);
+const json = await new Response(stream).json();
+console.log(json); // { hello: "world" }
+```

package/docs/guides/streams/node-readable-to-string.mdx

@@ -0,0 +1,14 @@
+---
+title: Convert a Node.js Readable to a string
+sidebarTitle: Readable to string
+mode: center
+---
+
+To convert a Node.js `Readable` stream to a string in Bun, you can create a new [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object with the stream as the body, then use [`response.text()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/text) to read the stream into a string.
+
+```ts
+import { Readable } from "stream";
+const stream = Readable.from([Buffer.from("Hello, world!")]);
+const text = await new Response(stream).text();
+console.log(text); // "Hello, world!"
+```

package/docs/guides/streams/node-readable-to-uint8array.mdx

@@ -0,0 +1,13 @@
+---
+title: Convert a Node.js Readable to an Uint8Array
+sidebarTitle: Readable to Uint8Array
+mode: center
+---
+
+To convert a Node.js `Readable` stream to an `Uint8Array` in Bun, you can create a new `Response` object with the stream as the body, then use `bytes()` to read the stream into an `Uint8Array`.
+
+```ts
+import { Readable } from "stream";
+const stream = Readable.from(["Hello, ", "world!"]);
+const buf = await new Response(stream).bytes();
+```

package/docs/guides/streams/to-array.mdx

@@ -0,0 +1,16 @@
+---
+title: Convert a ReadableStream to an array of chunks
+sidebarTitle: Stream to array
+mode: center
+---
+
+Bun provides a number of convenience functions for reading the contents of a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) into different formats. The `Bun.readableStreamToArray` function reads the contents of a `ReadableStream` to an array of chunks.
+
+```ts
+const stream = new ReadableStream();
+const str = await Bun.readableStreamToArray(stream);
+```
+
+---
+
+See [Docs > API > Utils](https://bun.com/docs/api/utils#bun-readablestreamto) for documentation on Bun's other `ReadableStream` conversion functions.