tsync-macro

Crates.iotsync-macro
lib.rstsync-macro
version0.1.0
sourcesrc
created_at2022-11-06 22:45:11.593622
updated_at2022-11-06 22:45:11.593622
descriptionMacros for tsync (see https://github.com/Wulf/tsync)
homepage
repository
max_upload_size
id706788
size4,587
Haris (Wulf)

documentation

README

tsync

License: MIT OR Apache-2.0

A utility to generate typescript types from rust code.

Install

There are two parts to this:

  1. The CLI tool:

    cargo install tsync
    
  2. The dependency for rust projects (to use the #[tsync] attribute; see usage below)

    /// Cargo.toml
    
    tsync = "X.Y.Z"
    

Usage

Mark structs with #[tsync] as below:

/// src/main.rs
use tsync::tsync;

/// Doc comments are preserved too!
#[tsync]
struct Book {
  name: String,
  chapters: Vec<Chapter>,
  user_reviews: Option<Vec<String>>
}

#[tsync]
struct Chapter {
  title: String,
  pages: u32
}


#[tsync]
/// Time in UTC seconds
type UTC = usize;

Then use the CLI tool:

tsync -i ./src -o types.d.ts

And voilĂ !

/// types.d.ts

/* This file is generated and managed by tsync */

// Doc comments are preserved too!
interface Book {
  name: string
  chapters: Array<Chapter>
  user_reviews: Array<string> | undefined
}

interface Chapter {
  title: string
  pages: number
}

// Time in UTC seconds
type UTC = number

Multiple Inputs

You can specify many inputs (directories and/or files) using the -i flag multiple times, like so:

tsync -i directory1 -i directory2 -o types.d.ts

Multiple Outputs

It might help to create multiple typing files for your project. It's easy, just call tsync multiple times:

tsync -i src/models -o models.d.ts
tsync -i src/api -o api.d.ts

Usage as a library

In the case that installing tsync globally isn't an option (or causes other concerns), you can use it as a library.

  1. Add the library to your project:

    cargo add tsync@1
    
  2. Create a new binary in your project which uses the crate (for example, bin/tsync.rs):

    // bin/tsync.rs
    
    use std::path::PathBuf;
    
    pub fn main() {
    let dir = env!("CARGO_MANIFEST_DIR");
    
        let inputs = vec![PathBuf::from_iter([dir, "backend"])];
        let output = PathBuf::from_iter([dir, "frontend/src/types/rust.d.ts"]);
    
        tsync::generate_typescript_defs(inputs, output, false);
    }
    
  3. Create a Cargo.toml binary entry:

    [[bin]]
    name = "tsync"
    path = "bin/tsync.rs"
    
  4. Execute!

    cargo run --bin tsync
    

Protip: to use cargo tsync, create an alias in .cargo/config:

[alias]
tsync="run --bin tsync"

Errors

A list of files which can't be opened or parsed successfully are listed after executing tsync. For other errors, try using the --debug flag to pinpoint issues. Please use the Github issue tracker to report any issues.

Docs

See tsync --help for more information.

Feel free to open tickets for support or feature requests.

Development/Testing

Use ./test/test_all.sh to run tests. After running the test, there should be no unexpected changes to files in ./test (use git status and git diff to see if there were any changes).

License

This tool is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE, LICENSE-MIT, and COPYRIGHT for details.

Commit count: 0

cargo fmt