ffi qjs-ffi
libffi + dlopen for QuickJS

qjs-ffi: call C from JavaScript, no glue code

Load a shared library, describe a prototype, call it. qjs-ffi is a small loadable QuickJS module built on libffi, with a bun:ffi-style API, native-to-JS callbacks, direct memory access, an optional in-memory C compiler, and a generator that turns a C or C++ header into a ready-made binding, for QuickJS, bun, Deno or Node.

Example:

import { dlopen } from 'ffi';

const { symbols } = dlopen(null, {
  strlen: { args: ['cstring'], returns: 'u64_fast' },
  getenv: { args: ['cstring'], returns: 'cstring' },
});

console.log(symbols.strlen('hello, world')); // 12
console.log(symbols.getenv('HOME'));
import { CFunction, dlsym, RTLD_DEFAULT } from 'ffi';

const strdup = CFunction({
  ptr: dlsym(RTLD_DEFAULT, 'strdup'),
  args: ['cstring'],
  returns: 'cstring',
});

console.log(strdup('hello')); // hello
import { linkSymbols, dlsym, RTLD_DEFAULT } from 'ffi';

const { symbols } = linkSymbols({
  abs: { args: ['i32'], returns: 'i32' }, // found with dlsym(RTLD_DEFAULT, 'abs')
  labs: { ptr: dlsym(RTLD_DEFAULT, 'labs'), args: ['i64'], returns: 'i64' },
});

console.log(symbols.abs(-5)); // 5
console.log(symbols.labs(-9007199254740993n)); // 9007199254740993n
import { JSCallback, CFunction, dlsym, read, RTLD_DEFAULT } from 'ffi';

const compare = new JSCallback((a, b) => read.i32(a) - read.i32(b), {
  args: ['pointer', 'pointer'],
  returns: 'i32',
});
const qsort = CFunction({ ptr: dlsym(RTLD_DEFAULT, 'qsort'), args: ['pointer', 'u64', 'u64', 'pointer'], returns: 'void' });

const numbers = new Int32Array([5, 3, 9, 1]);
qsort(numbers, numbers.length, 4n, compare.ptr);
console.log(numbers); // 1, 3, 5, 9
import { ptr, read, toArrayBuffer } from 'ffi';

const bytes = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
const p = ptr(bytes);

console.log(read.u8(p, 2)); // 3
console.log(read.u32(p, 4)); // 134678021 (0x08070605)

const view = new Uint8Array(toArrayBuffer(p, 2, 3)); // the same memory
bytes[3] = 99;
console.log(view); // 3, 99, 5

Why qjs-ffi

Writing a QuickJS binding in C for every library is a lot of code for a few calls. This is the shortcut.

01

Typed calls

dlopen() and CFunction prepare the libffi call interface once and give back plain JS functions, with no name lookup per call. Types follow bun:ffi: i32, u64 (an exact bigint), f64, pointer, cstring, and structs passed or returned by value. A class that extends ArrayBuffer is a type too: pass an instance, get one back.

02

Callbacks and memory

JSCallback turns a JS function into a real native function pointer, so C code can call back into your script. read.u32(ptr, off), toArrayBuffer() (with a native deallocator) and CString reach native memory without a copy.

03

C on the fly

cc() compiles C source in memory with TinyCC and hands back its functions with the same typed signatures, like bun's cc(). Optional: build with -DENABLE_TCC=ON; without it the module stays at about 100 KB.

04

Bindings included

lib/ ships generated bindings for cairo, SDL2, freetype, libcurl, libusb, libarchive and zlib. tools/gen-bindings.js makes one for any other header, using clang's AST: structs, unions, #defines, enums and C++ classes with virtual methods. --target=bun|deno|node writes the same bindings for bun:ffi, Deno.dlopen and Node 26's node:ffi.

One header, four runtimes

The generator writes the same module for QuickJS, bun, Deno and Node. SDL2's 816 functions load in about 25–130 ms on each, and a call returns the same value on all four.

for t in qjs bun deno node; do
  qjs-ffi-genbindings --target=$t --library=libSDL2-2.0.so.0 --structs \
    --follow-includes -I/usr/include/SDL2 -o sdl.$t.mjs /usr/include/SDL2/SDL.h
done
import * as sdl from './sdl.mjs';   // sdl.qjs.mjs, sdl.bun.mjs, ...

const v = new sdl.SDL_version();
sdl.SDL_GetVersion(v);
console.log(v.major, v.minor, v.patch); // 2 30 0, under qjsm, bun, deno and node

A struct is a class you can new and read fields from, a C++ virtual method is called through the object's vtable, and a header's constants are exported. The few things a runtime cannot do (structs by value on bun and node, variadic functions on bun, Deno and node) are skipped, with the reason written at the end of the module. See generating bindings.

Compile C where you use it

With the ENABLE_TCC build, cc() compiles a C file in memory and links it into the running process. No compiler on the target, no shared library to ship.

/* fib.c */
long fib(int n) {
  return n < 2 ? n : fib(n - 1) + fib(n - 2);
}
import { cc } from 'ffi';

const { symbols: { fib } } = cc({
  source: 'fib.c',
  symbols: { fib: { args: ['int'], returns: 'i64_fast' } },
});

console.log(fib(30)); // 832040

Install

Needs CMake, the libffi development files, and QuickJS with its qjsm launcher to load the module into.

git clone https://github.com/rsenn/qjs-ffi.git
cd qjs-ffi
cmake -S . -B build && cmake --build build --target quickjs-ffi
export QUICKJS_MODULE_PATH=$PWD/build
qjsm examples/cairo.js        # draws a PNG with the generated cairo binding

Add -DENABLE_TCC=ON to the first command to get cc(). Installation and first steps, then the reference: types, pointers and memory, the C compiler, generating bindings.