Crate ts_bindgen

Expand description

ts-bindgen provides a library as an easy entrypoint into generating rust wasm-bindgen bindings for a typescript module and provides an executable for doing the same via the command line.

If you are using the library, we recommend adding default-features = false to your Cargo.toml to avoid pulling in unnecessary crates.

Because rustfmt compilation requires the nightly toolchain at this point, the library functions do not support formatting the returned rust code but the ts-bindgen executable will run rustfmt on the generated code by default. You can see ts-bindgen-web for an example of running rustfmt as a library on the output (in wasm).

ts-bindgen

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:

Generated bindings
Exposed interfaces
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:

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.
Invoke cargo run ts-bindgen -- --output src/bindings.rs --rerun-if-changed your-ts-module in your build.rs.
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

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

Credit

ts-bindgen is crafted thoughtfully by Ratchet Designs

Structs

Error

Public Error type for ts-bindgen-gen.

MemFs

In-memory filesystem

StdFs

Regular filesystem

Traits

Fs

Filesystem abstraction

Functions

generate_rust_string_for_typescript

Given a filesystem and a reference to a typescript definition module (e.g. “moment” to refer to a moment module in node_modules, “./my-module” to refer to my-module.d.ts or my-module/index.d.ts or my-module’s package.json typings reference, etc.), return a String of rust code for wasm-bindgen bindings to the module.

generate_rust_string_for_typescript_string

Given typescript definitions as a string, return a String of rust code for wasm-bindgen bindings to the typescript definitions. The rust will be generated in a module named according to rust_namespace.