4 releases (breaking)

0.5.0 Mar 12, 2022
0.4.0 Feb 21, 2022
0.2.0 Feb 8, 2022
0.1.0 Jan 31, 2022

#310 in FFI

MIT/Apache

505KB
13K SLoC

ts-bindgen   CI Latest Version Rust Documentation Crates.io

ts-bindgen: automatically generate rust wasm-bindgen bindings for typescript definitions to easily interact with javascript libraries from rust compiled to wasm.

Try it out in your browser

Head to ts-bindgen.ratchetdesigns.com to try ts-bindgen in your browser now by copy/pasting typescript definitions to see the rust bindings it generates.

Status

ts-bindgen is currently alpha software and it should be expected that any or all of the following might change significantly from version to version:

  1. Generated bindings
  2. Exposed interfaces
  3. Internal implementation

There are currently known issues that will prevent generation of reasonable bindings for some typescript idioms.

We welcome contributions and issues!

Quickstart

Head over to ts-bindgen.ratchetdesigns.com to generate rust bindings by copy/pasting typescript definitions in your browser.

To start generating bindings in your rust projects, you have a few options:

  1. Run cargo run ts-bindgen -- --output src/bindings.rs your-ts-module to generate src/bindings.rs from your-ts-module where your-ts-module is a ./path/to/defs.d.ts, /path/to/defs.d.ts, or module-in-node_modules.
  2. Invoke cargo run ts-bindgen -- --output src/bindings.rs --rerun-if-changed your-ts-module in your build.rs.
  3. Add ts-bindgen = { version = "0.5.0", default-features = false } to your cargo.toml dependencies and invoke ts_bindgen::generate_rust_string_for_typescript(ts_bindgen::StdFs, "your-module") in your build.rs. Note: while the ts-bindgen executable will rustfmt the generated bindings, generate_rust_string_for_typescript does not.

The generated bindings depend on the ts-bindgen runtime: ts-bindgen-rt, wasm-bindgen, serde, and (optionally) js-sys and web-sys so add the following to your Cargo.toml:

[dependencies]
ts-bindgen-rt = "0.5.0"
wasm-bindgen = "0.2.63"
serde = { version = "1.0", features = ["derive"] }
js-sys = "0.3.53" # optional, depending on your input typescript
web-sys = { version = "0.3.53", features = ["Window"] } # optional, update with features for any types your bindings use

Generated bindings

ts-bindgen seeks reasonable rust ergonomics and frequently wraps wasm-bindgen bindings to present a (hopefully) more "rust-y" interface. For example, functions and methods are wrapped to convert their arguments and return values to/from javascript/rust representations, javascript classes are wrapped in newtype structs, and traits are generated for javscript class inheritance hierarcies. To more faithfully preserve javascript semantics of null/undefined, functions, etc., we implement a custom (de)serializer similar to serde-wasm-bindgen to marshall between JsValues and generated bindings. We expect that there are many opportunities for performance improvement that have not yet been explored.

Structure

ts-bindgen consists of a few crates:

  • ts-bindgen - the public interface, consisting of the ts-bindgen executable and library
  • ts-bindgen-gen - the meat of parsing ts and generating rust bindings
  • ts-bindgen-rt - the runtime that generated bindings depend on
  • ts-bindgen-web (unpublished) - the code for ts-bindgen.ratchetdesigns.com
  • ts-bindgen-macro (unpublished) - likely a bad idea for a macro to generate bindings. Bindings have become too complex not to be inspected while coding against them and ts-bindgen-gen has not attempted to preserve macro hygeine.

License

Copyright 2022 Adam Berger, Ratchet Designs.

ts-bindgen is licensed under either of the MIT or Apache licenses, at your option.

Credit

ts-bindgen is crafted thoughtfully by Ratchet Designs

Dependencies

~16–30MB
~498K SLoC