bun-types 1.3.2-canary.20251104T140728 → 1.3.2-canary.20251106T140813

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

@@ -1,30 +0,0 @@
----
-name: Import a TOML file
----
-
-Bun natively supports importing `.toml` files.
-
-```toml#data.toml
-name = "bun"
-version = "1.0.0"
-
-[author]
-name = "John Dough"
-email = "john@dough.com"
-```
-
----
-
-Import the file like any other source file.
-
-```ts
-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.md

@@ -1,102 +0,0 @@
----
-name: Import a YAML file
----
-
-Bun natively supports `.yaml` and `.yml` imports.
-
-```yaml#config.yaml
-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
-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
-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
-import config from "./config.yaml" with { type: "yaml" };
-
-config.database.port; // => 5432
-```
-
----
-
-For parsing YAML strings at runtime, use `Bun.YAML.parse()`:
-
-```ts
-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
-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.md

@@ -1,32 +0,0 @@
----
-name: Read environment variables
----
-
-The current environment variables can be accessed via `process.env`.
-
-```ts
-process.env.API_TOKEN; // => "secret"
-```
-
----
-
-Bun also exposes these variables via `Bun.env`, which is a simple alias of `process.env`.
-
-```ts
-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
-$ bun --print process.env
-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.md

@@ -1,47 +0,0 @@
----
-name: Set environment variables
----
-
-The current environment variables can be accessed via `process.env` or `Bun.env`.
-
-```ts
-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
-FOO=hello
-BAR=world
-```
-
----
-
-Variables can also be set via the command line.
-
-{% codetabs %}
-
-```sh#Linux/macOS
-$ FOO=helloworld bun run dev
-```
-
-```sh#Windows
-# Using CMD
-$ set FOO=helloworld && bun run dev
-
-# Using PowerShell
-$ $env:FOO="helloworld"; bun run dev
-```
-
-## {% /codetabs %}
-
-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.md

@@ -1,40 +0,0 @@
----
-name: Run a Shell Command
----
-
-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
-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
-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
-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.md

@@ -1,35 +0,0 @@
----
-name: Set a time zone in Bun
----
-
-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).
-
-{% callout %}
-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.
-{% /callout %}
-
-```ts
-process.env.TZ = "America/New_York";
-```
-
----
-
-Alternatively, this can be set from the command line when running a Bun command.
-
-```sh
-$ 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
-new Date().getHours(); // => 18
-
-process.env.TZ = "America/New_York";
-
-new Date().getHours(); // => 21
-```

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

@@ -1,29 +0,0 @@
----
-name: Re-map import paths
----
-
-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
-{
-  "compilerOptions": {
-    "paths": {
-      "my-custom-name": ["zod"],
-      "@components/*": ["./src/components/*"]
-    }
-  }
-}
-```
-
----
-
-With the above `tsconfig.json`, the following imports will be re-written:
-
-```ts
-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.md

@@ -1,49 +0,0 @@
----
-name: Install TypeScript declarations for Bun
----
-
-To install TypeScript definitions for Bun's built-in APIs in your project, install `@types/bun`.
-
-```sh
-$ 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.
-
-```jsonc
-{
-  "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.md

@@ -1,47 +0,0 @@
----
-name: Debugging Bun with the VS Code extension
----
-
-{% 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.
-
-{% image src="https://github.com/oven-sh/bun/assets/3084745/7c8c80e6-d49e-457a-a45e-45ebed946d56" /%}
-
----
-
-Alternatively, search `bun-vscode` in the Extensions tab of VS Code.
-
-{% image src="https://github.com/oven-sh/bun/assets/3084745/664b4c40-944c-4076-a4c2-f812aebd3dc9" /%}
-
----
-
-Make sure you are installing the extension published by the verified Oven organization.
-
-{% image src="https://github.com/oven-sh/bun/assets/3084745/73e6b09f-9ff1-4d85-b725-c5eb7215b6ae" /%}
-
----
-
-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.
-
-{% image src="https://github.com/oven-sh/bun/assets/3084745/1b2c7fd9-fbb9-486a-84d0-eb7ec135ded3" /%}
-
----
-
-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.
-
-{% image src="https://github.com/oven-sh/bun/assets/3084745/c579a36c-eb21-4a58-bc9c-74612aad82af" /%}

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

@@ -1,82 +0,0 @@
----
-name: Debugging Bun with the web debugger
----
-
-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
-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
-$ bun --inspect server.ts
------------------- 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.
-
-{% image src="https://github.com/oven-sh/bun/assets/3084745/e6a976a8-80cc-4394-8925-539025cc025d" alt="Screenshot of Bun debugger, Console tab" /%}
-
----
-
-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.
-
-{% image src="https://github.com/oven-sh/bun/assets/3084745/3b69c7e9-25ff-4f9d-acc4-caa736862935" alt="screenshot of Bun debugger" /%}
-
----
-
-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.
-
-{% image src="https://github.com/oven-sh/bun/assets/3084745/8b565e58-5445-4061-9bc4-f41090dfe769" alt="screenshot of Bun debugger" /%}
-
----
-
-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.
-
-{% image src="https://github.com/oven-sh/bun/assets/3084745/f4312b76-48ba-4a7d-b3b6-6205968ac681" /%}
-
----
-
-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.
-
-{% image src="https://github.com/oven-sh/bun/assets/3084745/63d7f843-5180-489c-aa94-87c486e68646" /%}
-
----
-
-In the upper left of the Sources pane, we can control the execution of the program.
-
-{% image src="https://github.com/oven-sh/bun/assets/3084745/41b76deb-7371-4461-9d5d-81b5a6d2f7a4" /%}
-
----
-
-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.
-
-{% image src="https://github-production-user-asset-6210df.s3.amazonaws.com/3084745/261510346-6a94441c-75d3-413a-99a7-efa62365f83d.png" /%}

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

@@ -1,11 +0,0 @@
----
-name: Convert a Node.js Readable to an ArrayBuffer
----
-
-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.md

@@ -1,11 +0,0 @@
----
-name: Convert a Node.js Readable to a Blob
----
-
-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.md

@@ -1,12 +0,0 @@
----
-name: Convert a Node.js Readable to JSON
----
-
-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.md

@@ -1,12 +0,0 @@
----
-name: Convert a Node.js Readable to a string
----
-
-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.md

@@ -1,11 +0,0 @@
----
-name: Convert a Node.js Readable to an Uint8Array
----
-
-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.md

@@ -1,14 +0,0 @@
----
-name: Convert a ReadableStream to an array of chunks
----
-
-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.

package/docs/guides/streams/to-arraybuffer.md

@@ -1,14 +0,0 @@
----
-name: Convert a ReadableStream to an ArrayBuffer
----
-
-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.
-
-```ts
-const stream = new ReadableStream();
-const buf = await Bun.readableStreamToArrayBuffer(stream);
-```
-
----
-
-See [Docs > API > Utils](https://bun.com/docs/api/utils#bun-readablestreamto) for documentation on Bun's other `ReadableStream` conversion functions.

package/docs/guides/streams/to-blob.md

@@ -1,14 +0,0 @@
----
-name: Convert a ReadableStream to a Blob
----
-
-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.
-
-```ts
-const stream = new ReadableStream();
-const blob = await Bun.readableStreamToBlob(stream);
-```
-
----
-
-See [Docs > API > Utils](https://bun.com/docs/api/utils#bun-readablestreamto) for documentation on Bun's other `ReadableStream` conversion functions.

package/docs/guides/streams/to-buffer.md

@@ -1,15 +0,0 @@
----
-name: Convert a ReadableStream to a Buffer
----
-
-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. This snippet reads the contents of a `ReadableStream` to an [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer), then creates a [`Buffer`](https://nodejs.org/api/buffer.html) that points to it.
-
-```ts
-const stream = new ReadableStream();
-const arrBuf = await Bun.readableStreamToArrayBuffer(stream);
-const nodeBuf = Buffer.from(arrBuf);
-```
-
----
-
-See [Docs > API > Utils](https://bun.com/docs/api/utils#bun-readablestreamto) for documentation on Bun's other `ReadableStream` conversion functions.

package/docs/guides/streams/to-json.md

@@ -1,14 +0,0 @@
----
-name: Convert a ReadableStream to JSON
----
-
-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.
-
-```ts
-const stream = new ReadableStream();
-const json = await Bun.readableStreamToJSON(stream);
-```
-
----
-
-See [Docs > API > Utils](https://bun.com/docs/api/utils#bun-readablestreamto) for documentation on Bun's other `ReadableStream` conversion functions.

package/docs/guides/streams/to-string.md

@@ -1,14 +0,0 @@
----
-name: Convert a ReadableStream to a string
----
-
-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.
-
-```ts
-const stream = new ReadableStream();
-const str = await Bun.readableStreamToText(stream);
-```
-
----
-
-See [Docs > API > Utils](https://bun.com/docs/api/utils#bun-readablestreamto) for documentation on Bun's other `ReadableStream` conversion functions.