bun-types 1.3.2-canary.20251105T140650 → 1.3.2

package/docs/guides/test/{testing-library.md → testing-library.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Using Testing Library with Bun
+title: Using Testing Library with Bun
+sidebarTitle: Testing Library
+mode: center
 ---
 
 You can use [Testing Library](https://testing-library.com/) with Bun's test runner.
@@ -8,7 +10,7 @@ You can use [Testing Library](https://testing-library.com/) with Bun's test runn
 
 As a prerequisite to using Testing Library you will need to install [Happy Dom](https://github.com/capricorn86/happy-dom). ([see Bun's Happy DOM guide for more information](https://bun.sh/guides/test/happy-dom)).
 
-```sh
+```sh terminal icon="terminal"
 bun add -D @happy-dom/global-registrator
 ```
 
@@ -16,7 +18,7 @@ bun add -D @happy-dom/global-registrator
 
 Next you should install the Testing Library packages you are planning on using. For example, if you are setting up testing for React your installs may look like this. You will also need to install `@testing-library/jest-dom` to get matchers working later.
 
-```sh
+```sh terminal icon="terminal"
 bun add -D @testing-library/react @testing-library/dom @testing-library/jest-dom
 ```
 
@@ -24,8 +26,8 @@ bun add -D @testing-library/react @testing-library/dom @testing-library/jest-dom
 
 Next you will need to create a preload script for Happy DOM and for Testing Library. For more details about the Happy DOM setup script see [Bun's Happy DOM guide](https://bun.sh/guides/test/happy-dom).
 
-```ts#happydom.ts
-import { GlobalRegistrator } from '@happy-dom/global-registrator';
+```ts happydom.ts icon="/icons/typescript.svg"
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
 
 GlobalRegistrator.register();
 ```
@@ -34,10 +36,10 @@ GlobalRegistrator.register();
 
 For Testing Library, you will want to extend Bun's `expect` function with Testing Library's matchers. Optionally, to better match the behavior of test-runners like Jest, you may want to run cleanup after each test.
 
-```ts#testing-library.ts
-import { afterEach, expect } from 'bun:test';
-import { cleanup } from '@testing-library/react';
-import * as matchers from '@testing-library/jest-dom/matchers';
+```ts testing-library.ts icon="/icons/typescript.svg"
+import { afterEach, expect } from "bun:test";
+import { cleanup } from "@testing-library/react";
+import * as matchers from "@testing-library/jest-dom/matchers";
 
 expect.extend(matchers);
 
@@ -51,7 +53,7 @@ afterEach(() => {
 
 Next, add these preload scripts to your `bunfig.toml` (you can also have everything in a single `preload.ts` script if you prefer).
 
-```toml#bunfig.toml
+```toml bunfig.toml icon="settings"
 [test]
 preload = ["./happydom.ts", "./testing-library.ts"]
 ```
@@ -60,13 +62,12 @@ preload = ["./happydom.ts", "./testing-library.ts"]
 
 If you are using TypeScript you will also need to make use of declaration merging in order to get the new matcher types to show up in your editor. To do this, create a type declaration file that extends `Matchers` like this.
 
-```ts#matchers.d.ts
-import { TestingLibraryMatchers } from '@testing-library/jest-dom/matchers';
-import { Matchers, AsymmetricMatchers } from 'bun:test';
+```ts matchers.d.ts icon="/icons/typescript.svg"
+import { TestingLibraryMatchers } from "@testing-library/jest-dom/matchers";
+import { Matchers, AsymmetricMatchers } from "bun:test";
 
-declare module 'bun:test' {
-  interface Matchers<T>
-    extends TestingLibraryMatchers<typeof expect.stringContaining, T> {}
+declare module "bun:test" {
+  interface Matchers<T> extends TestingLibraryMatchers<typeof expect.stringContaining, T> {}
   interface AsymmetricMatchers extends TestingLibraryMatchers {}
 }
 ```
@@ -75,7 +76,7 @@ declare module 'bun:test' {
 
 You should now be able to use Testing Library in your tests
 
-```ts
+```ts matchers.d.ts icon="/icons/typescript.svg"
 import { test, expect } from "bun:test";
 import { screen, render } from "@testing-library/react";
 import { MyComponent } from "./myComponent";

package/docs/guides/test/{timeout.md → timeout.mdx}

@@ -1,13 +1,15 @@
 ---
-name: Set a per-test timeout with the Bun test runner
+title: Set a per-test timeout with the Bun test runner
+sidebarTitle: Test timeout
+mode: center
 ---
 
 Use the `--timeout` flag to set a timeout for each test in milliseconds. If any test exceeds this timeout, it will be marked as failed.
 
 The default timeout is `5000` (5 seconds).
 
-```sh
-$ bun test --timeout 3000 # 3 seconds
+```sh terminal icon="terminal"
+bun test --timeout 3000 # 3 seconds
 ```
 
 ---

package/docs/guides/test/{todo-tests.md → todo-tests.mdx}

@@ -1,10 +1,12 @@
 ---
-name: Mark a test as a "todo" with the Bun test runner
+title: Mark a test as a "todo" with the Bun test runner
+sidebarTitle: Todo tests
+mode: center
 ---
 
 To remind yourself to write a test later, use the `test.todo` function. There's no need to provide a test implementation.
 
-```ts
+```ts test.ts icon="/icons/typescript.svg"
 import { test, expect } from "bun:test";
 
 // write this later
@@ -15,9 +17,11 @@ test.todo("unimplemented feature");
 
 The output of `bun test` indicates how many `todo` tests were encountered.
 
-```sh
-$ bun test
+```sh terminal icon="terminal"
+bun test
+```
 
+```txt
 test.test.ts:
 ✓ add [0.03ms]
 ✓ multiply [0.02ms]
@@ -46,8 +50,11 @@ test.todo("unimplemented feature", () => {
 
 If an implementation is provided, it will not be run unless the `--todo` flag is passed. If the `--todo` flag is passed, the test will be executed and _expected to fail_ by test runner! If a todo test passes, the `bun test` run will return a non-zero exit code to signal the failure.
 
-```sh
-$ bun test --todo
+```sh terminal icon="terminal"
+bun test --todo
+```
+
+```txt
 my.test.ts:
 ✗ unimplemented feature
   ^ this test is marked as todo but passes. Remove `.todo` or check that test is correct.

package/docs/guides/test/{update-snapshots.md → update-snapshots.mdx}

@@ -1,10 +1,12 @@
 ---
-name: Update snapshots in `bun test`
+title: Update snapshots in `bun test`
+sidebarTitle: Update snapshots
+mode: center
 ---
 
 Bun's test runner supports Jest-style snapshot testing via `.toMatchSnapshot()`.
 
-```ts#snap.test.ts
+```ts snap.test.ts icon="/icons/typescript.svg"
 import { test, expect } from "bun:test";
 
 test("snapshot", () => {
@@ -16,7 +18,7 @@ test("snapshot", () => {
 
 The first time this test is executed, Bun will write a snapshot file to disk in a directory called `__snapshots__` that lives alongside the test file.
 
-```txt
+```txt File Tree icon="folder-tree"
 test
 ├── __snapshots__
 │   └── snap.test.ts.snap
@@ -27,10 +29,11 @@ test
 
 To regenerate snapshots, use the `--update-snapshots` flag.
 
-```sh
-$ bun test --update-snapshots
-bun test v1.3.2-canary.20251105T140650 (9c68abdb)
+```sh terminal icon="terminal"
+bun test --update-snapshots
+```
 
+```txt
 test/snap.test.ts:
 ✓ snapshot [0.86ms]
 

package/docs/guides/test/{watch-mode.md → watch-mode.mdx}

@@ -1,18 +1,23 @@
 ---
-name: Run tests in watch mode with Bun
+title: Run tests in watch mode with Bun
+sidebarTitle: Watch mode
+mode: center
 ---
 
 Use the `--watch` flag to run your tests in watch mode.
 
-```sh
-$ bun test --watch
+```sh terminal icon="terminal"
+bun test --watch
 ```
 
 ---
 
 This will restart the running Bun process whenever a file change is detected. It's fast. In this example, the editor is configured to save the file on every keystroke.
 
-{% image src="https://github.com/oven-sh/bun/assets/3084745/dc49a36e-ba82-416f-b960-1c883a924248" caption="Running tests in watch mode in Bun" /%}
+<Frame>
+  ![Running tests in watch mode in
+  Bun](https://github.com/oven-sh/bun/assets/3084745/dc49a36e-ba82-416f-b960-1c883a924248)
+</Frame>
 
 ---
 

package/docs/guides/util/{base64.md → base64.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Encode and decode base64 strings
+title: Encode and decode base64 strings
+sidebarTitle: Base64 encoding
+mode: center
 ---
 
 Bun implements the Web-standard [`atob`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/atob) and [`btoa`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/btoa) functions for encoding and decoding base64 strings.

package/docs/guides/util/{deep-equals.md → deep-equals.mdx}

@@ -1,10 +1,12 @@
 ---
-name: Check if two objects are deeply equal
+title: Check if two objects are deeply equal
+sidebarTitle: Deep equality
+mode: center
 ---
 
 Check if two objects are deeply equal. This is used internally by `expect().toEqual()` in Bun's [test runner](https://bun.com/docs/test/writing).
 
-```ts#index.ts
+```ts index.ts icon="/icons/typescript.svg"
 const a = { a: 1, b: 2, c: { d: 3 } };
 const b = { a: 1, b: 2, c: { d: 3 } };
 
@@ -17,7 +19,7 @@ Pass `true` as a third argument to enable strict mode. This is used internally b
 
 The following examples would return `true` in non-strict mode but `false` in strict mode.
 
-```ts
+```ts index.ts icon="/icons/typescript.svg"
 // undefined values
 Bun.deepEquals({}, { a: undefined }, true); // false
 

package/docs/guides/util/{deflate.md → deflate.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Compress and decompress data with DEFLATE
+title: Compress and decompress data with DEFLATE
+sidebarTitle: DEFLATE compression
+mode: center
 ---
 
 Use `Bun.deflateSync()` to compress a `Uint8Array` with DEFLATE.

package/docs/guides/util/{detect-bun.md → detect-bun.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Detect when code is executed with Bun
+title: Detect when code is executed with Bun
+sidebarTitle: Detect Bun
+mode: center
 ---
 
 The recommended way to conditionally detect when code is being executed with `bun` is to check for the existence of the `Bun` global.

package/docs/guides/util/{entrypoint.md → entrypoint.mdx}

@@ -1,10 +1,12 @@
 ---
-name: Check if the current file is the entrypoint
+title: Check if the current file is the entrypoint
+sidebarTitle: Check entrypoint
+mode: center
 ---
 
 Bun provides a handful of module-specific utilities on the [`import.meta`](https://bun.com/docs/api/import-meta) object. Use `import.meta.main` to check if the current file is the entrypoint of the current process.
 
-```ts#index.ts
+```ts index.ts icon="/icons/typescript.svg"
 if (import.meta.main) {
   // this file is directly executed with `bun run`
 } else {

package/docs/guides/util/{escape-html.md → escape-html.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Escape an HTML string
+title: Escape an HTML string
+sidebarTitle: Escape HTML
+mode: center
 ---
 
 The `Bun.escapeHTML()` utility can be used to escape HTML characters in a string. The following replacements are made.

package/docs/guides/util/{file-url-to-path.md → file-url-to-path.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Convert a file URL to an absolute path
+title: Convert a file URL to an absolute path
+sidebarTitle: File URL to path
+mode: center
 ---
 
 Use `Bun.fileURLToPath()` to convert a `file://` URL to an absolute path.

package/docs/guides/util/{gzip.md → gzip.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Compress and decompress data with gzip
+title: Compress and decompress data with gzip
+sidebarTitle: Gzip compression
+mode: center
 ---
 
 Use `Bun.gzipSync()` to compress a `Uint8Array` with gzip.

package/docs/guides/util/{hash-a-password.md → hash-a-password.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Hash a password
+title: Hash a password
+sidebarTitle: Hash password
+mode: center
 ---
 
 The `Bun.password.hash()` function provides a fast, built-in mechanism for securely hashing passwords in Bun. No third-party dependencies are required.

package/docs/guides/util/{import-meta-dir.md → import-meta-dir.mdx}

@@ -1,10 +1,12 @@
 ---
-name: Get the directory of the current file
+title: Get the directory of the current file
+sidebarTitle: import.meta.dir
+mode: center
 ---
 
 Bun provides a handful of module-specific utilities on the [`import.meta`](https://bun.com/docs/api/import-meta) object.
 
-```ts#/a/b/c.ts
+```ts /a/b/c.ts icon="/icons/typescript.svg"
 import.meta.dir; // => "/a/b"
 ```
 

package/docs/guides/util/{import-meta-file.md → import-meta-file.mdx}

@@ -1,10 +1,12 @@
 ---
-name: Get the file name of the current file
+title: Get the file name of the current file
+sidebarTitle: import.meta.file
+mode: center
 ---
 
 Bun provides a handful of module-specific utilities on the [`import.meta`](https://bun.com/docs/api/import-meta) object. Use `import.meta.file` to retrieve the name of the current file.
 
-```ts#/a/b/c.ts
+```ts /a/b/c.ts icon="/icons/typescript.svg"
 import.meta.file; // => "c.ts"
 ```
 

package/docs/guides/util/{import-meta-path.md → import-meta-path.mdx}

@@ -1,10 +1,12 @@
 ---
-name: Get the absolute path of the current file
+title: Get the absolute path of the current file
+sidebarTitle: import.meta.path
+mode: center
 ---
 
 Bun provides a handful of module-specific utilities on the [`import.meta`](https://bun.com/docs/api/import-meta) object. Use `import.meta.path` to retrieve the absolute path of the current file.
 
-```ts#/a/b/c.ts
+```ts /a/b/c.ts icon="/icons/typescript.svg"
 import.meta.path; // => "/a/b/c.ts"
 ```
 

package/docs/guides/util/{javascript-uuid.md → javascript-uuid.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Generate a UUID
+title: Generate a UUID
+sidebarTitle: Generate UUID
+mode: center
 ---
 
 Use `crypto.randomUUID()` to generate a UUID v4. This API works in Bun, Node.js, and browsers. It requires no dependencies.

package/docs/guides/util/{main.md → main.mdx}

@@ -1,29 +1,40 @@
 ---
-name: Get the absolute path to the current entrypoint
+title: Get the absolute path to the current entrypoint
+sidebarTitle: Get entrypoint path
+mode: center
 ---
 
 The `Bun.main` property contains the absolute path to the current entrypoint.
 
-{% codetabs %}
+<CodeGroup>
 
-```ts#foo.ts
+```ts foo.ts icon="/icons/typescript.svg"
 console.log(Bun.main);
 ```
 
-```ts#index.ts
+```ts index.ts icon="/icons/typescript.svg"
 import "./foo.ts";
 ```
 
-{% /codetabs %}
+</CodeGroup>
 
 ---
 
 The printed path corresponds to the file that is executed with `bun run`.
 
-```sh
-$ bun run index.ts
+```sh terminal icon="terminal"
+bun run index.ts
+```
+
+```txt
 /path/to/index.ts
-$ bun run foo.ts
+```
+
+```sh terminal icon="terminal"
+bun run foo.ts
+```
+
+```txt
 /path/to/foo.ts
 ```
 

package/docs/guides/util/{path-to-file-url.md → path-to-file-url.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Convert an absolute path to a file URL
+title: Convert an absolute path to a file URL
+sidebarTitle: Path to file URL
+mode: center
 ---
 
 Use `Bun.pathToFileURL()` to convert an absolute path to a `file://` URL.

package/docs/guides/util/{sleep.md → sleep.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Sleep for a fixed number of milliseconds
+title: Sleep for a fixed number of milliseconds
+sidebarTitle: Sleep
+mode: center
 ---
 
 The `Bun.sleep` method provides a convenient way to create a void `Promise` that resolves in a fixed number of milliseconds.

package/docs/guides/util/{version.md → version.mdx}

@@ -1,18 +1,20 @@
 ---
-name: Get the current Bun version
+title: Get the current Bun version
+sidebarTitle: Get Bun version
+mode: center
 ---
 
 Get the current version of Bun in a semver format.
 
-```ts#index.ts
-Bun.version; // => "1.3.2-canary.20251105T140650"
+```ts index.ts icon="/icons/typescript.svg"
+Bun.version; // => "1.3.1"
 ```
 
 ---
 
 Get the exact `git` commit of [`oven-sh/bun`](https://github.com/oven-sh/bun) that was compiled to produce this Bun binary.
 
-```ts#index.ts
+```ts index.ts icon="/icons/typescript.svg"
 Bun.revision; // => "49231b2cb9aa48497ab966fc0bb6b742dacc4994"
 ```
 

package/docs/guides/util/{which-path-to-executable-bin.md → which-path-to-executable-bin.mdx}

@@ -1,10 +1,12 @@
 ---
-name: Get the path to an executable bin file
+title: Get the path to an executable bin file
+sidebarTitle: Find executable path
+mode: center
 ---
 
 `Bun.which` is a utility function to find the absolute path of an executable file. It is similar to the `which` command in Unix-like systems.
 
-```ts#foo.ts
+```ts foo.ts icon="/icons/typescript.svg"
 Bun.which("sh"); // => "/bin/sh"
 Bun.which("notfound"); // => null
 Bun.which("bun"); // => "/home/user/.bun/bin/bun"

package/docs/guides/websocket/{compression.md → compression.mdx}

@@ -1,10 +1,12 @@
 ---
-name: Enable compression for WebSocket messages
+title: Enable compression for WebSocket messages
+sidebarTitle: Enable compression
+mode: center
 ---
 
 Per-message compression can be enabled with the `perMessageDeflate` parameter. When set, all messages will be compressed using the [permessage-deflate](https://tools.ietf.org/html/rfc7692) WebSocket extension.
 
-```ts
+```ts server.ts icon="/icons/typescript.svg"
 Bun.serve({
   // ...
   websocket: {
@@ -18,7 +20,7 @@ Bun.serve({
 
 To enable compression for individual messages, pass `true` as the second parameter to `ws.send()`.
 
-```ts
+```ts server.ts icon="/icons/typescript.svg"
 Bun.serve({
   // ...
   websocket: {

package/docs/guides/websocket/{context.md → context.mdx}

@@ -1,13 +1,15 @@
 ---
-name: Set per-socket contextual data on a WebSocket
+title: Set per-socket contextual data on a WebSocket
+sidebarTitle: Contextual data
+mode: center
 ---
 
 When building a WebSocket server, it's typically necessary to store some identifying information or context associated with each connected client.
 
-With [Bun.serve()](https://bun.com/docs/api/websockets#contextual-data), this "contextual data" is set when the connection is initially upgraded by passing a `data` parameter in the `server.upgrade()` call.
+With [Bun.serve()](https://bun.com/docs/api/websockets contextual-data), this "contextual data" is set when the connection is initially upgraded by passing a `data` parameter in the `server.upgrade()` call.
 
-```ts
-Bun.serve({
+```ts server.ts icon="/icons/typescript.svg"
+Bun.serve<{ socketId: number }>({
   fetch(req, server) {
     const success = server.upgrade(req, {
       data: {
@@ -20,9 +22,6 @@ Bun.serve({
     // ...
   },
   websocket: {
-    // TypeScript: specify the type of ws.data like this
-    data: {} as { socketId: number },
-
     // define websocket handlers
     async message(ws, message) {
       // the contextual data is available as the `data` property
@@ -37,14 +36,15 @@ Bun.serve({
 
 It's common to read cookies/headers from the incoming request to identify the connecting client.
 
-```ts
+```ts server.ts icon="/icons/typescript.svg"
 type WebSocketData = {
   createdAt: number;
   token: string;
   userId: string;
 };
 
-Bun.serve({
+// TypeScript: specify the type of `data`
+Bun.serve<WebSocketData>({
   async fetch(req, server) {
     // use a library to parse cookies
     const cookies = parseCookies(req.headers.get("Cookie"));
@@ -62,9 +62,6 @@ Bun.serve({
     if (upgraded) return undefined;
   },
   websocket: {
-    // TypeScript: specify the type of ws.data like this
-    data: {} as WebSocketData,
-
     async message(ws, message) {
       // save the message to a database
       await saveMessageToDatabase({

package/docs/guides/websocket/{pubsub.md → pubsub.mdx}

@@ -1,13 +1,15 @@
 ---
-name: Build a publish-subscribe WebSocket server
+title: Build a publish-subscribe WebSocket server
+sidebarTitle: Pub-sub server
+mode: center
 ---
 
 Bun's server-side `WebSocket` API provides a native pub-sub API. Sockets can be subscribed to a set of named channels using `socket.subscribe(<name>)`; messages can be published to a channel using `socket.publish(<name>, <message>)`.
 
 This code snippet implements a simple single-channel chat server.
 
-```ts
-const server = Bun.serve({
+```ts server.ts icon="/icons/typescript.svg"
+const server = Bun.serve<{ username: string }>({
   fetch(req, server) {
     const cookies = req.headers.get("cookie");
     const username = getUsernameFromCookies(cookies);
@@ -17,9 +19,6 @@ const server = Bun.serve({
     return new Response("Hello world");
   },
   websocket: {
-    // TypeScript: specify the type of ws.data like this
-    data: {} as { username: string },
-
     open(ws) {
       const msg = `${ws.data.username} has entered the chat`;
       ws.subscribe("the-group-chat");

package/docs/guides/websocket/{simple.md → simple.mdx}

@@ -1,13 +1,15 @@
 ---
-name: Build a simple WebSocket server
+title: Build a simple WebSocket server
+sidebarTitle: Simple server
+mode: center
 ---
 
 Start a simple WebSocket server using [`Bun.serve`](https://bun.com/docs/api/http).
 
 Inside `fetch`, we attempt to upgrade incoming `ws:` or `wss:` requests to WebSocket connections.
 
-```ts
-const server = Bun.serve({
+```ts server.ts icon="/icons/typescript.svg"
+const server = Bun.serve<{ authToken: string }>({
   fetch(req, server) {
     const success = server.upgrade(req);
     if (success) {

package/docs/guides/write-file/{append.md → append.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Append content to a file
+title: Append content to a file
+sidebarTitle: Append to file
+mode: center
 ---
 
 Bun implements the `node:fs` module, which includes the `fs.appendFile` and `fs.appendFileSync` functions for appending content to files.

package/docs/guides/write-file/{basic.md → basic.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Write a string to a file
+title: Write a string to a file
+sidebarTitle: Write string to file
+mode: center
 ---
 
 This code snippet writes a string to disk at a particular _absolute path_.

package/docs/guides/write-file/{blob.md → blob.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Write a Blob to a file
+title: Write a Blob to a file
+sidebarTitle: Write Blob
+mode: center
 ---
 
 This code snippet writes a `Blob` to disk at a particular path.