Exports serde-serializable structs and enums to Typescript definitions.
Now that rust 2018 has landed there is no question that people should be using rust to write server applications (what are you thinking!). But currently generating wasm from rust code to run in the browser is too bleeding edge. Since javascript will be dominant on the client for the forseeable future there remains the problem of communicating with your javascript from your rust server.
Fundamental to this is to keep the datatypes on either side of the connection (http/websocket) in sync.
Typescript is an incremental typing system for javascript that is as tricked as rust (almost!) so why not create a typescript definition library based on your rust code?
Please see Credits.
example:
```rust extern crate serdederive; extern crate typescriptdefinitions; extern crate wasm_bindgen;
use::wasmbindgen::prelude::*; use::serdederive::Serialize; use::typescript_definitions::TypescriptDefinition;
enum Enum { #[allow(unused)] V1 { #[serde(rename = "Foo")] foo: bool, }, #[allow(unused)] V2 { #[serde(rename = "Bar")] bar: i64, #[serde(rename = "Baz")] baz: u64, }, #[allow(unused)] V3 { #[serde(rename = "Quux")] quux: String, }, } ```
With wasm-bindgen this will output in your .d.ts definition file:
typescript
export type Enum =
{tag: "V1", fields: { Foo: boolean } }
| {tag: "V2", fields: { Bar: number, Baz: number } }
| {tag: "V3", fields: { Quux: string } }
;
typescript-definitionsNB: Please note these macros by default work only for the debug build since they pollute the code with strings and methods all of which are proabably not useful in any release (Since you are only using them to extract information about your current types from your code). In release builds they become no-ops. See features below if you want them in your release build.
In your crate create a lib target in Cargo.toml pointing
to your "interfaces"
```toml [lib] name = "mywasm" # whatever... you decide path = "src/interface.rs" crate-type = ["cdylib"]
[dependencies] typescript-definitions = "0.1.3" wasm-bindgen = "0.2" serde = "1" serde_derive = "1"
```
Then you can run
bash
cargo +nightly build --target wasm32-unknown-unknown
mkdir pkg
wasm-bindgen target/wasm32-unknown-unknown/debug/mywasm.wasm --typescript --out-dir pkg/
cat pkg/mywasm.d.ts
If you don't have these tools then see here:
bash
rustup target add wasm32-unknown-unknown --toolchain nightly
cargo +nightly install wasm-bindgen-cli
or use wasm-pack (the typescript library will be in pkg/mywasm.d.ts)
bash
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
wasm-pack build
cat pkg/mywasm.d.ts
type_script_ifyYou can ignore WASM totally and derive using TypeScriptify as long as you have the following TypeScriptifyTrait Trait
in scope:
```rust // interface.rs extern crate serdederive; extern crate typescriptdefinitions; // wasmbindgen not needed // use::wasmbindgen::prelude::; use::serde_derive::Serialize; use::typescript_definitions::TypeScriptify; // *you have to provide this Trait because, currently, rust proc-macro crates can't // export any public Traits etc... sorry about that. pub trait TypeScriptifyTrait { fn typescriptify() -> &'static str; }
pub struct MyStruct {
v : i32,
}
``
Then inmain.rs(say) you can generate your own typescript specification usingStruct::typescriptify()`:
```rust mod interface; // need to pull in trait use self::interface::TypeScriptifyTrait;
fn main() {
println!("{}", interface::MyStruct::typescriptify());
// prints "export type MyStruct = { v: number };"
}
``
Use the cfg macro To protect any use oftypescriptify()`
if cfg!(any(debug_assertions, feature="export-typescript") {
let s = A::type_script_ify();
}
If you have a generic struct such as:
```rust
pub struct Value
Then you need to choose a concrete type: Value<i32>::type_script_ify(). The concrete type
doesn't matter as long as it obeys rust; the output will still be generic export type Value<T> { value: T }.
Currently type bounds are discarded.
There is an export-typescript feature
to opt-in for release.
```toml [dependencies.typescript-definitions] version = "0.1.3" features = ["export-typescript"]
typescript-definitions = { version="0.1.3", features=["export-typescript"] } ```
See Serde Docs.
This crate understands #[serde(tag="type")] and #[serde(tag="tag", content="fields")]
attributes but only for Struct variants.
It doesn't do Untagged or Externally tagged enums but defaults
to #[serde(tag="kind")] (Internal).
The default for NewTypes and Tuple types is
#[serde(tag="kind", content="fields")] (Adjacent).
Currently typescript-descriptions will not fail (AFAIK) even for
structs and enums with function types Fn(A,B) -> C (generates C). These make no sense in the current
context (data types, json serialization) so this might be considered a bug.
Watchout!
This might change if use cases show that an error would be better.
The Option type is rendered as:
Option<T> => T | nullSerde always seems to render Result (in json) as {"Ok": T } | {"Err": E} i.e as "External"
so we do too.
If you reference another type in a struct e.g.
```rust
#[derive(Serialize)]
struct B
#[derive(Serialize, TypescriptDefinition)]
struct A {
x : f64, /* simple */
b: B<f64>,
}
``
then this will "work" (producingexport type A = { x: number ,b: B) but B will be opaque to
javascript unless B is *also*#[derive(TypescriptDefinition)]`.
Currently there is no help for this.
Formatting is rubbish and won't pass tslint. This is due to the quote! crate taking control of the output token stream. I don't know what it does with whitespace for example... (is whitespace a token in rust?). Anyhow this crate apply a few bandaid regex patches to pretty things up.
We are not as clever as serde in determining the actual type. For example this won't "work":
```rust use std::borrow::Cow as Pig;
struct S<'a> { pig: Pig<'a, str>, ```
gives export type S = { pig : Pig<string> } instead of export type S = { pig : string }
We can't reasonably obey serde attributes like "flatten" since we would need to find the actual Struct object (from somewhere) and query its fields.
Generate a typescript verifier for each type (maybe).
typescript
export verify_A<T>(obj: any) -> boolean
or something...
Then one could:
typescript
let o : any = JSON.parse(some_string_from_the_inet);
if verify_A<number>(o) {
return obj as A<number>
} else {
// err....
}
see http://timryan.org/2019/01/22/exporting-serde-types-to-typescript.html
Forked from wasm-typescript-definition by @tcr
which was forked from rust-serde-schema by @srijs.
type_script_ify idea from typescriptify by @n3phtys
Probably some others...
MIT or Apache-2.0, at your option.