dodo-bindgen-cli 1.0.2

A CLI tool for parsing rust source code and generating a close TypeScript equivalent. works with the `dodo_bindgen` crate
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

# deno-bindgen2

> [!WARNING]
> Work in Progress 🚧 \
> This documentation is currently incomplete

`deno-bindgen2` is an FFI bindings generator that simplifies writing Rust libraries for Deno.

It works by providing procedural macros that create wrappers around native Rust functions and make it FFI-safe. This makes writing FFI libraries easier as it deals with boilerplate code generation so you don't have to.

It also provides a CLI tool that generates a TypeScript module and tries to follow the semantics of your code wherever possible.

This project works along with the `deno-bindgen2-utils` library (to be) published on JSR, which contains utilities for interfacing with Rust's data structures in TypeScript.

This project aims to empower TypeScript development by bridging access to Rust's powerful memory-safe ecosystem.

## To use

This library depends on nightly rust features. It is recommended to set your project on the [nightly tool chain](https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file) to make sure the tool works as intended.

Add the `deno-bindgen2` crate to your library crate's dependencies (note the spelling and dash `-` separator)

```toml
# Cargo.toml
[dependencies]
deno-bindgen2 = "1.0"
```

Import *everything* from `deno_bindgen2` and use the `deno_bindgen` attribute macro on a function, implement, or struct item in your source code:

```rust
// lib.rs
use deno_bindgen2::*;

#[deno_bindgen]
fn test_1() {
    println!("Hello, world!");
}

#[deno_bindgen]
fn test_2(string: String) -> String {
    format!("{} to Rust!", str)
}
```

> [!NOTE]
>
> Currently, `deno-bindgen2` only supports a limited set of Rust types that can be idiomatically converted or passed between Rust/Deno contexts. Although eventual support for all possible types is planned.
>
> See the [limitations](docs/limitations.md) documentation for more info

Next, to generate the bindings and TypeScript code, you must install the CLI tool with the command below:

```sh
cargo install deno-bindgen2-cli
```

Then, run this command in your project's package folder (not the workspace folder).

```sh
deno-bindgen2 --release
```

This will automatically generate a TypeScript module in `<pkg_root>/dist/<your_module>`, along with another module `rust_type.ts` that contains TypeScript representations of Rust types.

Finally, you can write your TypeScript code and import the functions with the same name/identity from the Rust code.

```ts
// hello_world.ts
import { test_1, test_2 } from "./dist/libmy_mod.ts";
import { RustString } from "./dist/rust_type.ts";

test_1();

Deno.test("test_string", () => {
    // create a `RustString` instance from a JavaScript string
    // by calling the `from()` static method
    const hello_string = test_2(RustString.from("Hello from Deno"));

    // turn the RustString into a JavaScript string
    // by calling its `into()` method
    console.log(hello_string.into());
})

```

To run:

```bash
deno run --allow-all --unstable-ffi hello_world.ts
```

This should output:

```text
Hello, world!
Hello from Deno to Rust!
```

For additional code generation options, run `deno-bindgen2 --help`

## Examples

Check out the [test directory](packages/test) to see some examples

## Performance

This project improves proc macro performance by [as much as 15x](packages/bench/bench_data.md) over `deno_bindgen`, reducing processing time from ~0.30 ms to ~0.02 ms