Crate typescript_type_def[][src]

Expand description

Generate TypeScript type definitions for Rust types.

This crate allows you to produce a TypeScript module containing type definitions which describe the JSON serialization of Rust types. The intended use is to define TypeScript types for data that is serialized from Rust types as JSON using serde_json so it can be safely used from TypeScript without needing to maintain a parallel set of type definitions.

One example of where this crate is useful is when working on a web application project with a Rust backend and a TypeScript frontend. If the data used to communicate between the two is defined in Rust and uses serde_json to encode/decode it for transmission across the network, you can use this crate to automatically generate a TypeScript definition file for those types in order to use them safely in your frontend code. This process can even be completely automated if you use this crate in a build script for your server to write the definition file to your TypeScript source code directory.

Examples

Simple example:

use serde::Serialize;
use typescript_type_def::{
    write_definition_file,
    DefinitionFileOptions,
    TypeDef,
};

#[derive(Serialize, TypeDef)]
struct Foo {
    a: usize,
    b: String,
}

let ts_module = {
    let mut buf = Vec::new();
    let options = DefinitionFileOptions::default();
    write_definition_file::<_, Foo>(&mut buf, options).unwrap();
    String::from_utf8(buf).unwrap()
};
assert_eq!(
    ts_module,
    r#"// AUTO-GENERATED by typescript-type-def

export default types;
export namespace types{
export type Usize=number;
export type Foo={"a":types.Usize;"b":string;};
}
"#
);

let foo = Foo {
    a: 123,
    b: "hello".to_owned(),
};
let json = serde_json::to_string(&foo).unwrap();
// This JSON matches the TypeScript type definition above
assert_eq!(json, r#"{"a":123,"b":"hello"}"#);

When working with a large codebase consisting of many types, a useful pattern is to declare an “API” type alias which lists all the types you want to make definitions for. For example:

use serde::Serialize;
use typescript_type_def::{write_definition_file, TypeDef};

#[derive(Serialize, TypeDef)]
struct Foo {
    a: String,
}

#[derive(Serialize, TypeDef)]
struct Bar {
    a: String,
}

#[derive(Serialize, TypeDef)]
struct Baz {
    a: Qux,
}

#[derive(Serialize, TypeDef)]
struct Qux {
    a: String,
}

// This type lists all the top-level types we want to make definitions for.
// You don't need to list *every* type in your API here, only ones that
// wouldn't be referenced otherwise. Note that `Qux` is not mentioned, but
// is still emitted because it is a dependency of `Baz`.
type Api = (Foo, Bar, Baz);

let ts_module = {
    let mut buf = Vec::new();
    write_definition_file::<_, Api>(&mut buf, Default::default()).unwrap();
    String::from_utf8(buf).unwrap()
};
assert_eq!(
    ts_module,
    r#"// AUTO-GENERATED by typescript-type-def

export default types;
export namespace types{
export type Foo={"a":string;};
export type Bar={"a":string;};
export type Qux={"a":string;};
export type Baz={"a":types.Qux;};
}
"#
);

Modules

This module defines structs used to create static descriptions of TypeScript type definitions.

Structs

Options for customizing the output of write_definition_file.

Statistics about the type definitions produced by write_definition_file.

Traits

A Rust type that has a corresponding TypeScript type definition.

Functions

Writes a TypeScript definition file containing type definitions for T to the writer W.

Derive Macros

A derive proc-macro for the TypeDef trait.