用途:在 Bun 中通过 .classes.ts 定义与 Rust 实现,为 JavaScriptCore 创建 JavaScript 类,适合用 Rust 实现新的 JS API、原型及 JSC 集成。
主要能力:架构由 JavaScript 接口定义(.classes.ts)、Rust 实现(.rs)和生成代码组成;src/codegen/generate-classes.ts 生成 C++ 与 Rust 到 ${BUN_CODEGEN_DIR}/generated_classes.rs,并以 crate::generated_classes 被 include! 进 bun_runtime,运行 bun bd 重新生成。类定义支持 construct、finalize、hasPendingActivity、proto(方法 fn:、getter: true 及可选 cache: true)、values 等选项。
使用方式:在 .classes.ts 中用 define 声明类;在 Rust 中用 #[bun_jsc::JsClass] 标注结构体,并按规范签名实现 constructor、method、getter、finalize、has_pending_activity 等钩子;缺失或类型错误的钩子会在 cargo check -p bun_runtime 时报编译错误。代码生成还会产出 js_$T 模块,提供 from_js、from_js_direct、get_constructor、to_js、detach_ptr 及缓存访问器,可用 pub use crate::generated_classes::js_Glob as js; 或 impl_js_class_via_generated! 重新导出。
限制与注意:不要在结构体字段中直接存原始 JSValue,应在 .classes.ts 中声明 values 槽或 cache: true 的 getter,并通过 js::*_set_cached / *_get_cached 读写,该槽是 GC 访问的 WriteBarrier。finalize 通常无需实现,默认 drop(Box<Self>);需要释放 JS 句柄时用固有方法覆盖,不要为 T 实现 JsFinalize。参考实现包括 glob.rs、cron.rs、Image.rs、host_fn.rs 与 jsc_macros/lib.rs。