agsol_borsh_schema/
lib.rs

1//! This library aims to facilitate the workflow between Rust and TypeScript data
2//! structures by auto-generating ! TypeScript classes and respective serialization
3//! layouts used for Borsh (de)serialization. Check out
4//! [`borsh-js`](https://github.com/near/borsh-js) and
5//! [`borsh-rs`](https://docs.rs/borsh/0.9.1/borsh/index.html) for more details.
6//!
7//! By default the library provides a derivable trait `BorshSchema` without any
8//! associated methods and constants. It's an empty trait that is essentially a
9//! flag for the schema parser that works the following way:
10//!
11//! 1) the parser traverses all `.rs` files in the provided input directory
12//!
13//! 2) data structures (`struct`s and `enum`s) annotated with
14//!    `#[derive(BorshSchema, ...)]` are parsed into an intermediate data
15//!    structure
16//!
17//! 3) the intermediate data structure is used to generate output files
18//!    containing TypeScript classes and serialization schemas
19//!
20//! The parser itself is only available through the `full` feature flag,
21//! because it uses parsing libraries incompatible with `wasm` or `bpf`
22//! targets.
23
24pub use agsol_borsh_schema_derive::*;
25
26/// Intermediate data structures used for generating
27/// schema an TypeScript class layouts.
28#[cfg(feature = "full")]
29mod layout;
30#[cfg(all(test, feature = "full"))]
31mod test;
32#[cfg(feature = "full")]
33mod utils;
34
35#[cfg(feature = "full")]
36pub use utils::*;
37
38/// An empty trait that serves as a flag for the schema parser.
39///
40/// It has an `alias` attribute that can be used to annotate `struct` and
41/// `enum` fields to explicitly indicate the type of that field. This is needed
42/// because the parser reads the file as a raw string, therefore it has no way
43/// of knowing the underlying type of a type alias.
44///
45/// # Example
46/// ```rust
47/// use agsol_borsh_schema::BorshSchema;
48/// use std::collections::BTreeMap;
49///
50/// type SomeAlias = [u8; 32];
51///
52/// #[derive(BorshSchema)]
53/// struct Foo {
54///     foo: Option<u64>,
55///     bar: BTreeMap<u8, Bar>,
56///     #[alias([u8; 32])]
57///     baz: SomeAlias,
58/// }
59///
60/// #[derive(BorshSchema)]
61/// enum Bar {
62///     A,
63///     B,
64///     C(u64),
65///     D {
66///         foo: i32,
67///         bar: String,
68///     },
69/// }
70/// ```
71///
72/// In the above example you may notice that `Foo`'s `bar` field doesn't need
73/// an alias because `Bar` implements `BorshSchema` itself, however, the parser
74/// doesn't know that `SomeAlias` is actually a byte array without the `alias`
75/// attribute. If the `alias` attribute is omitted, the generated TypeScript
76/// code will contain `SomeAlias` instead of `Uint8Array`.
77pub trait BorshSchema {}
agsol_borsh_schema/lib.rs

agsol_borsh_schema/
lib.rs
