implementing-jsc-classes-cpp

Source excerpt starting at line 1.

1---2name: implementing-jsc-classes-cpp3description: Implements JavaScript classes in C++ using JavaScriptCore. Use when creating new JS classes with C++ bindings, prototypes, or constructors.4---5 6# Implementing JavaScript Classes in C++7 8## Class Structure9 10For publicly accessible Constructor and Prototype, create 3 classes:11 121. **`class Foo : public JSC::DestructibleObject`** - if C++ fields exist; otherwise use `JSC::constructEmptyObject` with `putDirectOffset`132. **`class FooPrototype : public JSC::JSNonFinalObject`**143. **`class FooConstructor : public JSC::InternalFunction`**15 16No public constructor? Only Prototype and class needed.17 18## Iso Subspaces19 20Classes with C++ fields need subspaces in:21 22- `src/jsc/bindings/webcore/DOMClientIsoSubspaces.h`23- `src/jsc/bindings/webcore/DOMIsoSubspaces.h`24 25```cpp26template<typename MyClassT, JSC::SubspaceAccess mode>27static JSC::GCClient::IsoSubspace* subspaceFor(JSC::VM& vm) {28    if constexpr (mode == JSC::SubspaceAccess::Concurrently)29        return nullptr;30    return WebCore::subspaceForImpl<MyClassT, WebCore::UseCustomHeapCellType::No>(31        vm, BUN_SUBSPACE_SLOTS(m_clientSubspaceForMyClassT, m_subspaceForMyClassT));32}33```34 35`subspaceForImpl` only reads the slots inline. The subspaces themselves are created by `subspaceForImplSlow` in `src/jsc/bindings/BunClientData.cpp`, which is the only place that constructs an `IsoSubspace` (`test/internal/source-lints/iso-subspace-creation.test.ts` checks this).36 37## Property Definitions38 39```cpp40static JSC_DECLARE_HOST_FUNCTION(jsFooProtoFuncMethod);41static JSC_DECLARE_CUSTOM_GETTER(jsFooGetter_property);42 43static const HashTableValue JSFooPrototypeTableValues[] = {44    { "property"_s, static_cast<unsigned>(PropertyAttribute::ReadOnly | PropertyAttribute::CustomAccessor), NoIntrinsic, { HashTableValue::GetterSetterType, jsFooGetter_property, 0 } },45    { "method"_s, static_cast<unsigned>(PropertyAttribute::Function), NoIntrinsic, { HashTableValue::NativeFunctionType, jsFooProtoFuncMethod, 1 } },46};47```48 49## Prototype Class50 51```cpp52class JSFooPrototype final : public JSC::JSNonFinalObject {53public:54    using Base = JSC::JSNonFinalObject;55    static constexpr unsigned StructureFlags = Base::StructureFlags;56 57    static JSFooPrototype* create(JSC::VM& vm, JSC::JSGlobalObject* globalObject, JSC::Structure* structure) {58        JSFooPrototype* prototype = new (NotNull, allocateCell<JSFooPrototype>(vm)) JSFooPrototype(vm, structure);59        prototype->finishCreation(vm);60        return prototype;61    }62 63    template<typename, JSC::SubspaceAccess>64    static JSC::GCClient::IsoSubspace* subspaceFor(JSC::VM& vm) { return &vm.plainObjectSpace(); }65 66    DECLARE_INFO;67 68    static JSC::Structure* createStructure(JSC::VM& vm, JSC::JSGlobalObject* globalObject, JSC::JSValue prototype) {69        auto* structure = JSC::Structure::create(vm, globalObject, prototype, JSC::TypeInfo(JSC::ObjectType, StructureFlags), info());70        structure->setMayBePrototype(true);71        return structure;72    }73 74private:75    JSFooPrototype(JSC::VM& vm, JSC::Structure* structure) : Base(vm, structure) {}76    void finishCreation(JSC::VM& vm);77};78 79void JSFooPrototype::finishCreation(VM& vm) {80    Base::finishCreation(vm);81    reifyStaticProperties(vm, JSFoo::info(), JSFooPrototypeTableValues, *this);82    JSC_TO_STRING_TAG_WITHOUT_TRANSITION();83}84```85 86## Getter/Setter/Function Definitions87 88```cpp89// Getter90JSC_DEFINE_CUSTOM_GETTER(jsFooGetter_prop, (JSGlobalObject* globalObject, EncodedJSValue thisValue, PropertyName)) {91    VM& vm = globalObject->vm();92    auto scope = DECLARE_THROW_SCOPE(vm);93    JSFoo* thisObject = jsDynamicCast<JSFoo*>(JSValue::decode(thisValue));94    if (UNLIKELY(!thisObject)) {95        Bun::throwThisTypeError(*globalObject, scope, "JSFoo"_s, "prop"_s);96        return {};97    }98    return JSValue::encode(jsBoolean(thisObject->value()));99}100 101// Function102JSC_DEFINE_HOST_FUNCTION(jsFooProtoFuncMethod, (JSGlobalObject* globalObject, CallFrame* callFrame)) {103    VM& vm = globalObject->vm();104    auto scope = DECLARE_THROW_SCOPE(vm);105    auto* thisObject = jsDynamicCast<JSFoo*>(callFrame->thisValue());106    if (UNLIKELY(!thisObject)) {107        Bun::throwThisTypeError(*globalObject, scope, "Foo"_s, "method"_s);108        return {};109    }110    return JSValue::encode(thisObject->doSomething(vm, globalObject));111}112```113 114## Constructor Class115 116```cpp117class JSFooConstructor final : public JSC::InternalFunction {118public:119    using Base = JSC::InternalFunction;120    static constexpr unsigned StructureFlags = Base::StructureFlags;121 122    static JSFooConstructor* create(JSC::VM& vm, JSC::Structure* structure, JSC::JSObject* prototype) {123        JSFooConstructor* constructor = new (NotNull, JSC::allocateCell<JSFooConstructor>(vm)) JSFooConstructor(vm, structure);124        constructor->finishCreation(vm, prototype);125        return constructor;126    }127 128    DECLARE_INFO;129 130    template<typename CellType, JSC::SubspaceAccess>131    static JSC::GCClient::IsoSubspace* subspaceFor(JSC::VM& vm) { return &vm.internalFunctionSpace(); }132 133    static JSC::Structure* createStructure(JSC::VM& vm, JSC::JSGlobalObject* globalObject, JSC::JSValue prototype) {134        return JSC::Structure::create(vm, globalObject, prototype, JSC::TypeInfo(JSC::InternalFunctionType, StructureFlags), info());135    }136 137private:138    JSFooConstructor(JSC::VM& vm, JSC::Structure* structure) : Base(vm, structure, callFoo, constructFoo) {}139 140    void finishCreation(JSC::VM& vm, JSC::JSObject* prototype) {141        Base::finishCreation(vm, 0, "Foo"_s);142        putDirectWithoutTransition(vm, vm.propertyNames->prototype, prototype, JSC::PropertyAttribute::DontEnum | JSC::PropertyAttribute::DontDelete | JSC::PropertyAttribute::ReadOnly);143    }144};145```146 147## Structure Caching148 149Add to `ZigGlobalObject.h`:150 151```cpp152JSC::LazyClassStructure m_JSFooClassStructure;153```154 155Initialize in `ZigGlobalObject.cpp`:156 157```cpp158m_JSFooClassStructure.initLater([](LazyClassStructure::Initializer& init) {159    Bun::initJSFooClassStructure(init);160});161```162 163Visit in `visitChildrenImpl`:164 165```cpp166m_JSFooClassStructure.visit(visitor);167```168 169## Expose to Zig170 171```cpp172extern "C" JSC::EncodedJSValue Bun__JSFooConstructor(Zig::GlobalObject* globalObject) {173    return JSValue::encode(globalObject->m_JSFooClassStructure.constructor(globalObject));174}175 176extern "C" EncodedJSValue Bun__Foo__toJS(Zig::GlobalObject* globalObject, Foo* foo) {177    auto* structure = globalObject->m_JSFooClassStructure.get(globalObject);178    return JSValue::encode(JSFoo::create(globalObject->vm(), structure, globalObject, WTFMove(foo)));179}180```181 182Include `#include "root.h"` at the top of C++ files.183