bun-types 1.3.2-canary.20251105T140650 → 1.3.2

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

@@ -1,9 +1,17 @@
-{% callout %}
-**⚠️ Warning** — `bun:ffi` is **experimental**, with known bugs and limitations, and should not be relied on in production. The most stable way to interact with native code from Bun is to write a [Node-API module](/docs/api/node-api).
-{% /callout %}
+---
+title: FFI
+description: Use Bun's FFI module to efficiently call native libraries from JavaScript
+---
+
+<Warning>
+  `bun:ffi` is **experimental**, with known bugs and limitations, and should not be relied on in production. The most
+  stable way to interact with native code from Bun is to write a [Node-API module](/runtime/node-api).
+</Warning>
 
 Use the built-in `bun:ffi` module to efficiently call native libraries from JavaScript. It works with languages that support the C ABI (Zig, Rust, C/C++, C#, Nim, Kotlin, etc).
 
+---
+
 ## dlopen usage (`bun:ffi`)
 
 To print the version number of `sqlite3`:
@@ -33,20 +41,23 @@ const {
 console.log(`SQLite 3 version: ${sqlite3_libversion()}`);
 ```
 
+---
+
 ## Performance
 
 According to [our benchmark](https://github.com/oven-sh/bun/tree/main/bench/ffi), `bun:ffi` is roughly 2-6x faster than Node.js FFI via `Node-API`.
 
-{% image src="/images/ffi.png" height="400" /%}
+<Image src="/images/ffi.png" height="400" />
 
 Bun generates & just-in-time compiles C bindings that efficiently convert values between JavaScript types and native types. To compile C, Bun embeds [TinyCC](https://github.com/TinyCC/tinycc), a small and fast C compiler.
 
+---
+
 ## Usage
 
 ### Zig
 
-```zig
-// add.zig
+```zig add.zig icon="file-code"
 pub export fn add(a: i32, b: i32) i32 {
   return a + b;
 }
@@ -54,8 +65,8 @@ pub export fn add(a: i32, b: i32) i32 {
 
 To compile:
 
-```bash
-$ zig build-lib add.zig -dynamic -OReleaseFast
+```bash terminal icon="terminal"
+zig build-lib add.zig -dynamic -OReleaseFast
 ```
 
 Pass a path to the shared library and a map of symbols to import into `dlopen`:
@@ -89,7 +100,7 @@ pub extern "C" fn add(a: i32, b: i32) -> i32 {
 To compile:
 
 ```bash
-$ rustc --crate-type cdylib add.rs
+rustc --crate-type cdylib add.rs
 ```
 
 ### C++
@@ -105,9 +116,11 @@ extern "C" int32_t add(int32_t a, int32_t b) {
 To compile:
 
 ```bash
-$ zig build-lib add.cpp -dynamic -lc -lc++
+zig build-lib add.cpp -dynamic -lc -lc++
 ```
 
+---
+
 ## FFI types
 
 The following `FFIType` values are supported.
@@ -137,11 +150,13 @@ The following `FFIType` values are supported.
 
 Note: `buffer` arguments must be a `TypedArray` or `DataView`.
 
+---
+
 ## Strings
 
 JavaScript strings and C-like strings are different, and that complicates using strings with native libraries.
 
-{% details summary="How are JavaScript strings and C strings different?" %}
+<Accordion title="How are JavaScript strings and C strings different?">
 JavaScript strings:
 
 - UTF16 (2 bytes per letter) or potentially latin1, depending on the JavaScript engine &amp; what characters are used
@@ -154,7 +169,7 @@ C strings:
 - The length is not stored. Instead, the string is null-terminated which means the length is the index of the first `\0` it finds
 - Mutable
 
-{% /details %}
+</Accordion>
 
 To solve this, `bun:ffi` exports `CString` which extends JavaScript's built-in `String` to support null-terminated strings and add a few extras:
 
@@ -201,13 +216,11 @@ console.log(myString);
 
 When used in `returns`, `FFIType.cstring` coerces the pointer to a JavaScript `string`. When used in `args`, `FFIType.cstring` is identical to `ptr`.
 
-## Function pointers
-
-{% callout %}
+---
 
-**Note** — Async functions are not yet supported.
+## Function pointers
 
-{% /callout %}
+<Note>Async functions are not yet supported</Note>
 
 To call a function pointer from JavaScript, use `CFunction`. This is useful if using Node-API (napi) with Bun, and you've already loaded some symbols.
 
@@ -255,13 +268,11 @@ const lib = linkSymbols({
   },
 });
 
-const [major, minor, patch] = [
-  lib.symbols.getMajor(),
-  lib.symbols.getMinor(),
-  lib.symbols.getPatch(),
-];
+const [major, minor, patch] = [lib.symbols.getMajor(), lib.symbols.getMinor(), lib.symbols.getPatch()];
 ```
 
+---
+
 ## Callbacks
 
 Use `JSCallback` to create JavaScript callback functions that can be passed to C/FFI functions. The C/FFI function can call into the JavaScript/TypeScript code. This is useful for asynchronous code or whenever you want to call into JavaScript code from C.
@@ -279,13 +290,10 @@ const {
   },
 });
 
-const searchIterator = new JSCallback(
-  (ptr, length) => /hello/.test(new CString(ptr, length)),
-  {
-    returns: "bool",
-    args: ["ptr", "usize"],
-  },
-);
+const searchIterator = new JSCallback((ptr, length) => /hello/.test(new CString(ptr, length)), {
+  returns: "bool",
+  args: ["ptr", "usize"],
+});
 
 const str = Buffer.from("wwutwutwutwutwutwutwutwutwutwutut\0", "utf8");
 if (search(ptr(str), searchIterator)) {
@@ -305,21 +313,17 @@ When you're done with a JSCallback, you should call `close()` to free the memory
 
 `JSCallback` has experimental support for thread-safe callbacks. This will be needed if you pass a callback function into a different thread from its instantiation context. You can enable it with the optional `threadsafe` parameter.
 
-Currently, thread-safe callbacks work best when run from another thread that is running JavaScript code, i.e. a [`Worker`](/docs/api/workers). A future version of Bun will enable them to be called from any thread (such as new threads spawned by your native library that Bun is not aware of).
+Currently, thread-safe callbacks work best when run from another thread that is running JavaScript code, i.e. a [`Worker`](/runtime/workers). A future version of Bun will enable them to be called from any thread (such as new threads spawned by your native library that Bun is not aware of).
 
 ```ts
-const searchIterator = new JSCallback(
-  (ptr, length) => /hello/.test(new CString(ptr, length)),
-  {
-    returns: "bool",
-    args: ["ptr", "usize"],
-    threadsafe: true, // Optional. Defaults to `false`
-  },
-);
+const searchIterator = new JSCallback((ptr, length) => /hello/.test(new CString(ptr, length)), {
+  returns: "bool",
+  args: ["ptr", "usize"],
+  threadsafe: true, // Optional. Defaults to `false`
+});
 ```
 
-{% callout %}
-
+<Note>
 **⚡️ Performance tip** — For a slight performance boost, directly pass `JSCallback.prototype.ptr` instead of the `JSCallback` object:
 
 ```ts
@@ -340,17 +344,21 @@ setOnResolve(onResolve.ptr);
 setOnResolve(onResolve);
 ```
 
-{% /callout %}
+</Note>
+
+---
 
 ## Pointers
 
 Bun represents [pointers](<https://en.wikipedia.org/wiki/Pointer_(computer_programming)>) as a `number` in JavaScript.
 
-{% details summary="How does a 64 bit pointer fit in a JavaScript number?" %}
+<Accordion title="How does a 64 bit pointer fit in a JavaScript number?">
+
 64-bit processors support up to [52 bits of addressable space](https://en.wikipedia.org/wiki/64-bit_computing#Limits_of_processors). [JavaScript numbers](https://en.wikipedia.org/wiki/Double-precision_floating-point_format#IEEE_754_double-precision_binary_floating-point_format:_binary64) support 53 bits of usable space, so that leaves us with about 11 bits of extra space.
 
 **Why not `BigInt`?** `BigInt` is slower. JavaScript engines allocate a separate `BigInt` which means they can't fit into a regular JavaScript value. If you pass a `BigInt` to a function, it will be converted to a `number`
-{% /details %}
+
+</Accordion>
 
 To convert from a `TypedArray` to a pointer:
 
@@ -503,7 +511,7 @@ const out = encode_png(
 
 The [auto-generated wrapper](https://github.com/oven-sh/bun/blob/6a65631cbdcae75bfa1e64323a6ad613a922cd1a/src/bun.js/ffi.exports.js#L180-L182) converts the pointer to a `TypedArray`.
 
-{% details summary="Hardmode" %}
+<Accordion title="Hardmode">
 
 If you don't want the automatic conversion or you want a pointer to a specific byte offset within the `TypedArray`, you can also directly get the pointer to the `TypedArray`:
 
@@ -535,7 +543,7 @@ const out = encode_png(
 );
 ```
 
-{% /details %}
+</Accordion>
 
 ### Reading pointers
 

package/docs/{api/file-io.md → runtime/file-io.mdx}

@@ -1,12 +1,15 @@
-{% callout %}
+---
+title: File I/O
+description: Bun provides a set of optimized APIs for reading and writing files.
+---
 
-<!-- **Note** — The `Bun.file` and `Bun.write` APIs documented on this page are heavily optimized and represent the recommended way to perform file-system tasks using Bun. Existing Node.js projects may use Bun's [nearly complete](https://bun.com/docs/runtime/nodejs-apis#node-fs) implementation of the [`node:fs`](https://nodejs.org/api/fs.html) module. -->
+<Note>
 
-**Note** — The `Bun.file` and `Bun.write` APIs documented on this page are heavily optimized and represent the recommended way to perform file-system tasks using Bun. For operations that are not yet available with `Bun.file`, such as `mkdir` or `readdir`, you can use Bun's [nearly complete](https://bun.com/docs/runtime/nodejs-apis#node-fs) implementation of the [`node:fs`](https://nodejs.org/api/fs.html) module.
+The `Bun.file` and `Bun.write` APIs documented on this page are heavily optimized and represent the recommended way to perform file-system tasks using Bun. For operations that are not yet available with `Bun.file`, such as `mkdir` or `readdir`, you can use Bun's [nearly complete](/runtime/nodejs-compat#node-fs) implementation of the [`node:fs`](https://nodejs.org/api/fs.html) module.
 
-{% /callout %}
+</Note>
 
-Bun provides a set of optimized APIs for reading and writing files.
+---
 
 ## Reading files (`Bun.file()`)
 
@@ -26,6 +29,7 @@ The reference conforms to the [`Blob`](https://developer.mozilla.org/en-US/docs/
 const foo = Bun.file("foo.txt");
 
 await foo.text(); // contents as a string
+await foo.json(); // contents as a JSON object
 await foo.stream(); // contents as ReadableStream
 await foo.arrayBuffer(); // contents as ArrayBuffer
 await foo.bytes(); // contents as Uint8Array
@@ -70,6 +74,8 @@ You can delete a file by calling the `.delete()` function.
 await Bun.file("logs.json").delete();
 ```
 
+---
+
 ## Writing files (`Bun.write()`)
 
 `Bun.write(destination, data): Promise<number>`
@@ -92,88 +98,22 @@ The second argument is the data to be written. It can be any of the following:
 
 All possible permutations are handled using the fastest available system calls on the current platform.
 
-{% details summary="See syscalls" %}
-
-{% table %}
-
-- Output
-- Input
-- System call
-- Platform
-
----
-
-- file
-- file
-- copy_file_range
-- Linux
-
----
-
-- file
-- pipe
-- sendfile
-- Linux
-
----
-
-- pipe
-- pipe
-- splice
-- Linux
-
----
-
-- terminal
-- file
-- sendfile
-- Linux
-
----
-
-- terminal
-- terminal
-- sendfile
-- Linux
+<Accordion title="See syscalls">
 
----
+| Output               | Input          | System call                   | Platform |
+| -------------------- | -------------- | ----------------------------- | -------- |
+| file                 | file           | copy_file_range               | Linux    |
+| file                 | pipe           | sendfile                      | Linux    |
+| pipe                 | pipe           | splice                        | Linux    |
+| terminal             | file           | sendfile                      | Linux    |
+| terminal             | terminal       | sendfile                      | Linux    |
+| socket               | file or pipe   | sendfile (if http, not https) | Linux    |
+| file (doesn't exist) | file (path)    | clonefile                     | macOS    |
+| file (exists)        | file           | fcopyfile                     | macOS    |
+| file                 | Blob or string | write                         | macOS    |
+| file                 | Blob or string | write                         | Linux    |
 
-- socket
-- file or pipe
-- sendfile (if http, not https)
-- Linux
-
----
-
-- file (doesn't exist)
-- file (path)
-- clonefile
-- macOS
-
----
-
-- file (exists)
-- file
-- fcopyfile
-- macOS
-
----
-
-- file
-- Blob or string
-- write
-- macOS
-
----
-
-- file
-- Blob or string
-- write
-- Linux
-
-{% /table %}
-
-{% /details %}
+</Accordion>
 
 To write a string to disk:
 
@@ -184,7 +124,7 @@ await Bun.write("output.txt", data);
 
 To copy a file to another location on disk:
 
-```js
+```ts
 const input = Bun.file("input.txt");
 const output = Bun.file("output.txt"); // doesn't exist yet!
 await Bun.write(output, input);
@@ -212,6 +152,8 @@ const response = await fetch("https://bun.com");
 await Bun.write("index.html", response);
 ```
 
+---
+
 ## Incremental writing with `FileSink`
 
 Bun provides a native incremental file writing API called `FileSink`. To retrieve a `FileSink` instance from a `BunFile`:
@@ -259,6 +201,8 @@ writer.unref();
 writer.ref();
 ```
 
+---
+
 ## Directories
 
 Bun's implementation of `node:fs` is fast, and we haven't implemented a Bun-specific API for reading directories just yet. For now, you should use `node:fs` for working with directories in Bun.
@@ -295,13 +239,15 @@ import { mkdir } from "node:fs/promises";
 await mkdir("path/to/dir", { recursive: true });
 ```
 
+---
+
 ## Benchmarks
 
 The following is a 3-line implementation of the Linux `cat` command.
 
-```ts#cat.ts
+```ts cat.ts icon="/icons/typescript.svg"
 // Usage
-// $ bun ./cat.ts ./path-to-file
+// bun ./cat.ts ./path-to-file
 
 import { resolve } from "path";
 
@@ -311,13 +257,15 @@ await Bun.write(Bun.stdout, Bun.file(path));
 
 To run the file:
 
-```bash
-$ bun ./cat.ts ./path-to-file
+```bash terminal icon="terminal"
+bun ./cat.ts ./path-to-file
 ```
 
 It runs 2x faster than GNU `cat` for large files on Linux.
 
-{% image src="/images/cat.jpg" /%}
+<Frame>![Cat screenshot](/images/cat.jpg)</Frame>
+
+---
 
 ## Reference
 
@@ -331,13 +279,7 @@ interface Bun {
 
   write(
     destination: string | number | BunFile | URL,
-    input:
-      | string
-      | Blob
-      | ArrayBuffer
-      | SharedArrayBuffer
-      | TypedArray
-      | Response,
+    input: string | Blob | ArrayBuffer | SharedArrayBuffer | TypedArray | Response,
   ): Promise<number>;
 }
 
@@ -354,9 +296,7 @@ interface BunFile {
 }
 
 export interface FileSink {
-  write(
-    chunk: string | ArrayBufferView | ArrayBuffer | SharedArrayBuffer,
-  ): number;
+  write(chunk: string | ArrayBufferView | ArrayBuffer | SharedArrayBuffer): number;
   flush(): number | Promise<number>;
   end(error?: Error): number | Promise<number>;
   start(options?: { highWaterMark?: number }): void;

package/docs/{api/file-system-router.md → runtime/file-system-router.mdx}

@@ -1,4 +1,9 @@
-Bun provides a fast API for resolving routes against file-system paths. This API is primarily intended for library authors. At the moment only Next.js-style file-system routing is supported, but other styles may be added in the future.
+---
+title: File System Router
+description: Bun provides a fast API for resolving routes against file-system paths
+---
+
+This API is primarily intended for library authors. At the moment only Next.js-style file-system routing is supported, but other styles may be added in the future.
 
 ## Next.js-style
 
@@ -16,13 +21,14 @@ pages
 
 The `FileSystemRouter` can be used to resolve routes against this directory:
 
-```ts
+```ts router.ts
 const router = new Bun.FileSystemRouter({
   style: "nextjs",
   dir: "./pages",
   origin: "https://mydomain.com",
   assetPrefix: "_next/static/"
 });
+
 router.match("/");
 
 // =>