bun-types 1.3.2-canary.20251106T140813 → 1.3.2

package/docs/runtime/watch-mode.mdx

@@ -0,0 +1,161 @@
+---
+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 terminal icon="terminal"
+bun --watch index.tsx
+```
+
+To run your tests in `--watch` mode:
+
+```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.
+
+<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).
+
+</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).
+
+```sh terminal icon="terminal"
+bun run --watch 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");
+  },
+});
+```
+
+In this example, Bun is
+
+<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 terminal icon="terminal"
+bun --watch test
+```
+
+<Frame>
+  ![bun test gif](https://user-images.githubusercontent.com/709451/228396976-38a23864-4a1d-4c96-87cc-04e5181bf459.gif)
+</Frame>
+
+<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>
+
+---
+
+## `--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>
+
+```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 title="server.ts" icon="/icons/typescript.svg"
+// make TypeScript happy
+declare global {
+  var count: number;
+}
+
+globalThis.count ??= 0;
+console.log(`Reloaded ${globalThis.count} times`);
+globalThis.count++;
+
+// prevent `bun run` from exiting
+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 terminal icon="terminal"
+bun --hot index.ts
+```
+
+```txt
+Reloaded 1 times
+Reloaded 2 times
+Reloaded 3 times
+```
+
+Traditional file watchers like `nodemon` restart the entire process, so HTTP servers and other stateful objects are lost. By contrast, `bun --hot` is able to reflect the updated code without restarting the process.
+
+### HTTP servers
+
+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 title="server.ts" icon="/icons/typescript.svg"
+globalThis.count ??= 0;
+globalThis.count++;
+
+Bun.serve({
+  fetch(req: Request) {
+    return new Response(`Reloaded ${globalThis.count} times`);
+  },
+  port: 3000,
+});
+```
+
+<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.
+
+</Note>
+
+<Accordion title="Implementation details">
+
+On hot reload, Bun:
+
+- Resets the internal `require` cache and ES module registry (`Loader.registry`)
+- Runs the garbage collector synchronously (to minimize memory leaks, at the cost of runtime performance)
+- Re-transpiles all of your code from scratch (including sourcemaps)
+- Re-evaluates the code with JavaScriptCore
+
+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.
+
+</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/runtime/workers.mdx

@@ -0,0 +1,328 @@
+---
+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.
+
+Bun implements a minimal version of the [Web Workers API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) with extensions that make it work better for server-side use cases. Like the rest of Bun, `Worker` in Bun support CommonJS, ES Modules, TypeScript, JSX, TSX and more out of the box. No extra build steps are necessary.
+
+## Creating a `Worker`
+
+Like in browsers, [`Worker`](https://developer.mozilla.org/en-US/docs/Web/API/Worker) is a global. Use it to create a new worker thread.
+
+### From the main thread
+
+```ts index.ts icon="/icons/typescript.svg"
+const worker = new Worker("./worker.ts");
+
+worker.postMessage("hello");
+worker.onmessage = event => {
+  console.log(event.data);
+};
+```
+
+### Worker thread
+
+```ts worker.ts  icon="file-code"
+// prevents TS errors
+declare var self: Worker;
+
+self.onmessage = (event: MessageEvent) => {
+  console.log(event.data);
+  postMessage("world");
+};
+```
+
+To prevent TypeScript errors when using `self`, add this line to the top of your worker file.
+
+```ts
+declare var self: Worker;
+```
+
+You can use `import` and `export` syntax in your worker code. Unlike in browsers, there's no need to specify `{type: "module"}` to use ES Modules.
+
+To simplify error handling, the initial script to load is resolved at the time `new Worker(url)` is called.
+
+```js
+const worker = new Worker("/not-found.js");
+// throws an error immediately
+```
+
+The specifier passed to `Worker` is resolved relative to the project root (like typing `bun ./path/to/file.js`).
+
+### `preload` - load modules before the worker starts
+
+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.
+
+```ts index.ts icon="/icons/typescript.svg"
+const worker = new Worker("./worker.ts", {
+  preload: ["./load-sentry.js"],
+});
+```
+
+Like the `--preload` CLI argument, the `preload` option is processed before the worker starts.
+
+You can also pass a single string to the `preload` option:
+
+```ts index.ts icon="/icons/typescript.svg"
+const worker = new Worker("./worker.ts", {
+  preload: "./load-sentry.js",
+});
+```
+
+This feature was added in Bun v1.1.35.
+
+### `blob:` URLs
+
+As of Bun v1.1.13, you can also pass a `blob:` URL to `Worker`. This is useful for creating workers from strings or other sources.
+
+```js
+const blob = new Blob(
+  [
+    `
+  self.onmessage = (event: MessageEvent) => postMessage(event.data)`,
+  ],
+  {
+    type: "application/typescript",
+  },
+);
+const url = URL.createObjectURL(blob);
+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.
+
+```ts
+const file = new File(
+  [
+    `
+  self.onmessage = (event: MessageEvent) => postMessage(event.data)`,
+  ],
+  "worker.ts",
+);
+const url = URL.createObjectURL(file);
+const worker = new Worker(url);
+```
+
+### `"open"`
+
+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 index.ts icon="/icons/typescript.svg"
+const worker = new Worker(new URL("worker.ts", import.meta.url).href);
+
+worker.addEventListener("open", () => {
+  console.log("worker is ready");
+});
+```
+
+Messages are automatically enqueued until the worker is ready, so there is no need to wait for the `"open"` event to send messages.
+
+## Messages with `postMessage`
+
+To send messages, use [`worker.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Worker/postMessage) and [`self.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). This leverages the [HTML Structured Clone Algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm).
+
+### Performance optimizations
+
+Bun includes optimized fast paths for `postMessage` to dramatically improve performance for common data types:
+
+**String fast path** - When posting pure string values, Bun bypasses the structured clone algorithm entirely, achieving significant performance gains with no serialization overhead.
+
+**Simple object fast path** - For plain objects containing only primitive values (strings, numbers, booleans, null, undefined), Bun uses an optimized serialization path that stores properties directly without full structured cloning.
+
+The simple object fast path activates when the object:
+
+- Is a plain object with no prototype chain modifications
+- Contains only enumerable, configurable data properties
+- Has no indexed properties or getter/setter methods
+- All property values are primitives or strings
+
+With these fast paths, Bun's `postMessage` performs **2-241x faster** because the message length no longer has a meaningful impact on performance.
+
+**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
+```
+
+**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
+```
+
+```js
+// String fast path - optimized
+postMessage("Hello, worker!");
+
+// Simple object fast path - optimized
+postMessage({
+  message: "Hello",
+  count: 42,
+  enabled: true,
+  data: null,
+});
+
+// Complex objects still work but use standard structured clone
+postMessage({
+  nested: { deep: { object: true } },
+  date: new Date(),
+  buffer: new ArrayBuffer(8),
+});
+```
+
+```js
+// On the worker thread, `postMessage` is automatically "routed" to the parent thread.
+postMessage({ hello: "world" });
+
+// On the main thread
+worker.postMessage({ hello: "world" });
+```
+
+To receive messages, use the [`message` event handler](https://developer.mozilla.org/en-US/docs/Web/API/Worker/message_event) on the worker and main thread.
+
+```js
+// Worker thread:
+self.addEventListener("message", event => {
+  console.log(event.data);
+});
+// or use the setter:
+// self.onmessage = fn
+
+// if on the main thread
+worker.addEventListener("message", event => {
+  console.log(event.data);
+});
+// or use the setter:
+// worker.onmessage = fn
+```
+
+## Terminating a worker
+
+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 index.ts icon="/icons/typescript.svg"
+const worker = new Worker(new URL("worker.ts", import.meta.url).href);
+
+// ...some time later
+worker.terminate();
+```
+
+This will cause the worker's to exit as soon as possible.
+
+### `process.exit()`
+
+A worker can terminate itself with `process.exit()`. This does not terminate the main process. Like in Node.js, `process.on('beforeExit', callback)` and `process.on('exit', callback)` are emitted on the worker thread (and not on the main thread), and the exit code is passed to the `"close"` event.
+
+### `"close"`
+
+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 index.ts icon="/icons/typescript.svg"
+const worker = new Worker(new URL("worker.ts", import.meta.url).href);
+
+worker.addEventListener("close", event => {
+  console.log("worker is being closed");
+});
+```
+
+This event does not exist in browsers.
+
+## Managing lifetime
+
+By default, an active `Worker` will keep the main (spawning) process alive, so async tasks like `setTimeout` and promises will keep the process alive. Attaching `message` listeners will also keep the `Worker` alive.
+
+### `worker.unref()`
+
+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 index.ts icon="/icons/typescript.svg"
+const worker = new Worker(new URL("worker.ts", import.meta.url).href);
+worker.unref();
+```
+
+Note: `worker.unref()` is not available in browsers.
+
+### `worker.ref()`
+
+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 index.ts icon="/icons/typescript.svg"
+const worker = new Worker(new URL("worker.ts", import.meta.url).href);
+worker.unref();
+// later...
+worker.ref();
+```
+
+Alternatively, you can also pass an `options` object to `Worker`:
+
+```ts index.ts icon="/icons/typescript.svg"
+const worker = new Worker(new URL("worker.ts", import.meta.url).href, {
+  ref: false,
+});
+```
+
+Note: `worker.ref()` is not available in browsers.
+
+## Memory usage with `smol`
+
+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.
+
+```ts index.ts icon="/icons/typescript.svg"
+const worker = new Worker("./i-am-smol.ts", {
+  smol: true,
+});
+```
+
+<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()`.
+
+```ts title="index.ts" icon="/icons/typescript.svg"
+import { setEnvironmentData, getEnvironmentData } from "worker_threads";
+
+// In main thread
+setEnvironmentData("config", { apiUrl: "https://api.example.com" });
+
+// In worker
+const config = getEnvironmentData("config");
+console.log(config); // => { apiUrl: "https://api.example.com" }
+```
+
+## Worker Events
+
+Listen for worker creation events using `process.emit()`:
+
+```ts title="index.ts" icon="/icons/typescript.svg"
+process.on("worker", worker => {
+  console.log("New worker created:", worker.threadId);
+});
+```
+
+## `Bun.isMainThread`
+
+You can check if you're in the main thread by checking `Bun.isMainThread`.
+
+```ts
+if (Bun.isMainThread) {
+  console.log("I'm the main thread");
+} else {
+  console.log("I'm in a worker");
+}
+```
+
+This is useful for conditionally running code based on whether you're in the main thread or not.