bun-types 1.3.2-canary.20251105T140650 → 1.3.2

package/docs/runtime/{hot.md → watch-mode.mdx}

@@ -1,87 +1,104 @@
+---
+title: "Watch Mode"
+description: "Automatic reloading in Bun with --watch and --hot modes"
+---
+
 Bun supports two kinds of automatic reloading via CLI flags:
 
 - `--watch` mode, which hard restarts Bun's process when imported files change.
 - `--hot` mode, which soft reloads the code (without restarting the process) when imported files change.
 
+---
+
 ## `--watch` mode
 
 Watch mode can be used with `bun test` or when running TypeScript, JSX, and JavaScript files.
 
 To run a file in `--watch` mode:
 
-```bash
-$ bun --watch index.tsx
+```bash terminal icon="terminal"
+bun --watch index.tsx
 ```
 
 To run your tests in `--watch` mode:
 
-```bash
-$ bun --watch test
+```bash terminal icon="terminal"
+bun --watch test
 ```
 
 In `--watch` mode, Bun keeps track of all imported files and watches them for changes. When a change is detected, Bun restarts the process, preserving the same set of CLI arguments and environment variables used in the initial run. If Bun crashes, `--watch` will attempt to automatically restart the process.
 
-{% callout %}
+<Note>
 
 **⚡️ Reloads are fast.** The filesystem watchers you're probably used to have several layers of libraries wrapping the native APIs or worse, rely on polling.
 
 Instead, Bun uses operating system native filesystem watcher APIs like kqueue or inotify to detect changes to files. Bun also does a number of optimizations to enable it scale to larger projects (such as setting a high rlimit for file descriptors, statically allocated file path buffers, reuse file descriptors when possible, etc).
 
-{% /callout %}
+</Note>
 
 The following examples show Bun live-reloading a file as it is edited, with VSCode configured to save the file [on each keystroke](https://code.visualstudio.com/docs/editor/codebasics#_save-auto-save).
 
-{% codetabs %}
-
-```bash
-$ bun run --watch watchy.tsx
+```sh terminal icon="terminal"
+bun run --watch watchy.tsx
 ```
 
-```tsx#watchy.tsx
+```tsx title="watchy.tsx" icon="/icons/typescript.svg"
 import { serve } from "bun";
+
 console.log("I restarted at:", Date.now());
 
 serve({
   port: 4003,
-
   fetch(request) {
     return new Response("Sup");
   },
 });
 ```
 
-{% /codetabs %}
-
 In this example, Bun is
-![bun watch gif](https://user-images.githubusercontent.com/709451/228439002-7b9fad11-0db2-4e48-b82d-2b88c8625625.gif)
+
+<Frame>
+  ![bun watch gif](https://user-images.githubusercontent.com/709451/228439002-7b9fad11-0db2-4e48-b82d-2b88c8625625.gif)
+</Frame>
 
 Running `bun test` in watch mode and `save-on-keypress` enabled:
 
-```bash
-$ bun --watch test
+```bash terminal icon="terminal"
+bun --watch test
 ```
 
-![bun test gif](https://user-images.githubusercontent.com/709451/228396976-38a23864-4a1d-4c96-87cc-04e5181bf459.gif)
-
-{% callout %}
+<Frame>
+  ![bun test gif](https://user-images.githubusercontent.com/709451/228396976-38a23864-4a1d-4c96-87cc-04e5181bf459.gif)
+</Frame>
 
-The **`--no-clear-screen`** flag is useful in scenarios where you don’t want the terminal to clear, such as when running multiple `bun build --watch` commands simultaneously using tools like `concurrently`. Without this flag, the output of one instance could clear the output of others, potentially hiding errors from one instance beneath the output of another. The `--no-clear-screen` flag, similar to TypeScript’s `--preserveWatchOutput`, prevents this issue. It can be used in combination with `--watch`, for example: `bun build --watch --no-clear-screen`.
+<Note>
+  The **`--no-clear-screen`** flag is useful in scenarios where you don't want the terminal to clear, such as when
+  running multiple `bun build --watch` commands simultaneously using tools like `concurrently`. Without this flag, the
+  output of one instance could clear the output of others, potentially hiding errors from one instance beneath the
+  output of another. The `--no-clear-screen` flag, similar to TypeScript's `--preserveWatchOutput`, prevents this issue.
+  It can be used in combination with `--watch`, for example: `bun build --watch --no-clear-screen`.
+</Note>
 
-{% /callout %}
+---
 
 ## `--hot` mode
 
 Use `bun --hot` to enable hot reloading when executing code with Bun. This is distinct from `--watch` mode in that Bun does not hard-restart the entire process. Instead, it detects code changes and updates its internal module cache with the new code.
 
-**Note** — This is not the same as hot reloading in the browser! Many frameworks provide a "hot reloading" experience, where you can edit & save your frontend code (say, a React component) and see the changes reflected in the browser without refreshing the page. Bun's `--hot` is the server-side equivalent of this experience. To get hot reloading in the browser, use a framework like [Vite](https://vitejs.dev).
+<Note>
+  This is not the same as hot reloading in the browser! Many frameworks provide a "hot reloading" experience, where you
+  can edit & save your frontend code (say, a React component) and see the changes reflected in the browser without
+  refreshing the page. Bun's `--hot` is the server-side equivalent of this experience. To get hot reloading in the
+  browser, use a framework like [Vite](https://vitejs.dev).
+</Note>
 
-```bash
-$ bun --hot server.ts
+```bash terminal icon="terminal"
+bun --hot server.ts
 ```
 
 Starting from the entrypoint (`server.ts` in the example above), Bun builds a registry of all imported source files (excluding those in `node_modules`) and watches them for changes. When a change is detected, Bun performs a "soft reload". All files are re-evaluated, but all global state (notably, the `globalThis` object) is persisted.
 
-```ts#server.ts
+```ts title="server.ts" icon="/icons/typescript.svg"
 // make TypeScript happy
 declare global {
   var count: number;
@@ -97,8 +114,11 @@ setInterval(function () {}, 1000000);
 
 If you run this file with `bun --hot server.ts`, you'll see the reload count increment every time you save the file.
 
-```bash
-$ bun --hot index.ts
+```bash terminal icon="terminal"
+bun --hot index.ts
+```
+
+```txt
 Reloaded 1 times
 Reloaded 2 times
 Reloaded 3 times
@@ -110,7 +130,7 @@ Traditional file watchers like `nodemon` restart the entire process, so HTTP ser
 
 This makes it possible, for instance, to update your HTTP request handler without shutting down the server itself. When you save the file, your HTTP server will be reloaded with the updated code without the process being restarted. This results in seriously fast refresh speeds.
 
-```ts#server.ts
+```ts title="server.ts" icon="/icons/typescript.svg"
 globalThis.count ??= 0;
 globalThis.count++;
 
@@ -122,16 +142,12 @@ Bun.serve({
 });
 ```
 
-<!-- The file above is simply exporting an object with a `fetch` handler defined. When this file is executed, Bun interprets this as an HTTP server and passes the exported object into `Bun.serve`. -->
-
-<!-- {% image src="https://user-images.githubusercontent.com/709451/195477632-5fd8a73e-014d-4589-9ba2-e075ad9eb040.gif" alt="Bun vs Nodemon refresh speeds" caption="Bun on the left, Nodemon on the right." /%} -->
-
-{% callout %}
+<Note>
 **Note** — In a future version of Bun, support for Vite's `import.meta.hot` is planned to enable better lifecycle management for hot reloading and to align with the ecosystem.
 
-{% /callout %}
+</Note>
 
-{% details summary="Implementation details" %}
+<Accordion title="Implementation details">
 
 On hot reload, Bun:
 
@@ -142,4 +158,4 @@ On hot reload, Bun:
 
 This implementation isn't particularly optimized. It re-transpiles files that haven't changed. It makes no attempt at incremental compilation. It's a starting point.
 
-{% /details %}
+</Accordion>

package/docs/runtime/web-apis.mdx

@@ -0,0 +1,29 @@
+---
+title: "Web APIs"
+description: "Web-standard APIs supported by Bun for server-side JavaScript"
+mode: center
+---
+
+Some Web APIs aren't relevant in the context of a server-first runtime like Bun, such as the [DOM API](https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API#html_dom_api_interfaces) or [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API). Many others, though, are broadly useful outside of the browser context; when possible, Bun implements these Web-standard APIs instead of introducing new APIs.
+
+The following Web APIs are partially or completely supported.
+
+| Category              | APIs                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| HTTP                  | [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/fetch), [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response), [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request), [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers), [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController), [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)                                                                         |
+| URLs                  | [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL), [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)                                                                                                                                                                                                                                                                                                                                                                                   |
+| Web Workers           | [`Worker`](https://developer.mozilla.org/en-US/docs/Web/API/Worker), [`self.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/DedicatedWorkerGlobalScope/postMessage), [`structuredClone`](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone), [`MessagePort`](https://developer.mozilla.org/en-US/docs/Web/API/MessagePort), [`MessageChannel`](https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel), [`BroadcastChannel`](https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel) |
+| Streams               | [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream), [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream), [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream), [`ByteLengthQueuingStrategy`](https://developer.mozilla.org/en-US/docs/Web/API/ByteLengthQueuingStrategy), [`CountQueuingStrategy`](https://developer.mozilla.org/en-US/docs/Web/API/CountQueuingStrategy) and associated classes                                     |
+| Blob                  | [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob)                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| WebSockets            | [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Encoding and decoding | [`atob`](https://developer.mozilla.org/en-US/docs/Web/API/atob), [`btoa`](https://developer.mozilla.org/en-US/docs/Web/API/btoa), [`TextEncoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder), [`TextDecoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder)                                                                                                                                                                                                                                         |
+| JSON                  | [`JSON`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON)                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Timeouts              | [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout), [`clearTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/clearTimeout)                                                                                                                                                                                                                                                                                                                                                                           |
+| Intervals             | [`setInterval`](https://developer.mozilla.org/en-US/docs/Web/API/setInterval), [`clearInterval`](https://developer.mozilla.org/en-US/docs/Web/API/clearInterval)                                                                                                                                                                                                                                                                                                                                                                       |
+| Crypto                | [`crypto`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto), [`SubtleCrypto`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto), [`CryptoKey`](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey)                                                                                                                                                                                                                                                                                                        |
+| Debugging             | [`console`](https://developer.mozilla.org/en-US/docs/Web/API/console), [`performance`](https://developer.mozilla.org/en-US/docs/Web/API/Performance)                                                                                                                                                                                                                                                                                                                                                                                   |
+| Microtasks            | [`queueMicrotask`](https://developer.mozilla.org/en-US/docs/Web/API/queueMicrotask)                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Errors                | [`reportError`](https://developer.mozilla.org/en-US/docs/Web/API/reportError)                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| User interaction      | [`alert`](https://developer.mozilla.org/en-US/docs/Web/API/Window/alert), [`confirm`](https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm), [`prompt`](https://developer.mozilla.org/en-US/docs/Web/API/Window/prompt) (intended for interactive CLIs)                                                                                                                                                                                                                                                                     |
+| Realms                | [`ShadowRealm`](https://github.com/tc39/proposal-shadowrealm)                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| Events                | [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget), [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event), [`ErrorEvent`](https://developer.mozilla.org/en-US/docs/Web/API/ErrorEvent), [`CloseEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent), [`MessageEvent`](https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent)                                                                                                                                            |

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

@@ -1,6 +1,12 @@
-{% callout %}
-**🚧** — The `Worker` API is still experimental (particularly for terminating workers). We are actively working on improving this.
-{% /callout %}
+---
+title: Workers
+description: Use Bun's Workers API to create and communicate with a new JavaScript instance running on a separate thread while sharing I/O resources with the main thread
+---
+
+<Warning>
+  The `Worker` API is still experimental (particularly for terminating workers). We are actively working on improving
+  this.
+</Warning>
 
 [`Worker`](https://developer.mozilla.org/en-US/docs/Web/API/Worker) lets you start and communicate with a new JavaScript instance running on a separate thread while sharing I/O resources with the main thread.
 
@@ -12,7 +18,7 @@ Like in browsers, [`Worker`](https://developer.mozilla.org/en-US/docs/Web/API/Wo
 
 ### From the main thread
 
-```js#Main_thread
+```ts index.ts icon="/icons/typescript.svg"
 const worker = new Worker("./worker.ts");
 
 worker.postMessage("hello");
@@ -23,7 +29,7 @@ worker.onmessage = event => {
 
 ### Worker thread
 
-```ts#worker.ts_(Worker_thread)
+```ts worker.ts  icon="file-code"
 // prevents TS errors
 declare var self: Worker;
 
@@ -54,7 +60,7 @@ The specifier passed to `Worker` is resolved relative to the project root (like
 
 You can pass an array of module specifiers to the `preload` option to load modules before the worker starts. This is useful when you want to ensure some code is always loaded before the application starts, like loading OpenTelemetry, Sentry, DataDog, etc.
 
-```js
+```ts index.ts icon="/icons/typescript.svg"
 const worker = new Worker("./worker.ts", {
   preload: ["./load-sentry.js"],
 });
@@ -64,7 +70,7 @@ Like the `--preload` CLI argument, the `preload` option is processed before the
 
 You can also pass a single string to the `preload` option:
 
-```js
+```ts index.ts icon="/icons/typescript.svg"
 const worker = new Worker("./worker.ts", {
   preload: "./load-sentry.js",
 });
@@ -92,7 +98,7 @@ const worker = new Worker(url);
 
 Like the rest of Bun, workers created from `blob:` URLs support TypeScript, JSX, and other file types out of the box. You can communicate it should be loaded via typescript either via `type` or by passing a `filename` to the `File` constructor.
 
-```js
+```ts
 const file = new File(
   [
     `
@@ -108,7 +114,7 @@ const worker = new Worker(url);
 
 The `"open"` event is emitted when a worker is created and ready to receive messages. This can be used to send an initial message to a worker once it's ready. (This event does not exist in browsers.)
 
-```ts
+```ts index.ts icon="/icons/typescript.svg"
 const worker = new Worker(new URL("worker.ts", import.meta.url).href);
 
 worker.addEventListener("open", () => {
@@ -141,7 +147,7 @@ With these fast paths, Bun's `postMessage` performs **2-241x faster** because th
 
 **Bun (with fast paths):**
 
-```
+```ts
 postMessage({ prop: 11 chars string, ...9 more props }) - 648ns
 postMessage({ prop: 14 KB string, ...9 more props })    - 719ns
 postMessage({ prop: 3 MB string, ...9 more props })     - 1.26µs
@@ -149,7 +155,7 @@ postMessage({ prop: 3 MB string, ...9 more props })     - 1.26µs
 
 **Node.js v24.6.0 (for comparison):**
 
-```
+```js
 postMessage({ prop: 11 chars string, ...9 more props }) - 1.19µs
 postMessage({ prop: 14 KB string, ...9 more props })    - 2.69µs
 postMessage({ prop: 3 MB string, ...9 more props })     - 304µs
@@ -205,7 +211,7 @@ worker.addEventListener("message", event => {
 
 A `Worker` instance terminates automatically once it's event loop has no work left to do. Attaching a `"message"` listener on the global or any `MessagePort`s will keep the event loop alive. To forcefully terminate a `Worker`, call `worker.terminate()`.
 
-```ts
+```ts index.ts icon="/icons/typescript.svg"
 const worker = new Worker(new URL("worker.ts", import.meta.url).href);
 
 // ...some time later
@@ -222,7 +228,7 @@ A worker can terminate itself with `process.exit()`. This does not terminate the
 
 The `"close"` event is emitted when a worker has been terminated. It can take some time for the worker to actually terminate, so this event is emitted when the worker has been marked as terminated. The `CloseEvent` will contain the exit code passed to `process.exit()`, or 0 if closed for other reasons.
 
-```ts
+```ts index.ts icon="/icons/typescript.svg"
 const worker = new Worker(new URL("worker.ts", import.meta.url).href);
 
 worker.addEventListener("close", event => {
@@ -240,7 +246,7 @@ By default, an active `Worker` will keep the main (spawning) process alive, so a
 
 To stop a running worker from keeping the process alive, call `worker.unref()`. This decouples the lifetime of the worker to the lifetime of the main process, and is equivalent to what Node.js' `worker_threads` does.
 
-```ts
+```ts index.ts icon="/icons/typescript.svg"
 const worker = new Worker(new URL("worker.ts", import.meta.url).href);
 worker.unref();
 ```
@@ -251,7 +257,7 @@ Note: `worker.unref()` is not available in browsers.
 
 To keep the process alive until the `Worker` terminates, call `worker.ref()`. A ref'd worker is the default behavior, and still needs something going on in the event loop (such as a `"message"` listener) for the worker to continue running.
 
-```ts
+```ts index.ts icon="/icons/typescript.svg"
 const worker = new Worker(new URL("worker.ts", import.meta.url).href);
 worker.unref();
 // later...
@@ -260,7 +266,7 @@ worker.ref();
 
 Alternatively, you can also pass an `options` object to `Worker`:
 
-```ts
+```ts index.ts icon="/icons/typescript.svg"
 const worker = new Worker(new URL("worker.ts", import.meta.url).href, {
   ref: false,
 });
@@ -272,21 +278,21 @@ Note: `worker.ref()` is not available in browsers.
 
 JavaScript instances can use a lot of memory. Bun's `Worker` supports a `smol` mode that reduces memory usage, at a cost of performance. To enable `smol` mode, pass `smol: true` to the `options` object in the `Worker` constructor.
 
-```js
+```ts index.ts icon="/icons/typescript.svg"
 const worker = new Worker("./i-am-smol.ts", {
   smol: true,
 });
 ```
 
-{% details summary="What does `smol` mode actually do?" %}
-Setting `smol: true` sets `JSC::HeapSize` to be `Small` instead of the default `Large`.
-{% /details %}
+<Accordion title="What does `smol` mode actually do?">
+  Setting `smol: true` sets `JSC::HeapSize` to be `Small` instead of the default `Large`.
+</Accordion>
 
 ## Environment Data
 
 Share data between the main thread and workers using `setEnvironmentData()` and `getEnvironmentData()`.
 
-```js
+```ts title="index.ts" icon="/icons/typescript.svg"
 import { setEnvironmentData, getEnvironmentData } from "worker_threads";
 
 // In main thread
@@ -301,7 +307,7 @@ console.log(config); // => { apiUrl: "https://api.example.com" }
 
 Listen for worker creation events using `process.emit()`:
 
-```js
+```ts title="index.ts" icon="/icons/typescript.svg"
 process.on("worker", worker => {
   console.log("New worker created:", worker.threadId);
 });