FFI: calling a prebuilt shared library from JS with koffi — and who owns the memory

What FFI is — and how it differs from a native addon

In ten minutes you’ll know exactly why that SIGSEGV from the hook happened, how FFI works at the ABI level, and the three memory rules that separate a production-safe integration from a process-killing time bomb.

The previous lessons built a native addon: you write C/C++ glue against Node-API, compile it to a .node binary, and require it. FFI (Foreign Function Interface) skips the glue entirely. You take an already-compiled shared library — libfoo.so on Linux, .dylib on macOS, .dll on Windows — declare the prototype of the function you want in JavaScript, and a library marshals the call at runtime. No C source of your own, no compiler at install, no .node to build: just open the library and describe the signature.

import koffi from 'koffi';

const libm = koffi.load('libm.so.6');             // dlopen the shared library
const pow  = libm.func('double pow(double, double)'); // declare the C prototype

pow(2, 10); // 1024 — libffi packs the doubles per the ABI, calls, reads the result

That libm.func('double pow(double, double)') line is the whole idea: a string that is the C signature. There is no compiler verifying it against libm’s real pow. The declaration is a contract you alone enforce — and that is the central tradeoff against a native addon, where the C compiler type-checks your glue. FFI buys you “no toolchain, wrap an existing library in minutes” by selling you “get one type wrong and there is no one to tell you.”

libffi: building a call frame at runtime

Under every FFI binding sits libffi. A normal compiled call has its argument layout baked in at compile time — the compiler knows to put the first integer in rdi, the first float in xmm0, and so on for the platform’s calling convention (System V AMD64 on Linux/macOS, the Microsoft x64 ABI on Windows). FFI does not have that luxury: it learns the signature only at runtime, from your declaration. So libffi constructs the call frame dynamically — it reads your declared types, places each argument in the right register or stack slot for the ABI, jumps through a trampoline into the library function, and reads the return value back out of the return register.

The cost is that dynamic step. Each FFI call pays a trampoline plus per-argument marshalling — on the order of tens of nanoseconds on top of the C function’s own work. For a handful of coarse calls per request that is invisible. For a hot loop making millions of tiny calls it dominates, and a compiled Node-API addon — whose calls are direct, with no runtime frame-building — wins decisively. FFI’s sweet spot is coarse-grained calls into an existing library, not a chatty inner loop.

koffi vs ffi-napi: pick the maintained one

There are two FFI lineages in Node, and the choice is not close in 2025.

The classic stack is ffi-napi + ref-napi — the descendants of node-ffi. Its fatal property is the one from the hook: it is itself a native addon. Installing it compiles C, so you inherit the entire node-gyp/prebuild/ABI matrix from the last lesson — the very build pain FFI was supposed to avoid — plus breakage every time a Node major shifts the ABI. It is now effectively unmaintained. Do not start new work on it.

koffi is the modern answer. It ships prebuilt binaries for common platforms (no node-gyp on install), is actively maintained, runs measurably faster, and has first-class support for structs, pointers, output parameters, callbacks, and disposable types. For new FFI work, koffi is the senior default; treat ffi-napi as legacy you migrate off.

Memory ownership: the boundary the GC will not cross

This is where FFI bites, and it is worth stating as a hard rule: JavaScript’s garbage collector cannot see native memory, and C cannot see the JS heap. They are two separate worlds with no shared bookkeeping. Three consequences you must manage by hand:

• C allocations are yours to free. If a function returns a malloc’d pointer (a char* string, a struct), the GC will never reclaim it — you must call the library’s matching free function yourself. Forget it and you have a classic C memory leak, in a Node process, that no heap snapshot will explain because it is off-heap.
• Buffers you pass must outlive the call. When you hand C a pointer into a JS Buffer or typed array, that memory is only safe for as long as the JS object is alive and unmoved. If C stores the pointer and uses it after the call returns (an async callback, a retained handle), you must keep a live JS reference so the GC neither collects nor relocates it — otherwise C dereferences freed memory.
• Output parameters need explicit allocation. Many C functions fill a caller-provided buffer (int read(fd, void* buf, size_t n)). You allocate it (koffi.alloc), pass the pointer, then decode what C wrote back.

// C: char* make_greeting(const char* name);  // returns a malloc'd string
//    void  free_greeting(char* p);            // caller must free it
const make = lib.func('char* make_greeting(const char*)');
const free = lib.func('void free_greeting(char*)');

const ptr = make('Ada');                 // C malloc'd this — GC has no idea
const text = koffi.decode(ptr, 'char*'); // copy the bytes into a JS string
free(ptr);                               // YOU free it, or it leaks forever

Structs, callbacks, and the cost of a wrong type

Three more places the contract must be exact:

Structs. You declare the layout (koffi.struct({ x: 'int', y: 'double' })), and the field order, types, and alignment/padding must match the C definition byte-for-byte. Get the padding wrong and every field after it reads from the wrong offset — garbage, not a crash, which is worse to debug.

Callbacks. To let C call back into JS (a comparator, an event handler) you register a JS function as a C function pointer. Two hazards: the JS function must stay alive while C holds the pointer (drop the reference and GC collects it under C’s feet), and if the library invokes your callback on a non-JS thread, calling into V8 from there crashes — you need koffi’s async/registered-callback handling, not a raw synchronous one.

Wrong scalar types. The hook’s bug generalizes: declaring 'int' where C returns a 64-bit size_t, long, or pointer truncates the value; declaring a signed type for an unsigned one flips large values negative. None of this is checked. The declaration is the only source of truth, and it is yours to get right.