PEABIND(1)

NAME

peabind — generate JavaScript ↔ native bindings for QuickJS and WebAssembly

SYNOPSIS

peabind <idl> <sources...> --output <file> --target <quickjs|wasm> [--prefix <name>]

DESCRIPTION

peabind is a tool that lets you call C++ code from JavaScript.

You describe your API once (in a simple JSON IDL), and peabind generates everything needed to expose it to JavaScript — either:

• inside an embedded engine like QuickJS
• or as a WebAssembly module usable from standard JavaScript

The focus is on usability:

Write C++ → describe it → use it from JavaScript.

You do not need to deal with:

• JS engine internals
• manual binding code
• cross-language memory handling

ARGUMENTS

<idl>

The first positional argument.

Path to the IDL JSON file describing your API.

<sources...>

All remaining positional arguments before flags.

C++ source files implementing the API.

OPTIONS

--output <file>

Output file. Its extension must match the selected target.

--target <quickjs|wasm>

Selects the output type.

• quickjs → generates C++ bindings
• wasm → generates JavaScript + WebAssembly module

--prefix <name>

Optional.

Used mainly for the QuickJS target:

• prefixes generated symbols
• defines the init function name

Has little practical effect for the WASM target.

BASIC USAGE

Example (WASM)

peabind api.json api.cpp --output module.js --target wasm

Given a api.cpp source file:

int add(int a, int b) {
  return a+b;
}

And a api.json idl description file:

{
  "functions": {
    "add": {"return": "int", "args": ["int","int"]}
  }
}

You can use it from JavaScript like a normal module:

import * as mod from "./module.js";

let result = mod.add(1, 2);

Example (QuickJS)

peabind api.json api.cpp --output bindings.cpp --target quickjs --prefix mod

Integrate in C++:

JSContext *ctx;

// Init quickjs...

mod_init(ctx);

TARGETS

QUICKJS

--target quickjs --output bindings.cpp

Generates:

• bindings.cpp
• bindings.h

You compile these into your application.

Entry Point

void mod_init(JSContext *ctx);

Where mod comes from --prefix.

WASM

--target wasm --output module.js

Generates:

• module.js
• module.wasm

In this mode:

• compilation to WebAssembly is handled internally
• intermediate steps are hidden

You can import the result like a normal JavaScript module.

FUNCTIONS

Functions are exposed as JavaScript functions:

mod.add(1, 2);

CLASSES

C++ classes become JavaScript classes.

IDL:

{
  "classes": {
    "Counter": {
      "methods": {
        "inc": {},
        "get": { "return": "int" }
      }
    }
  }
}

Usage:

let c = new mod.Counter();
c.inc();
console.log(c.get());

COMMON WORKFLOWS

Embedded (QuickJS)

1. Generate bindings
2. Compile into application
3. Call init function
4. Use from JS

Web / Node.js (WASM)

1. Generate module
2. Import in JavaScript
3. Call functions directly

WHAT PEABIND HANDLES

• JS ↔ C++ type conversion
• Function dispatch
• Object identity across calls
• Memory safety across the boundary
• WASM compilation pipeline

LIMITATIONS

• Requires explicit IDL
• Output must match target
• Debugging may involve generated code
• GC timing is non-deterministic

FILES

QuickJS

bindings.cpp
bindings.h

WASM

module.js
module.wasm

SUMMARY

peabind lets you expose C++ code to JavaScript with a simple interface description, targeting both embedded QuickJS environments and WebAssembly modules.

"decl": ["static", "promise", "expected","allownull"]