implementing-jsc-classes-rust

Bun's JavaScriptCore Class Bindings Generator

Bridge JavaScript and Rust through .classes.ts definitions and Rust implementations.

Architecture

1. JavaScript Interface Definition (.classes.ts files)
2. Rust Implementation (.rs files)
3. 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.

Class Definition (.classes.ts)

export default [
  define({
    name: "Glob",
    construct: true,
    finalize: true,
    hasPendingActivity: true,
    proto: {
      scan:  { fn: "scan",  length: 1 },
      match: { fn: "match", length: 1 },
    },
  }),
];

Options:

• construct: Has a public new Foo() constructor
• finalize: Needs cleanup beyond Drop (rarely — see Finalize below)
• hasPendingActivity: GC keep-alive while async work is in flight
• proto: Methods (fn:), getters (getter: true, optionally cache: true)
• values: [...]: WriteBarrier slots for JS values the native side holds (callbacks, buffers)

Rust Implementation

use bun_jsc::{CallFrame, JSGlobalObject, JSValue, JsResult};
use std::sync::atomic::{AtomicUsize, Ordering};

#[bun_jsc::JsClass]
pub struct Glob {
    pattern: Box<[u8]>,
    has_pending_activity: AtomicUsize,
}

impl Glob {
    pub fn constructor(global: &JSGlobalObject, frame: &CallFrame) -> JsResult<Box<Glob>> {
        let arg = frame.argument(0);
        let pattern = bun_core::String::from_js(arg, global)?.to_utf8_bytes().into();
        Ok(Box::new(Glob { pattern, has_pending_activity: AtomicUsize::new(0) }))
    }

    #[bun_jsc::host_fn(method)]
    pub fn r#match(&self, global: &JSGlobalObject, frame: &CallFrame) -> JsResult<JSValue> {
        // ...
        Ok(JSValue::TRUE)
    }

    pub fn has_pending_activity(&self) -> bool {
        self.has_pending_activity.load(Ordering::SeqCst) > 0
    }
}

Canonical signatures