This project uses v5 of Node N-API. Please see following compatibility matrix.
Following OS are supported: * Linux * MacOs * Windows
Writing native node-js requires lots of boiler plate code. Node-bindgen generates external "C" glue code from rust code including native module registration. This make it writing node-js module easy and fun.
Node-bi
Install nj-cli command line which will be used to generate native library.
cargo install nj-cli
This is one time step.
Add two dependencies to your projects' Cargo.toml.
Add node-bindgen as as regular dependencies as below:
[dependencies]
node-bindgen = { version = "2.0.0-beta.1" }
Then add node-bindgen's procedure macro to your build-dependencies as below:
[build-dependencies]
node-bindgen = { path = "../../", features = ["build"] }
Then update crate type to cdylib to generate node.js compatible native module:
[lib]
crate-type = ["cdylib"]
A simple functional example which add two integers. Noticed that you don't need to worry about JS conversion.
```rust
use nodebindgen::derive::nodebindgen;
/// add two integer
fn sum(first: i32, second: i32) -> i32 {
first + second
}
```
To build node.js library, using nj-cli to build:
nj-cli build
This will generate Node.js module in "./dist" folder.
Then in the Node.js, rust function can invoked as normal node.js function:
```js $ node Welcome to Node.js v14.0.0. Type ".help" for more information.
let addon = require('./dist'); undefined addon.sum(2,3) 5
```
```rust
fn mul(first: i32,second: i32) -> i32 {
first * second
}
```
Rust function mul is re-mapped as multiply
Argument can be skipped if it is marked as optional ```rust
fn sum(first: i32, second: Option
first + second.unwrap_or(0)
}
Then sum can be invoked as
sum(10)orsum(10,20)```
JS callback are mapped as Rust closure
```rust
fn hello }
``` from node: ```js
let addon = require('./dist'); addon.hello(2,function(msg){
assert.equal(msg,"argument is: 2");
console.log(msg); // print out argument is 2
});
``` Callback are supported in Async rust as well. Async rust function is mapped to Node.js promise. ```rust use std::time::Duration;
use flvfutureaio::time::sleep;
use nodebindgen::derive::nodebindgen; async fn hello(arg: f64) -> f64 {
println!("sleeping");
sleep(Duration::from_secs(1)).await;
println!("woke and adding 10.0");
arg + 10.0
}
``` ```js
let addon = require('./dist'); addon.hello(5).then((val) => {
console.log("future value is %s",val);
}); ``` JavaScript class is supported. ```rust struct MyClass {
val: f64,
} impl MyClass { }
``` ```js
let addon = require('./dist');
const assert = require('assert'); let obj = new addon.MyObject(10);
assert.equal(obj.value,10,"verify value works");
assert.equal(obj.plusOne(),11);
``` There are more features in the examples folderlet msg = format!("argument is: {}", first);
second(msg);
Support for Async Rust
[node_bindgen]
JavaScript class
[node_bindgen]
#[node_bindgen(constructor)]
fn new(val: f64) -> Self {
Self { val }
}
#[node_bindgen]
fn plus_one(&self) -> f64 {
self.val + 1.0
}
#[node_bindgen(getter)]
fn value(&self) -> f64 {
self.val
}