#deno #ffi #bindgen #bindings #macro

deno_bindgen

This tool aims to simplify glue code generation for Deno FFI libraries written in Rust

12 releases (6 breaking)

0.7.0 Sep 13, 2022
0.6.0 Jul 24, 2022
0.5.1 Mar 25, 2022
0.4.1 Dec 28, 2021
0.3.1 Nov 15, 2021

#31 in FFI

Download history 66/week @ 2022-10-11 93/week @ 2022-10-18 68/week @ 2022-10-25 90/week @ 2022-11-01 106/week @ 2022-11-08 90/week @ 2022-11-15 104/week @ 2022-11-22 64/week @ 2022-11-29 107/week @ 2022-12-06 151/week @ 2022-12-13 143/week @ 2022-12-20 194/week @ 2022-12-27 204/week @ 2023-01-03 213/week @ 2023-01-10 312/week @ 2023-01-17 232/week @ 2023-01-24

999 downloads per month
Used in 3 crates

MIT license

6KB
76 lines

deno_bindgen

This tool aims to simplify glue code generation for Deno FFI libraries written in Rust.

QuickStart

Annotate on top of Rust fn, struct and enum to make them avaiable 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

Installation

  • Install the deno_bindgen CLI with Deno.
deno install -Afq -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"]

Bindings

Put #[deno_bindgen] on top of a "serde-deriavable" struct, enum or fn.

struct (named fields)

These transform into Typescript types.

// lib.rs
#[deno_bindgen]
pub struct A {
  b: Vec<Vec<String>>,
}

becomes:

// bindings/bindings.ts
export type A = {
  b: Array<Array<string>>;
};

enum

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;
    };
  };

fn

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;
    };
    

CLI

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 to cargo build. Example:

    deno_bindgen -- --features "cool_stuff"
    

Dependencies

~0.8–1.4MB
~32K SLoC