bun-types 1.3.2-canary.20251105T140650 → 1.3.2

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

@@ -1,3 +1,8 @@
+---
+title: Transpiler
+description: Use Bun's transpiler to transpile JavaScript and TypeScript code
+---
+
 Bun exposes its internal transpiler via the `Bun.Transpiler` class. To create an instance of Bun's transpiler:
 
 ```ts
@@ -6,15 +11,14 @@ const transpiler = new Bun.Transpiler({
 });
 ```
 
+---
+
 ## `.transformSync()`
 
 Transpile code synchronously with the `.transformSync()` method. Modules are not resolved and the code is not executed. The result is a string of vanilla JavaScript code.
 
-<!-- It is synchronous and runs in the same thread as other JavaScript code. -->
-
-{% codetabs %}
-
-```js#Example
+<CodeGroup>
+```ts transpile.ts icon="/icons/typescript.svg" 
 const transpiler = new Bun.Transpiler({
   loader: 'tsx',
 });
@@ -26,9 +30,10 @@ export function Home(props: {title: string}){
 }`;
 
 const result = transpiler.transformSync(code);
-```
 
-```js#Result
+````
+
+```ts output
 import { __require as require } from "bun:wrap";
 import * as JSX from "react/jsx-dev-runtime";
 var jsx = require(JSX).jsxDEV;
@@ -43,9 +48,9 @@ export default jsx(
   undefined,
   this,
 );
-```
+````
 
-{% /codetabs %}
+</CodeGroup>
 
 To override the default loader specified in the `new Bun.Transpiler()` constructor, pass a second argument to `.transformSync()`.
 
@@ -53,11 +58,15 @@ To override the default loader specified in the `new Bun.Transpiler()` construct
 transpiler.transformSync("<div>hi!</div>", "tsx");
 ```
 
-{% details summary="Nitty gritty" %}
+<Accordion title="Nitty gritty">
+
 When `.transformSync` is called, the transpiler is run in the same thread as the currently executed code.
 
 If a macro is used, it will be run in the same thread as the transpiler, but in a separate event loop from the rest of your application. Currently, globals between macros and regular code are shared, which means it is possible (but not recommended) to share states between macros and regular code. Attempting to use AST nodes outside of a macro is undefined behavior.
-{% /details %}
+
+</Accordion>
+
+---
 
 ## `.transform()`
 
@@ -75,21 +84,23 @@ Unless you're transpiling _many_ large files, you should probably use `Bun.Trans
 await transpiler.transform("<div>hi!</div>", "tsx");
 ```
 
-{% details summary="Nitty gritty" %}
+<Accordion title="Nitty gritty">
+
 The `.transform()` method runs the transpiler in Bun's worker threadpool, so if you run it 100 times, it will run it across `Math.floor($cpu_count * 0.8)` threads, without blocking the main JavaScript thread.
 
 If your code uses a macro, it will potentially spawn a new copy of Bun's JavaScript runtime environment in that new thread.
-{% /details %}
+
+</Accordion>
 
 ## `.scan()`
 
 The `Transpiler` instance can also scan some source code and return a list of its imports and exports, plus additional metadata about each one. [Type-only](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html#type-only-imports-and-export) imports and exports are ignored.
 
-{% codetabs %}
+<CodeGroup>
 
-```ts#Example
+```ts example.ts icon="/icons/typescript.svg"
 const transpiler = new Bun.Transpiler({
-  loader: 'tsx',
+  loader: "tsx",
 });
 
 const code = `
@@ -104,11 +115,9 @@ export const name = "hello";
 const result = transpiler.scan(code);
 ```
 
-```json#Output
+```json output
 {
-  "exports": [
-    "name"
-  ],
+  "exports": ["name"],
   "imports": [
     {
       "kind": "import-statement",
@@ -126,7 +135,7 @@ const result = transpiler.scan(code);
 }
 ```
 
-{% /codetabs %}
+</CodeGroup>
 
 Each import in the `imports` array has a `path` and `kind`. Bun categories imports into the following kinds:
 
@@ -136,19 +145,18 @@ Each import in the `imports` array has a `path` and `kind`. Bun categories impor
 - `dynamic-import`: `import('./loader')`
 - `import-rule`: `@import 'foo.css'`
 - `url-token`: `url('./foo.png')`
-<!-- - `internal`: `import {foo} from 'bun:internal'`
-- `entry-point-build`: `import {foo} from 'bun:entry'`
-- `entry-point-run`: `bun ./mymodule` -->
+
+---
 
 ## `.scanImports()`
 
 For performance-sensitive code, you can use the `.scanImports()` method to get a list of imports. It's faster than `.scan()` (especially for large files) but marginally less accurate due to some performance optimizations.
 
-{% codetabs %}
+<CodeGroup>
 
-```ts#Example
+```ts example.ts icon="/icons/typescript.svg"
 const transpiler = new Bun.Transpiler({
-  loader: 'tsx',
+  loader: "tsx",
 });
 
 const code = `
@@ -163,26 +171,30 @@ export const name = "hello";
 const result = transpiler.scanImports(code);
 ```
 
-```json#Results
+```json results icon="file-json"
 [
   {
-    kind: "import-statement",
-    path: "react"
-  }, {
-    kind: "require-call",
-    path: "./cjs.js"
-  }, {
-    kind: "dynamic-import",
-    path: "./loader"
+    "kind": "import-statement",
+    "path": "react"
+  },
+  {
+    "kind": "require-call",
+    "path": "./cjs.js"
+  },
+  {
+    "kind": "dynamic-import",
+    "path": "./loader"
   }
 ]
 ```
 
-{% /codetabs %}
+</CodeGroup>
+
+---
 
 ## Reference
 
-```ts
+```ts See Typescript Definitions expandable
 type Loader = "jsx" | "js" | "ts" | "tsx";
 
 interface TranspilerOptions {

package/docs/{typescript.md → runtime/typescript.mdx}

@@ -1,7 +1,12 @@
+---
+title: "TypeScript"
+description: "Using TypeScript with Bun, including type definitions and compiler options"
+---
+
 To install the TypeScript definitions for Bun's built-in APIs, install `@types/bun`.
 
 ```sh
-$ bun add -d @types/bun # dev dependency
+bun add -d @types/bun # dev dependency
 ```
 
 At this point, you should be able to reference the `Bun` global in your TypeScript files without seeing errors in your editor.
@@ -49,5 +54,5 @@ Bun supports things like top-level await, JSX, and extensioned `.ts` imports, wh
 If you run `bun init` in a new directory, this `tsconfig.json` will be generated for you. (The stricter flags are disabled by default.)
 
 ```sh
-$ bun init
+bun init
 ```

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

@@ -1,8 +1,13 @@
+---
+title: Utils
+description: Use Bun's utility functions to work with the runtime
+---
+
 ## `Bun.version`
 
 A `string` containing the version of the `bun` CLI that is currently running.
 
-```ts
+```ts terminal icon="terminal"
 Bun.version;
 // => "0.6.4"
 ```
@@ -11,7 +16,7 @@ Bun.version;
 
 The git commit of [Bun](https://github.com/oven-sh/bun) that was compiled to create the current `bun` CLI.
 
-```ts
+```ts terminal icon="terminal"
 Bun.revision;
 // => "f02561530fda1ee9396f51c8bc99b38716e38296"
 ```
@@ -24,7 +29,7 @@ An alias for `process.env`.
 
 An absolute path to the entrypoint of the current program (the file that was executed with `bun run`).
 
-```ts#script.ts
+```ts script.ts
 Bun.main;
 // /path/to/script.ts
 ```
@@ -127,17 +132,11 @@ The final 8 bytes of the UUID are a cryptographically secure random value. It us
 
 ```ts
 namespace Bun {
-  function randomUUIDv7(
-    encoding?: "hex" | "base64" | "base64url" = "hex",
-    timestamp?: number = Date.now(),
-  ): string;
+  function randomUUIDv7(encoding?: "hex" | "base64" | "base64url" = "hex", timestamp?: number = Date.now()): string;
   /**
    * If you pass "buffer", you get a 16-byte buffer instead of a string.
    */
-  function randomUUIDv7(
-    encoding: "buffer",
-    timestamp?: number = Date.now(),
-  ): Buffer;
+  function randomUUIDv7(encoding: "buffer", timestamp?: number = Date.now()): Buffer;
 
   // If you only pass a timestamp, you get a hex string
   function randomUUIDv7(timestamp?: number = Date.now()): string;
@@ -146,13 +145,13 @@ namespace Bun {
 
 You can optionally set encoding to `"buffer"` to get a 16-byte buffer instead of a string. This can sometimes avoid string conversion overhead.
 
-```ts#buffer.ts
+```ts buffer.ts
 const buffer = Bun.randomUUIDv7("buffer");
 ```
 
 `base64` and `base64url` encodings are also supported when you want a slightly shorter string.
 
-```ts#base64.ts
+```ts base64.ts
 const base64 = Bun.randomUUIDv7("base64");
 const base64url = Bun.randomUUIDv7("base64url");
 ```
@@ -200,9 +199,7 @@ test("peek", () => {
   // If we peek a rejected promise, it:
   // - returns the error
   // - does not mark the promise as handled
-  const rejected = Promise.reject(
-    new Error("Successfully tested promise rejection"),
-  );
+  const rejected = Promise.reject(new Error("Successfully tested promise rejection"));
   expect(peek(rejected).message).toBe("Successfully tested promise rejection");
 });
 ```
@@ -234,11 +231,11 @@ const currentFile = import.meta.url;
 Bun.openInEditor(currentFile);
 ```
 
-You can override this via the `debug.editor` setting in your [`bunfig.toml`](https://bun.com/docs/runtime/bunfig).
+You can override this via the `debug.editor` setting in your [`bunfig.toml`](/runtime/bunfig).
 
-```toml-diff#bunfig.toml
-+ [debug]
-+ editor = "code"
+```toml bunfig.toml
+[debug] // [!code ++]
+editor = "code" // [!code ++]
 ```
 
 Or specify an editor with the `editor` param. You can also specify a line and column number.
@@ -310,7 +307,9 @@ This function is optimized for large input. On an M1X, it processes 480 MB/s -
 20 GB/s, depending on how much data is being escaped and whether there is non-ascii
 text. Non-string types will be converted to a string before escaping.
 
-## `Bun.stringWidth()` ~6,756x faster `string-width` alternative
+## `Bun.stringWidth()`
+
+<Note>~6,756x faster `string-width` alternative</Note>
 
 Get the column count of a string as it would be displayed in a terminal.
 Supports ANSI escape codes, emoji, and wide characters.
@@ -352,7 +351,7 @@ npm/string-width    500 chars ascii             249,710 ns/iter (239,970 ns …
 
 To make `Bun.stringWidth` fast, we've implemented it in Zig using optimized SIMD instructions, accounting for Latin1, UTF-16, and UTF-8 encodings. It passes `string-width`'s tests.
 
-{% details summary="View full benchmark" %}
+<Accordion title="View full benchmark">
 
 As a reminder, 1 nanosecond (ns) is 1 billionth of a second. Here's a quick reference for converting between units:
 
@@ -362,7 +361,7 @@ As a reminder, 1 nanosecond (ns) is 1 billionth of a second. Here's a quick refe
 | µs   | 1,000         |
 | ms   | 1             |
 
-```js
+```bash terminal icon="terminal"
 ❯ bun string-width.mjs
 cpu: 13th Gen Intel(R) Core(TM) i9-13900
 runtime: bun 1.0.29 (x64-linux)
@@ -391,7 +390,7 @@ Bun.stringWidth 19,000 chars ansi+emoji+ascii  114.06 µs/iter (112.86 µs … 1
 Bun.stringWidth 95,000 chars ansi+emoji+ascii  572.69 µs/iter (565.52 µs … 607.22 µs) 572.45 µs 604.86 µs 605.21 µs
 ```
 
-```ts
+```bash terminal icon="terminal"
 ❯ node string-width.mjs
 cpu: 13th Gen Intel(R) Core(TM) i9-13900
 runtime: node v21.4.0 (x64-linux)
@@ -420,11 +419,11 @@ npm/string-width 19,000 chars ansi+emoji+ascii   27.19 ms/iter   (26.89 ms … 2
 npm/string-width 95,000 chars ansi+emoji+ascii     3.68 s/iter        (3.66 s … 3.7 s)    3.69 s     3.7 s     3.7 s
 ```
 
-{% /details %}
+</Accordion>
 
 TypeScript definition:
 
-```ts
+```ts expandable
 namespace Bun {
   export function stringWidth(
     /**
@@ -449,7 +448,7 @@ namespace Bun {
 }
 ```
 
-<!-- ## `Bun.enableANSIColors()` -->
+---
 
 ## `Bun.fileURLToPath()`
 
@@ -460,6 +459,8 @@ const path = Bun.fileURLToPath(new URL("file:///foo/bar.txt"));
 console.log(path); // "/foo/bar.txt"
 ```
 
+---
+
 ## `Bun.pathToFileURL()`
 
 Converts an absolute path to a `file://` URL.
@@ -469,7 +470,7 @@ const url = Bun.pathToFileURL("/foo/bar.txt");
 console.log(url); // "file:///foo/bar.txt"
 ```
 
-<!-- Bun.hash; -->
+---
 
 ## `Bun.gzipSync()`
 
@@ -485,9 +486,9 @@ compressed; // => Uint8Array(30)
 
 Optionally, pass a parameters object as the second argument:
 
-{% details summary="zlib compression options"%}
+<Accordion title="zlib compression options">
 
-```ts
+```ts expandable
 export type ZlibCompressionOptions = {
   /**
    * The compression level to use. Must be between `-1` and `9`.
@@ -558,7 +559,9 @@ export type ZlibCompressionOptions = {
 };
 ```
 
-{% /details %}
+</Accordion>
+
+---
 
 ## `Bun.gunzipSync()`
 
@@ -574,6 +577,8 @@ dec.decode(uncompressed);
 // => "hellohellohello..."
 ```
 
+---
+
 ## `Bun.deflateSync()`
 
 Compresses a `Uint8Array` using zlib's DEFLATE algorithm.
@@ -588,6 +593,8 @@ compressed; // => Uint8Array(12)
 
 The second argument supports the same set of configuration options as [`Bun.gzipSync`](#bun-gzipsync).
 
+---
+
 ## `Bun.inflateSync()`
 
 Decompresses a `Uint8Array` using zlib's INFLATE algorithm.
@@ -602,6 +609,8 @@ dec.decode(decompressed);
 // => "hellohellohello..."
 ```
 
+---
+
 ## `Bun.zstdCompress()` / `Bun.zstdCompressSync()`
 
 Compresses a `Uint8Array` using the Zstandard algorithm.
@@ -636,6 +645,8 @@ dec.decode(decompressedSync);
 // => "hellohellohello..."
 ```
 
+---
+
 ## `Bun.inspect()`
 
 Serializes an object to a `string` exactly as it would be printed by `console.log`.
@@ -650,7 +661,7 @@ const str = Bun.inspect(arr);
 // => "Uint8Array(3) [ 1, 2, 3 ]"
 ```
 
-## `Bun.inspect.custom`
+### `Bun.inspect.custom`
 
 This is the symbol that Bun uses to implement `Bun.inspect`. You can override this to customize how your objects are printed. It is identical to `util.inspect.custom` in Node.js.
 
@@ -665,7 +676,7 @@ const foo = new Foo();
 console.log(foo); // => "foo"
 ```
 
-## `Bun.inspect.table(tabularData, properties, options)`
+### `Bun.inspect.table(tabularData, properties, options)`
 
 Format tabular data into a string. Like [`console.table`](https://developer.mozilla.org/en-US/docs/Web/API/console/table_static), except it returns a string rather than printing to the console.
 
@@ -724,6 +735,8 @@ console.log(
 );
 ```
 
+---
+
 ## `Bun.nanoseconds()`
 
 Returns the number of nanoseconds since the current `bun` process started, as a `number`. Useful for high-precision timing and benchmarking.
@@ -733,6 +746,8 @@ Bun.nanoseconds();
 // => 7288958
 ```
 
+---
+
 ## `Bun.readableStreamTo*()`
 
 Bun implements a set of convenience functions for asynchronously consuming the body of a `ReadableStream` and converting it to various binary formats.
@@ -767,6 +782,8 @@ await Bun.readableStreamToFormData(stream);
 await Bun.readableStreamToFormData(stream, multipartFormBoundary);
 ```
 
+---
+
 ## `Bun.resolveSync()`
 
 Resolves a file path or module specifier using Bun's internal module resolution algorithm. The first argument is the path to resolve, and the second argument is the "root". If no match is found, an `Error` is thrown.
@@ -792,21 +809,11 @@ To resolve relative to the directory containing the current file, pass `import.m
 Bun.resolveSync("./foo.ts", import.meta.dir);
 ```
 
-## `serialize` & `deserialize` in `bun:jsc`
+---
 
-To save a JavaScript value into an ArrayBuffer & back, use `serialize` and `deserialize` from the `"bun:jsc"` module.
+## `Bun.stripANSI()`
 
-```js
-import { serialize, deserialize } from "bun:jsc";
-
-const buf = serialize({ foo: "bar" });
-const obj = deserialize(buf);
-console.log(obj); // => { foo: "bar" }
-```
-
-Internally, [`structuredClone`](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone) and [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) serialize and deserialize the same way. This exposes the underlying [HTML Structured Clone Algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) to JavaScript as an ArrayBuffer.
-
-## `Bun.stripANSI()` ~6-57x faster `strip-ansi` alternative
+<Note>~6-57x faster `strip-ansi` alternative</Note>
 
 `Bun.stripANSI(text: string): string`
 
@@ -824,8 +831,11 @@ console.log(Bun.stripANSI(formatted)); // => "Bold and underlined"
 
 `Bun.stripANSI` is significantly faster than the popular [`strip-ansi`](https://www.npmjs.com/package/strip-ansi) npm package:
 
-```js
-> bun bench/snippets/strip-ansi.mjs
+```bash terminal icon="terminal"
+bun bench/snippets/strip-ansi.mjs
+```
+
+```txt
 cpu: Apple M3 Max
 runtime: bun 1.2.21 (arm64-darwin)
 
@@ -844,8 +854,11 @@ Bun.stripANSI 212,992 chars long-ansi    227.65 µs/iter 234.50 µs
                                 (216.46 µs … 401.92 µs) 262.25 µs
 ```
 
-```js
-> node bench/snippets/strip-ansi.mjs
+```bash terminal icon="terminal"
+node bench/snippets/strip-ansi.mjs
+```
+
+```txt
 cpu: Apple M3 Max
 runtime: node 24.6.0 (arm64-darwin)
 
@@ -865,6 +878,24 @@ npm/strip-ansi 212,992 chars long-ansi      1.36 ms/iter   1.38 ms
 
 ```
 
+---
+
+## `serialize` & `deserialize` in `bun:jsc`
+
+To save a JavaScript value into an ArrayBuffer & back, use `serialize` and `deserialize` from the `"bun:jsc"` module.
+
+```js
+import { serialize, deserialize } from "bun:jsc";
+
+const buf = serialize({ foo: "bar" });
+const obj = deserialize(buf);
+console.log(obj); // => { foo: "bar" }
+```
+
+Internally, [`structuredClone`](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone) and [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) serialize and deserialize the same way. This exposes the underlying [HTML Structured Clone Algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) to JavaScript as an ArrayBuffer.
+
+---
+
 ## `estimateShallowMemoryUsageOf` in `bun:jsc`
 
 The `estimateShallowMemoryUsageOf` function returns a best-effort estimate of the memory usage of an object in bytes, excluding the memory usage of properties or other objects it references. For accurate per-object memory usage, use `Bun.generateHeapSnapshot`.