rust-ffi

Modern Foreign Function Interface for Node.js v24+

Modernized and optimized FFI for Node.js v24+, based on node-ffi-napi with enhanced support for Rust and C interoperability.

rust-ffi is a high-performance Node.js addon for loading and calling dynamic libraries using pure JavaScript. It excels at creating bindings to native Rust and C libraries without writing any C++ code.

It also simplifies the augmentation of node.js with C code as it takes care of handling the translation of types across JavaScript and C, which can add reams of boilerplate code to your otherwise simple C. See the example/factorial for an example of this use case.

WARNING: rust-ffi assumes you know what you're doing. You can pretty easily create situations where you will segfault the interpreter and unless you've got C/Rust debugger skills, you probably won't know what's going on.

NOTE: This package maintains API compatibility with the original node-ffi while leveraging modern Node.js v24+ features and optimizations. Multi-threaded usage should be approached with caution.

Example

const ffi = require('rust-ffi');

// Example with standard math library
const libm = ffi.Library('libm', {
  'ceil': [ 'double', [ 'double' ] ]
});
libm.ceil(1.5); // 2

// Example with Rust library (compiled as cdylib)
const rustLib = ffi.Library('./target/release/libmyrust.so', {
  'add_numbers': [ 'int', [ 'int', 'int' ] ]
});

// Access functions in the current process
const current = ffi.Library(null, {
  'atoi': [ 'int', [ 'string' ] ]
});
current.atoi('1234'); // 1234

For a more detailed introduction, see the node-ffi tutorial page.

Requirements

• Node.js v24 or higher (required)
• Linux, macOS, Windows, or Solaris
• C++17 compatible compiler
• libffi comes bundled; it does not need to be installed separately
• For Windows: Visual Studio 2017 or newer

Installation

Make sure you've installed all the necessary build tools for your platform, then invoke:

$ npm install rust-ffi

Source Install / Manual Compilation

To compile from source it's easiest to use node-gyp:

$ npm install -g node-gyp

Now you can compile rust-ffi:

$ git clone https://github.com/yourusername/rust-ffi.git
$ cd rust-ffi
$ npm install
$ npm run build

Types

The types that you specify in function declarations correspond to ref's types system. So see its docs for a reference if you are unfamiliar.

V8 and 64-bit Types

Internally, V8 stores integers that will fit into a 32-bit space in a 32-bit integer, and those that fall outside of this get put into double-precision floating point numbers. This is problematic because FP numbers are imprecise. To get around this, the methods in node-ffi that deal with 64-bit integers return strings and can accept strings as parameters.

Call Overhead

There is non-trivial overhead associated with FFI calls. Comparing a hard-coded binding version of strtoul() to an FFI version of strtoul() shows that the native hard-coded binding is orders of magnitude faster. So don't just use the C version of a function just because it's faster. There's a significant cost in FFI calls, so make them worth it.

License

MIT License. See the LICENSE file.