implementing-jsc-classes-rust

Source excerpt starting at line 1.

1---2name: implementing-jsc-classes-rust3description: Creates JavaScript classes using Bun's Rust bindings generator (.classes.ts). Use when implementing new JS APIs in Rust with JSC integration, prototypes, or constructors.4---5 6# Bun's JavaScriptCore Class Bindings Generator7 8Bridge JavaScript and Rust through `.classes.ts` definitions and Rust implementations.9 10## Architecture11 121. **JavaScript Interface Definition** (`.classes.ts` files)132. **Rust Implementation** (`.rs` files)143. **Generated Code** — `src/codegen/generate-classes.ts` emits C++ + Rust into `${BUN_CODEGEN_DIR}/generated_classes.rs`, `include!`d as `crate::generated_classes` in `bun_runtime`. Run `bun bd` to regenerate.15 16## Class Definition (.classes.ts)17 18```typescript19export default [20  define({21    name: "Glob",22    construct: true,23    finalize: true,24    hasPendingActivity: true,25    proto: {26      scan:  { fn: "scan",  length: 1 },27      match: { fn: "match", length: 1 },28    },29  }),30];31```32 33Options:34 35- `construct`: Has a public `new Foo()` constructor36- `finalize`: Needs cleanup beyond `Drop` (rarely — see Finalize below)37- `hasPendingActivity`: GC keep-alive while async work is in flight38- `proto`: Methods (`fn:`), getters (`getter: true`, optionally `cache: true`)39- `values: [...]`: WriteBarrier slots for JS values the native side holds (callbacks, buffers)40 41## Rust Implementation42 43```rust44use bun_jsc::{CallFrame, JSGlobalObject, JSValue, JsResult};45use std::sync::atomic::{AtomicUsize, Ordering};46 47#[bun_jsc::JsClass]48pub struct Glob {49    pattern: Box<[u8]>,50    has_pending_activity: AtomicUsize,51}52 53impl Glob {54    pub fn constructor(global: &JSGlobalObject, frame: &CallFrame) -> JsResult<Box<Glob>> {55        let arg = frame.argument(0);56        let pattern = bun_core::String::from_js(arg, global)?.to_utf8_bytes().into();57        Ok(Box::new(Glob { pattern, has_pending_activity: AtomicUsize::new(0) }))58    }59 60    #[bun_jsc::host_fn(method)]61    pub fn r#match(&self, global: &JSGlobalObject, frame: &CallFrame) -> JsResult<JSValue> {62        // ...63        Ok(JSValue::TRUE)64    }65 66    pub fn has_pending_activity(&self) -> bool {67        self.has_pending_activity.load(Ordering::SeqCst) > 068    }69}70```71 72### Canonical signatures73 74| Hook                | Signature                                                                            |75| ------------------- | ------------------------------------------------------------------------------------ |76| constructor         | `pub fn constructor(global: &JSGlobalObject, frame: &CallFrame) -> JsResult<Box<Self>>` |77| method (`fn:`)      | `pub fn name(&self, global: &JSGlobalObject, frame: &CallFrame) -> JsResult<JSValue>`   |78| getter              | `pub fn get_x(this: &Self, global: &JSGlobalObject) -> JsResult<JSValue>`               |79| finalize            | `pub fn finalize(self: Box<Self>)` — or omit; the blanket `JsFinalize` just drops    |80| hasPendingActivity  | `pub fn has_pending_activity(&self) -> bool`                                         |81 82A missing or mis-typed hook is a **compile error** in `cargo check -p bun_runtime` — the generated code calls the inherent method directly.83 84## Hooking into the generated module85 86`#[bun_jsc::JsClass]` on the struct implements the `JsClass` trait (`to_js`, `from_js`, `from_js_direct`, `get_constructor`) by binding the C++ externs. Attribute knobs: `no_constructor`, `no_finalize`, `estimated_size`.87 88The codegen also emits a `js_$T` module with the cached-value accessors. Re-export it when you need `*_set_cached` / `*_get_cached` or `detach_ptr`:89 90```rust91pub use crate::generated_classes::js_Glob as js;92// or93bun_jsc::impl_js_class_via_generated!(Archive => crate::generated_classes::js_Archive);94```95 96The `js_$T` module surface:97 98```rust99pub fn from_js(value: JSValue) -> Option<NonNull<T>>;100pub fn from_js_direct(value: JSValue) -> Option<NonNull<T>>;101pub fn get_constructor(global: &JSGlobalObject) -> JSValue;102pub fn to_js(this: *mut T, global: &JSGlobalObject) -> JSValue;   // ownership transfer103pub fn detach_ptr(value: JSValue);104// per cached getter / `values: [...]` entry:105pub fn <field>_set_cached(this_value: JSValue, global: &JSGlobalObject, value: JSValue);106pub fn <field>_get_cached(this_value: JSValue) -> Option<JSValue>;107```108 109## Finalize110 111Most classes need nothing — `#[bun_jsc::JsClass]` wires the blanket `JsFinalize` whose default is `drop(Box<Self>)`. Override only when you must release a JS handle or defer to a heap helper:112 113```rust114pub fn finalize(self: Box<Self>) {115    bun_ptr::finalize_js_box(self, |this| this.this_value.with_mut(|v| v.finalize()));116}117```118 119Override with an **inherent** method, never `impl JsFinalize for T`.120 121## Holding JS values122 123Never store raw `JSValue` in a struct field. Declare a slot in `.classes.ts` (`values: ["callback"]` or a `cache: true` getter) and read/write it through `js::callback_set_cached(this_value, global, v)` / `js::callback_get_cached(this_value)`. The slot is a `WriteBarrier` visited by the GC, so the value stays alive without a `Strong`.124 125## Reference implementations126 127- `src/runtime/api/glob.rs` + `Glob.classes.ts` — constructor, methods, `hasPendingActivity`, default finalize128- `src/runtime/api/cron.rs` + `cron.classes.ts` — `noConstructor`, cached getter, `values: [...]`, custom finalize129- `src/runtime/image/Image.rs:56` — the `pub use crate::generated_classes::js_Image as js;` one-liner130- `src/jsc/host_fn.rs` — the host-fn adapters the codegen dispatches through131- `src/jsc_macros/lib.rs` — `#[bun_jsc::JsClass]` proc-macro source132