While embedding v8, exposing native objects in Javascript is mostly unavoidable. As easy as it might sound the process involves a very specific set of steps as well as certain design decisions. From Javascript standpoint, there will no difference between a pure Javascript object and a wrapped one. For example, you must be able to extend a native object prototype with a plain Javascript object or vice versa.

The link between Javascript and native world is bidirectional. A native wrappable object, should refer to a single Javascript object (not necessarily, but it will save a lot of headaches at a later stage with garbage collection). This is done by keeping a reciprocal reference between a v8::Persisten<v8::Object> and a native object, or bridging between the two.

It is important to note that now, two inter-related objects exist, a Javascript wrapper and a native wrappable. Both have different lifecycles, and we must bind them in the right way.

Design decisions

Native wrappable objects will extends a base class object: Wrappable. Its purpose is to keep track of the Javascript object wrapping a native object (hence its name) and also does the heavy lifting to associate a native object with a Javascript object, like invoking the constructor, setting Javascript object’s native pointers, etc.

A Wrappable will rely on a WrapperTypeInfo to configure itself. Each potentially wrappable exposed in Javascript will define one such struct. For example, for an actual Event object I define:

const WrapperTypeInfo V8Event::wrapperTypeInfo = {
        V8Event::InterfaceTemplate,        // configuration function
        "Event",                           // js object context
        nullptr                            // inherit from
};

For code simplicity, I will define two cpp files for each object I’d like wrapped and exposed in Javascript. For the Event object sample, a file Event.cpp will keep the delegated methods invoked from javascript. Don’t forgetEvent class extends Wrappable so inherits the possibility to generate the Javascript wrapper on demand. The other file, V8Event.cpp contains all javascript related stuff, like the constructor function, the list of accessors, functions, etc.

Another design decision I make is about object extension. Any Javascript object extending another object, will reflect in its native wrappable extending the another wrappable. Basically, makes sense an object extending another in Javascript, necessarily means c++ class extending another one.

Configuring wrapper objects

Depending on whether we expect this to be part of the global context object, we will create either a v8::FunctionTemplate or a regular v8::Function object.

In this article, I will be creating an Event object in Javascript, which is actually delegating all its functionality to a Native c++ wrappable instance.

FunctionTemplate structure

As we know, a javascript function, is a first class object. It can be called, can be called as a constructor (instanced), which will create a prototype chain if needed, and the function object itself can hold functions and variables. All this translates directly into native code, where a v8::FunctionTemplate object (which we will name interface_template from now on), exposes two methods returning a Local:

// prototype function template
Local<ObjectTemplate> prototype_t= interface_t->PrototypeTemplate();
// instance function template
Local<ObjectTemplate> instance_t = interface_t->InstanceTemplate();

So, for each wrappable object, we will manage 3 different places to add native bindings code to:

• Prototype template will be used, of course, to define accessors and function on the prototype.
• Instance template will be used to add accessors or functions to an instance resulting from calling the constructor function.
• Interface template will be used to add accessors or functions to the constructor function itself. These won’t be accessible from any instance or object prototype though.

Exposing a Constructor function in Javascript

The constructor function is the entry point to instantiate Javascript objects and bind them with native wrappable objects.

The first thing would be to make our instantiation function available in Javascript. This is done by exposing our interface_template in the global context object (or any other object). Something like:

global_template_object->Set(
        v8::String::NewFromUtf8(isolate_, "Event"),
        interface_template->GetFunction());

When in Javascript the Event object is created by calling new Event(), the wrapper will invoke our supplied construction callback. This constructor callback is defined as:

// c++ function invoked when new Event() is called in js.
// see "Javascript-native object relationship" 
interface_template->SetCallHandler(V8Event::constructorCallback);
// constructor length, e.g. number of parameters
interface_template->SetLength(1);

This CallHandler function, is an special native constructor delegate. It is responsible for associating a Javascript with its native wrappable when invoked from javascript as new Event(), but it also must handle the situation when an existing native object, just needs be wrapped and be available in javascript. We’ll see how to do this later in the article.

The CallHandler, has a signature of a regular native function callback:

void constructorCallback(const FunctionCallbackInfo<Value> &ci);

Adding accessors

Accessors will act as properties’ getter and setter function callbacks. Normally I will add accessors in the prototype or instance templates. Or both. But they can be added as well to the interface template. Once in Javascript, there will be no difference with a regular object variable, except for the fact that behind the scenes, a native object is accessed, and a native value is wrapped as a Javascript type.

For accessors in prototypes or instances, we need to add a regular v8::FunctionTemplate representing the getter or setter to the corresponding v8::ObjectTemplate.

Adding accessor to the interface template is a bit different, since its type is v8::FunctionTemplate, and not v8::ObjectTemplate.

Doing this is mostly trivial:

void native_getter(const FunctionCallbackInfo<Value> &info) {
    ...
}

void native_setter(const FunctionCallbackInfo<Value> &info) {
    ...
}

// getters don't need parameters, we pass 0.
Local<FunctionTemplate> getter = v8::FunctionTemplate::New(
        isolate, native_getter, Local<Value>(), Local<Value>(), 0 );

// setter need a parameter, so we pass 1.
Local<FunctionTemplate> setter = v8::FunctionTemplate::New(
        isolate, native_getter, Local<Value>(), Local<Value>(), 1);

// these getter/setter function callbacks don't need a prototype.
getter->RemovePrototype();
setter->RemovePrototype();

// create an accessor name
local<String> name = String::NewFromUtf8( isolate, "prop" );

// binding:
instance_or_template->SetAccessorProperty(
        name, 
        getter, setter,
        attribute         // see v8::PropertyAttribute
);

Now, whenever we call from Javascript ev.prop, the native_getter function is invoked. Our wrappable code starts to make sense now.

We must monotonically perform the same process for each accessor we’d like to have in our Javascript wrapper objects.

Adding functions

Another functionality wrapper objects need is functions. As in the case of accessors, Javascript function callbacks must be defined. Simply enough:

void callback(const FunctionCallbackInfo<Value> &info) {
    ...
}

v8::Local<v8::FunctionTemplate> function_template =
        v8::FunctionTemplate::New(
               isolate, 
               callback, 
               v8::Local<v8::Value>(),
               v8::Local<v8::Value>(), 
               numberOfParameters );

// again, prototype not needed for this callback function
function_template->RemovePrototype();

instance_or_template->Set(
    method.MethodName(isolate), 
    function_template,
    attribute           // see v8::PropertyAttribute    
);

Again, repeat this process for each function we want to be available in our Javascript wrapper.

Javascript-native object relationship — Javascript Instantiation

When code like this is executed in Javascript

 new Event();

the registered constructor callback is invoked. It will also add all defined accessor and function bindings, create the prototype chain, etc. As a native function callback, the signature is:

void constructorCallback(const FunctionCallbackInfo<Value> &ci)

It has three main responsibilities:

1. abort object creation if this is not a valid constructor. For example, TouchList is not instance-able by constructor, so it is safe to throw an exception here. A call of the form will do the trick.

isolate_->ThrowException( v8::Exception::Error( v8::String ... 

// don't forget to return from constructorCallback after throwing...
return;

2. Generate native wrappable instance and associate it with the Javascript object:

// create a wrappable
Event* event = new Event();

// we associate a native Event object, with constructorCallback's
// holder. Holder() points to the object being constructed in 
// javascript.
v8::Local<v8::Object> wrapper = ci.Holder();

// Event instance holds a v8::Persistent<v8::Object> reference
event->wrapper_.Reset(isolate, wrapper);

// Manage gc.
//
// e.g:
//    event->wrapper_.SetWrapperClassId( ...
//    event->wrapper_.SetWeak( ...
// or
//    event->wrapper_.ClearWeak();

3. Bridge the Javascript object with the native wrappable

wrapper->SetAlignedPointerInInternalFields(0, event);

After this code, a Javascript object has a pointer to the wrappable c++ object. And the wrapple c++, has set a v8::Persistent handle to the same Javascript object.

Accessor and Function callbacks

For the three of accessor getter, setter and function callbacks, we must specify a function of type v8::FunctionCallback, that is

void fnName(const FunctionCallbackInfo<Value> &info);

How the Javascript object accesses its native wrappable object is as follows:

void fnName(const FunctionCallbackInfo<Value> &info) {
    Local<Object> holder = info.Holder();
    Event* event = reinterpret_cast<Event*>(
        object->GetAlignedPointerFromInternalField(0));
    info->GetReturnValue().Set( event->name );
}

The key here is where to obtain the native pointer to the wrappable object. And that will always be the Holder object on every FunctionCallback.

Javascript-native object relationship — Native Instantiation

Sometimes, we want to expose in Javascript a native wrappable object w/o it being created from Javascript. For example, a pointer data generated in native needs to make its way through to Javascript.

Event* ev = new Event("load"); 
// set wrappable properties
ev->target = this;
ev->currentTarget = this;
// create a Javascript object to reference to this ev
// native instance.

For this to happen, we need to manually create a Javascript object of the needed type. We have the interface template so seems like a trivial operation, just (deprecated: call it as constructor) new instance the interface template function.

We would be mostly done, except for the fact that this code will invoke the constructorCallback previously defined. Which will create a new Event instance. Our constructorCallback must therefore be aware of the fact that an existing native object is being wrapped instead. Other than that, the code will be the same for the constructorCallback.

// Signal constructorCallback to wrap an existing object, 
// instead of creating a new one. RAII on isolate's private data.
Config::ConstructorMode p = Config::Status::CurrentConstructorMode;    Config::SetCurrentConstructorMode(Config::kWrapExistingObject);
v8::Local<v8::Object> wrapper = interface_template->
        GetFunction()->
        NewInstance( 
           creation_context->CreationContext() 
        ).ToLocalChecked();

// do wrapper association just as in the javascript instantiation
// example.
// restore constructor mode to previous one.
Config::SetCurrentConstructorMode(p);

Needless to say , I also trivially check for an already existing Javascript wrapper for the native object.

Prototype Inheritance

Inheriting a prototype for a wrappable object can only happen from a native prototype. Don’t worry though, you will be able to extend a wrapper object from Javascript.

The inheritance process boils down just to one native call, and must happen at constructor function definition time. This code will extend the prototype chain of our wrapper object:

// function_template->Inherit( v8::Local<v8::FunctionTemplate> );
//
// this function template is the previously defined 
// interface_template
//
interface_template->Inherit(parent_interface_template);

Object naming

By default, wrappable objects will identify themselves in chrome devtools console as the infamous: {} that is, no name. To properly have our wrappables named in dev-tools, we’d need to do a couple things:

1. set the constructor function class name.

interface_template->SetClassName( v8::Local<v8::String> );

This will properly name our wrapper exposed constructor function. Unfortunately, this won’t be sufficient, since our wrapper’s prototype object still won’t show the expected naming. To fix this, a trickier approach must be taken:

2. name our prototype object:

prototype_template->Set(
        v8::Symbol::GetToStringTag(isolate),
        v8::Local<v8::String>,  // desired string representation
        v8::PropertyAttribute); // e.g.: v8::ReadOnly | v8::DontEnum

Putting it all together

I have created this repository where all things covered in this article have been placed. It is a compilable and runnable version of this post.

Conclusion

There is still some other stuff that native wrappable objects can do. Indexed properties, which would accept indexed access on them like an array or for the DOM TouchList object. Interceptors, making an object callable, receivers, signatures, inheritance… v8’s bestiary is fairly interesting and each of the creatures deserve one or more posts to describe them.

At first glance it is not easy to create a Javascript wrapper. Too many steps, for something conceptually simple, specially if we compare it with defining a plain Javascript object. That’s Javascript’s magic. It abstracts away all the dirty details from the developer, like GC, instantiation, wiring, etc. This article might be also useful to realise how complex a browser can just be. We just scratched the surface and shaw how to wire the simplest native object possible.

I’d like to make an explicit disclaimer here. All credit of this article must go to the V8 and Chromium project developers. Being able to scavenge through the whole browser source code has been an invaluable resource to figure out stuff, and to learn very solid foundations on v8 development. On my side I just made the effort of collecting low hanging fruit.