Struct near_syn::ts::TS

pub struct TS<T> {
    pub name: String,
    pub interfaces: Vec<String>,
    pub view_methods: Vec<String>,
    pub change_methods: Vec<String>,
    pub buf: T,
}

Represents a pass to several Rust files to generate TypeScript bindings.

Fields

name: String

Represents the name of the contract to export.

interfaces: Vec<String>

interfaces

view_methods: Vec<String>

view

change_methods: Vec<String>

change

buf: T

Output buffer where to store the generated TypeScript bindings.

Implementations

impl<T: Write> TS<T>

pub fn new(buf: T) -> Self

Creates a new TS instance.

let mut ts = near_syn::ts::TS::new(Vec::new());
assert_eq!(String::from_utf8_lossy(&ts.buf), "");

pub fn ts_prelude(&mut self, now: String, bin_name: &str)

Exports common Near types.

let mut ts = near_syn::ts::TS::new(Vec::new());
ts.ts_prelude(" 2021".to_string(), "bin");
assert_eq!(String::from_utf8_lossy(&ts.buf), format!(
r#"// TypeScript bindings generated with bin v{} {} 2021

// Exports common NEAR Rust SDK types
export type U64 = string;
export type I64 = string;
export type U128 = string;
export type I128 = string;
export type AccountId = string;
export type ValidAccountId = string;

"#,
  env!("CARGO_PKG_VERSION"),
  env!("CARGO_PKG_REPOSITORY"),
  ));

pub fn ts_extend_traits(&mut self)

Emits additional extensions for the main type implemented by the contract. This is used when the contract implements one or more traits. The name and interfaces fields must be set in order to emit these additional extensions.

Examples

let mut ts = near_syn::ts::TS::new(Vec::new());
ts.name = "Contract".to_string();
ts.interfaces.push("NftCore".to_string());
ts.interfaces.push("NftEnum".to_string());
ts.ts_extend_traits();
assert_eq!(String::from_utf8_lossy(&ts.buf), "export interface Contract extends NftCore, NftEnum {}\n\n");

pub fn ts_contract_methods(&mut self)

Exports the methods object required by near-api-js to be able to find contract methods.

let mut ts = near_syn::ts::TS::new(Vec::new());
ts.name = "Contract".to_string();
ts.view_methods.push("get".to_string());
ts.change_methods.push("set".to_string());
ts.change_methods.push("insert".to_string());
ts.ts_contract_methods();
assert_eq!(String::from_utf8_lossy(&ts.buf),
r#"export const ContractMethods = {
    viewMethods: [
        "get",
    ],
    changeMethods: [
        "set",
        "insert",
    ],
};
"#);

Both viewMethods and changeMethods fields must be present in the resulting object. This is required by near-api-js. For example,

let mut ts = near_syn::ts::TS::new(Vec::new());
ts.name = "Contract".to_string();
ts.view_methods.push("get".to_string());
ts.ts_contract_methods();
assert_eq!(String::from_utf8_lossy(&ts.buf),
r#"export const ContractMethods = {
    viewMethods: [
        "get",
    ],
    changeMethods: [
    ],
};
"#);

pub fn ts_items(&mut self, items: &Vec<Item>)

Translates a collection of Rust items to TypeScript. It currently translates type, struct, enum and impl items to TypeScript. It traverses recursively mod definitions with braced content. The inner mod’ items are flatten into a single TypeScript module. If an item in items is not one of the mentioned above, it is ignored.

Notice how mod definitions are flattened:

let mut ts = near_syn::ts::TS::new(Vec::new());
let ast: syn::File = syn::parse2(quote::quote! {
        /// Doc-comments are translated.
        type T = u64;
        mod inner_mod {
            /// Doc-comments are translated.
            type S = u64;
        }
    }).unwrap();
ts.ts_items(&ast.items);
assert_eq!(String::from_utf8_lossy(&ts.buf),
r#"/**
 *  Doc-comments are translated.
 */
export type T = number;

/**
 *  Doc-comments are translated.
 */
export type S = number;

"#);

let mut ts = near_syn::ts::TS::new(Vec::new());
let ast: syn::File = syn::parse2(quote::quote! {
        #[near_bindgen]
        impl Contract {
            pub fn get(&self) -> u32 { 42 }
        }

        #[near_bindgen]
        impl NftCore for Contract {
            fn f(&self) -> u32 { 42 }
        }

        #[near_bindgen]
        impl NftEnum for Contract {
            fn g(&self) -> u32 { 42 }
        }

    }).unwrap();
ts.ts_items(&ast.items);
ts.ts_extend_traits();
assert_eq!(String::from_utf8_lossy(&ts.buf),
r#"/**
 */
export interface Contract {
    /**
     */
    get(): Promise<number>;

}

/**
 */
export interface NftCore {
    /**
     */
    f(): Promise<number>;

}

/**
 */
export interface NftEnum {
    /**
     */
    g(): Promise<number>;

}

export interface Contract extends NftCore, NftEnum {}

"#);

pub fn ts_type(&mut self, item_type: &ItemType)

Translates a type alias to another type alias in TypeScript.

let mut ts = near_syn::ts::TS::new(Vec::new());
ts.ts_type(&syn::parse2(quote::quote! {
        /// Doc-comments are translated.
        type T = u64;
    }).unwrap());
assert_eq!(String::from_utf8_lossy(&ts.buf),
r#"/**
 *  Doc-comments are translated.
 */
export type T = number;

"#);

If doc-comments are omitted, TypeScript empty doc-comments will be emitted.

let mut ts = near_syn::ts::TS::new(Vec::new());
ts.ts_type(&syn::parse2(quote::quote! {
        type T = u64;
    }).unwrap());
assert_eq!(String::from_utf8_lossy(&ts.buf),
r#"/**
 */
export type T = number;

"#);

pub fn ts_struct(&mut self, item_struct: &ItemStruct)

Generates the corresponding TypeScript bindings for the given struct. Doc-comments embedded in the Rust source file are included in the bindings. The struct must derive Serialize from serde in order to generate its corresponding TypeScript bindings.

let mut ts = near_syn::ts::TS::new(Vec::new());
ts.ts_struct(&syn::parse2(quote::quote! {
        /// Doc-comments are also translated.
        #[derive(Serialize)]
        struct A {
            /// Doc-comments here are translated as well.
            field: u32,
        }
    }).unwrap());
assert_eq!(String::from_utf8_lossy(&ts.buf),
r#"/**
 *  Doc-comments are also translated.
 */
export type A = {
    /**
     *  Doc-comments here are translated as well.
     */
    field: number;

}

"#);

Single-compoenent tuple-structs are converted to TypeScript type synonym.

let mut ts = near_syn::ts::TS::new(Vec::new());
ts.ts_struct(&syn::parse2(quote::quote! {
        /// Tuple struct with one component.
        #[derive(Serialize)]
        struct T(String);
    }).unwrap());
assert_eq!(String::from_utf8_lossy(&ts.buf),
r#"/**
 *  Tuple struct with one component.
 */
export type T = string;

"#);

On the other hand, tuple-structs with more than one component, are converted to TypeScript proper tuples.

let mut ts = near_syn::ts::TS::new(Vec::new());
ts.ts_struct(&syn::parse2(quote::quote! {
        /// Tuple struct with one component.
        #[derive(Serialize)]
        struct T(String, u32);
    }).unwrap());
assert_eq!(String::from_utf8_lossy(&ts.buf),
r#"/**
 *  Tuple struct with one component.
 */
export type T = [string, number];

"#);

If derive Serialize is not found, given struct is omitted.

let mut ts = near_syn::ts::TS::new(Vec::new());
ts.ts_struct(&syn::parse2(quote::quote! {
        struct A { }
    }).unwrap());
assert_eq!(String::from_utf8_lossy(&ts.buf), "");

pub fn ts_enum(&mut self, item_enum: &ItemEnum)

Translates an enum to a TypeScript enum or type according to the Rust definition. The Rust enum must derive Serialize from serde in order to be translated.

For instance, a plain Rust enum will be translated to an enum.

let mut ts = near_syn::ts::TS::new(Vec::new());
ts.ts_enum(&syn::parse2(quote::quote! {
        /// Doc-comments are translated.
        #[derive(Serialize)]
        enum E {
            /// Doc-comments here are translated as well.
            V1,
        }
    }).unwrap());
assert_eq!(String::from_utf8_lossy(&ts.buf),
r#"/**
 *  Doc-comments are translated.
 */
export enum E {
    /**
     *  Doc-comments here are translated as well.
     */
    V1,

}

"#);

pub fn ts_impl(&mut self, item_impl: &ItemImpl)

Translates an impl section to a TypeScript interface.

A struct can have multiple impl sections with no trait to declare additional methods. These impls are emitted with the name of the contract, as TypeScript merges these definitions.

let mut ts = near_syn::ts::TS::new(Vec::new());
ts.ts_impl(&syn::parse2(quote::quote! {
        /// Doc-comments are translated.
        #[near_bindgen]
        impl Contract {
            /// Doc-comments here are translated as well.
            pub fn get(&self) -> u32 { 42 }
        }
    }).unwrap());
assert_eq!(String::from_utf8_lossy(&ts.buf),
r#"/**
 *  Doc-comments are translated.
 */
export interface Contract {
    /**
     *  Doc-comments here are translated as well.
     */
    get(): Promise<number>;

}

"#);