USVString characteristics
USVString does not contain invalid surrogate pairs, so its text can be represented correctly in UTF-8.
runtime/bindgen
22 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Bindgen file naming and location
Bindgen scans for `*.bind.ts` files to find function and class definitions. The binding file should be placed next to its corresponding Rust implementation file.
Bindgen code generation purpose
The bindings generator generates glue code to interop between JavaScript and native code. It eventually replaces the Classes generator for custom classes and JS2Native for ad-hoc calls from JavaScript to native code.
Rust binding function signature for Bindgen
Binding functions in Rust take a `&JSGlobalObject` parameter and return `JsResult<T>`. The function must convert non-memory-related failures into thrown errors using `global.throw_pretty()` with descriptive error messages.
Accessing generated Rust bindgen module
On the Rust side, the generated module is reachable as `crate::r#gen::<basename>` where `<basename>` matches the `.bind.ts` filename. To construct a JSFunction, use `generated::create_<function_name>_callback(global)`. Function names are converted from camelCase to snake_case.
Accessing bindgen functions from JavaScript
In JavaScript files in `src/js/`, `$bindgenFn("<basename>.bind.ts", "<function_name>")` returns a handle to the native implementation.
Bindgen TypeScript binding file example
A binding file uses the `fn` and `t` exports from bindgen. The `args` object defines function parameters with their types, and `ret` specifies the return type. Example: ```ts import { fn, t } from "bindgen"; export const add = fn({ args: { global: t.globalObject, a: t.i32, b: t.i32.default(-1), }, ret: t.i32, }); ```
String types in Bindgen
Bindgen supports three string types: `t.DOMString`, `t.ByteString`, and `t.USVString`, which map directly to WebIDL counterparts and have different conversion logic. All pass `bun_core::String` to native code. `t.UTF8String` works like `t.DOMString` but eagerly converts to UTF-8, passing a `&[u8]` slice that is freed after the function returns. When in doubt, use `t.DOMString`.
ByteString limitations and characteristics
ByteString can only contain valid latin1 characters. It is not safe to assume `bun_core::String` is already in 8-bit format, but it is extremely likely.
Function variants and overloads in Bindgen
The `variants` key declares multiple variants (overloads) of a function. Each variant is a separate object in the array with its own `args` and `ret` properties. Each variant gets a numbered Rust function: `action1`, `action2`, etc.
Bindgen function variants example
```ts import { fn, t } from "bindgen"; export const action = fn({ variants: [ { args: { a: t.i32, }, ret: t.i32, }, { args: { a: t.DOMString, }, ret: t.DOMString, }, ], }); ``` On the Rust side, this generates `pub fn action1(a: i32) -> i32` and `pub fn action2(a: bun_core::String) -> bun_core::String`.
t.dictionary in Bindgen
A `dictionary` describes a JavaScript object, typically used as a function input. For function outputs, prefer a class type so you can add methods and support destructuring.
t.stringEnum in Bindgen
t.stringEnum creates a WebIDL enumeration and generates a new enum type. Bindgen sorts enum values alphabetically before emitting the C++ enum class, so discriminants must match the generated header's order, not the declaration order in the .bind.ts file.
stringEnum example in Bindgen
```ts export const Formatter = t.stringEnum("highlight-javascript", "highlight-javascript-redacted", "escape-powershell"); export const fmtString = fn({ implNamespace: "js_bindings", args: { global: t.globalObject, code: t.UTF8String, formatter: Formatter, }, ret: t.DOMString, }); ``` On the Rust side, this generates a `#[repr(u8)]` enum with discriminants ordered alphabetically: EscapePowershell = 0, HighlightJavascript = 1, HighlightJavascriptRedacted = 2.
implNamespace in Bindgen
Setting `implNamespace: "foo"` on a `fn({...})` routes the generated call to `crate::<basename>::foo::fn_name` instead of `crate::<basename>::fn_name`. Use this to group related binding implementations under a submodule.
t.oneOf in Bindgen
A `oneOf` is a union of two or more types. It is represented as a Rust `enum` with one variant per member type.
Bindgen type attributes
Attributes can be chained onto `t.*` types. Common attributes that apply to all types are `.required` (in dictionary parameters only), `.optional` (in function arguments only), and `.default(T)`. When a value is `.optional`, it is lowered to a Rust `Option<T>`.
Bindgen type attributes example
```ts export const requiredAndOptionalArg = fn({ args: { a: t.boolean, b: t.usize.optional, c: t.i32.enforceRange(0, 100).default(42), d: t.u8.optional, }, ret: t.i32, }); ``` In Rust: `pub fn required_and_optional_arg(a: bool, b: Option<usize>, c: i32, d: Option<u8>) -> i32`
Integer type attributes in Bindgen
Integer types take `clamp` or `enforceRange` to customize overflow behavior. `enforceRange()` with no arguments enforces the type's native range. `clamp()` clamps values to a range. Both can take custom min/max arguments: `enforceRange(0, 1000)` or `clamp(0, 10)`.
Integer type attributes example in Bindgen
```ts import { fn, t } from "bindgen"; export const add = fn({ args: { global: t.globalObject, a: t.i32.enforceRange(), b: t.u16, c: t.i32.enforceRange(0, 1000).default(5), d: t.u16.clamp(0, 10).optional, }, ret: t.i32, }); ```
Node.js validator functions in Bindgen
Bindgen provides Node.js validator functions such as `validateInteger`, `validateInt32`, `validateNumber`, and `validateNumber(min, max)` for implementing Node.js APIs so error messages match Node exactly. These are much stricter than WebIDL validators; for example, Node's numerical validator checks `typeof value === 'number'`, while WebIDL uses `ToNumber` for lossy conversion.
Node.js validator functions example in Bindgen
```ts import { fn, t } from "bindgen"; export const add = fn({ args: { global: t.globalObject, a: t.f64.validateNumber(), b: t.i32.validateInt32(), c: t.f64.validateInteger(), d: t.f64.validateNumber(-10000, 10000), }, ret: t.i32, }); ```