crossbind
GitHub

C++

There are no binding macros to write: the generator reads your header and writes the bridge. It handles a subset of C++. Inside it everything binds; outside it, wrap the API in something that does.

The rules

The public surface belongs in the header

The binder reads only headers: a class defined only in the .cpp, an anonymous namespace around the API or a file-scope static function is invisible to it. Public members bind; private ones do not.

Single inheritance only

Single-base virtual polymorphism works. Multiple inheritance, diamonds especially, breaks the binder: use composition or a wrapper.

Templates need explicit instantiation

C++
template<typename T> class Buffer { /* ... */ };
 
// name the instantiations you want in JavaScript
template class Buffer<int>;
template class Buffer<float>;

Fields are properties

Public fields of numbers, bool and std::string, in a class or a C struct, read and write as properties. Fields of vector, shared_ptr or class type need accessor methods, and arrays are not bound.

Returning unique_ptr
A std::unique_ptr returned across the boundary fails silently: the call returns null or undefined. Use std::shared_ptr for anything JavaScript holds.

Primitive types

C++JavaScriptNote
voidundefined
booltrue / false
char, short, int and unsigned formsNumbera char parameter also takes a one-character string
float, doubleNumber
int64_t, uint64_t, long longBigInttakes a BigInt or a safe-integer Number
long, size_tNumber on wasm32, BigInt on React Native
std::stringString
const char *Stringsee pointers
std::optional<T>the value or nullC++17, every runtime
emscripten::valanythingthe untyped escape hatch

An argument of the wrong type throws a TypeError instead of crossing as 0. An enum parameter takes a member of the enum or its number.

Vectors, maps and enums

Vectors bind under generated names: VectorInt, VectorDouble, VectorString, VectorInt64 and so on. std::vector<MyClass> becomes VectorMyClass.

JavaScript
const myVector = getMyVector();
 
for (let i = 0; i < myVector.size(); i += 1) {
console.log(myVector.get(i));
}
 
const next = new VectorInt();
next.push_back(9);
setMyVector(next);

To work with plain arrays, convert with two module helpers:

JavaScript
const values = m.toArray(getMyVector()); // vector -> Array
values.push(9);
setMyVector(m.toVector(VectorInt, values)); // Array -> vector

Maps bind the same way (MapIntInt, MapStringString, MapStringInt, MapIntString). Enums, enum and enum class alike, arrive as objects keyed by their member names.

Worker mode returns arrays
In worker mode a returned std::vector arrives as a plain array instead of a vector. m.toArray() takes both, so code that uses it works either way.

Pointers

Raw pointers bind. What cannot become an object crosses as a handle: an opaque NativePointer that holds the address and owns what crossbind allocated for it.

C++JavaScript
const char * parametera string, a handle or null
const char * returna string or null
char *, void *, T **, pointers to numbersa handle
T * to a class or struct the header bindsan instance
T * to a type the header only declares (sqlite3, PJ)a handle
int &, double &, std::string & out-parametersa handle from allocPointer or allocString, read back afterwards
function pointera JavaScript function, a handle or null

Every module that binds a pointer also exports helpers to make and read handles: cstring and readCString, allocBuffer and allocPointer (zero-filled), allocString and readString, readNumberAt and writeNumberAt, readPointerAt and writePointerAt, readBuffer (a Uint8Array copy) and writeBuffer, and releaseCallback.

C++
void process(int* data, size_t len);
char* getName();
size_t encode(unsigned char* out, size_t cap);
JavaScript
const data = allocBuffer(3 * 4);
[7, 8, 9].forEach((n, i) => writeNumberAt(data, i, 'int32', n));
process(data, 3);
 
const name = readCString(getName());
 
const out = allocBuffer(1024);
const bytes = readBuffer(out, encode(out, 1024));

Only const char * converts to a string. A char * result is memory the library hands over: it stays a handle you read and then free the library's way. A string passed for a const char * lives only for the call; if C keeps the pointer, pass a cstring handle and keep it until C is done.

A JavaScript function passed for a function pointer holds a slot in the module until releaseCallback(fn) frees it. With useWorker: true, handles are proxies and JavaScript functions cannot cross into the worker.

Constants and macros

A #define with a number, character, string or boolean value, and a const or constexpr global of those types, bind as module constants. Only the names you import bind, so thousands of macros cost nothing until you use one:

src/main.js
import { deflateInit2_, Z_DEFLATED, MAX_WBITS, ZLIB_VERSION } from '@crossbind/port-zlib/zlib.h';

A function-like macro that calls one bound function, a macro that renames one, a variadic function and a mutable global bind as well, but only when you name them in an import { ... }; import * as reaches none of them. Details: cpp-binding-rules.md.

What a library header binds

Your own headers bind every function and class. A dependency's header (a port or a ConanCenter package) binds its enums, the functions you import and the classes they reach, with their bases. What nothing you import reaches is left out, and so is the library code only it uses.

src/main.js
import { GDALAllRegister, GDALOpenEx, GDALClose } from '@crossbind/port-gdal/gdal.h';

import * as, import(), require, a bare import 'x.h' and an import of initNative alone bind the whole header. Otherwise a function you call through the module object (m.GDALVersionInfo()) still needs a named import; without one the call fails with m.GDALVersionInfo is not a function. Dev servers bind a newly imported function when you save the file.

Exceptions

Report a failure by throwing in C++ and catching in JavaScript, rather than with status codes or out-parameters.

C++
double squareRoot(double x) {
if (x < 0) throw std::invalid_argument("sqrt of negative");
return std::sqrt(x);
}
JavaScript
try {
m.squareRoot(-1);
} catch (e) {
console.error(e.message); // "std::invalid_argument: sqrt of negative"
}

On wasm the message is "<type>: <what()>", with the halves also available as e.cppType and e.cppMessage. On React Native (JSI) and in a Node-API addon it is the plain what() text.

Memory

A handle frees only what crossbind allocated for it. When objects are freed, and when to call .delete(): Object lifetime.

Wrapping what does not fit

For a library full of templates, multiple inheritance or pointer-heavy calls, put a clean class in front of it. The wrapper binds; the upstream type stays inside it.

src/native/wrapper.h
#pragma once
#include "upstream/upstream.h"
#include <memory>
#include <vector>
 
class CleanWrapper {
public:
CleanWrapper();
std::vector<float> process(const std::vector<float>& input);
private:
std::shared_ptr<upstream::RawType> raw_;
};

An app keeps its wrappers in src/native. A published package carries its own, so everyone who installs it gets them.

TypeScript

Types for every header and Rust import are generated under .crossbind/. Setting them up, and dts: 'promise' for worker mode: Runtime API.

The escape hatch

When neither the rules nor a wrapper fit, hand-write a SWIG interface file next to the header and import it from JavaScript. It is also how you register a container the generator does not cover:

src/native/mycustom.i
#pragma once
 
%module mycustom
 
%{
EMSCRIPTEN_BINDINGS(mycustom) {
emscripten::register_vector<Abc>("VectorAbc");
}
%}
 
%feature("shared_ptr");
%feature("polymorphic_shared_ptr");
src/index.js
import './native/mycustom.i';
Type to search every guide page and section.
↑↓ navigate↵ openesc close