This tool aims to simplify glue code generation for Deno FFI libraries written in Rust.
Annotate on top of Rust fn
, struct
and enum
to make them available to
Deno.
// add.rs
use deno_bindgen::deno_bindgen;
#[deno_bindgen]
pub struct Input {
a: i32,
b: i32,
}
#[deno_bindgen]
fn add(input: Input) -> i32 {
input.a + input.b
}
Invoke the CLI to compile and generate bindings:
$ deno_bindgen
And finally import the generated bindings in your JS
// add.ts
import { add } from "./bindings/bindings.ts";
add({ a: 1, b: 2 }); // 3
- Install the
deno_bindgen
CLI with Deno.
deno install -Afrq -n deno_bindgen https://deno.land/x/deno_bindgen/cli.ts
Add the following dependencies to your crate.
# Cargo.toml
[dependencies]
deno_bindgen = "0.7.0"
serde = { version = "1", features = ["derive"] }
Change your crate-type
to cdylib
and set your package name as well.
[lib]
name = "___"
crate-type = ["cdylib"]
Put #[deno_bindgen]
on top of a "serde-deriavable" struct, enum or fn.
These transform into Typescript type
s.
// lib.rs
#[deno_bindgen]
pub struct A {
b: Vec<Vec<String>>,
}
becomes:
// bindings/bindings.ts
export type A = {
b: Array<Array<string>>;
};
Enums become type
unions in Typescript.
#[deno_bindgen]
pub enum Event {
Quit,
MouseMove {
x: i32,
y: i32,
}
}
becomes:
export type Enum =
| "quit"
| {
mouse_move: {
x: number;
y: number;
};
};
Functions are exposed through the FFI boundaries.
#[deno_bindgen]
fn greet(name: &str) {
println!("Hello, {}!", name);
}
becomes:
export function greet(name: string) {
// ... glue code for calling the
// symbol.
}
Notes
-
Use
#[deno_bindgen(non_blocking)]
attribute to call symbol without blocking JS event loop. Exposed as an async funtion from bindings. -
Rust doc comments transform to JS docs.
#[deno_bindgen] pub struct Me { /// My name... /// ...it is name: String, }
becomes:
export type Me = { /** * My name... * ...it is */ name: string; };
-
If the argument type of Rust is f32, the calculation result may be different.
Number in Java Script is float64, when data is passed to Rust, it becomes float32, so the number may change.
e.g:1.3 + 1.5
will be2.799999952316284
The deno_bindgen
CLI tool provides the following flags:
-
Pass
--release
to create a release build. -
--release=URL
will load library artifacts from a remote location. This is useful for updating bindings for end users after a release:deno_bindgen --release=https://github.com/littledivy/deno_sdl2/releases/download/0.2-alpha.1
Under the hood this uses
x/plug
to fetch and cache the artifact.Artifacts must be following the remote asset naming scheme, as follows:
OS Arch Naming Windows x86_64 name.dll Linux x86_64 libname.so MacOS x86_64 libname.dylib MacOS arm64 libname_arm64.dylib -
Flags after
--
will be passed tocargo build
. Example:deno_bindgen -- --features "cool_stuff"