borsh_serde_adapter/
lib.rs

1
2//! ## borsh-serde-adapter
3//!
4//! This library provides functions to deserialize data that was serialized with Borsh and returns a serde_json value when
5//! provided with the borsh schema binary file generated by the borsh-schema-writer library. It will take a serde_json value
6//! and serialize using borsh. Here is an example of deserialization:
7//!
8//! ```
9//! fn deserialize_from_borsh_schema_from_file() {
10//!     let person = Person {
11//!         first_name: "John".to_string(),
12//!         last_name: "Doe".to_string(),
13//!     };
14//!
15//!     let person_ser = to_vec(&person).expect("Error trying to serialize Person");
16//!
17//!     let file = File::open("./tests/schema/person_schema.dat").unwrap();
18//!     let mut reader = BufReader::new(file);
19//!     let container_from_file = BorshSchemaContainer::deserialize_reader(&mut reader).expect("Deserializing BorshSchemaContainer failed.");
20//!
21//!     let result = deserialize_from_schema(&mut person_ser.as_slice(), &container_from_file).expect("Deserializing from schema failed.");
22//!     println!("{}", result.to_string());
23//! }
24//! ```
25//!
26//! In this example you can see that we aren't deserializing with a struct with the BorshDeserialize trait. Typically you
27//! would do something like this:
28//!
29//! ```
30//!     let person_serialized = to_vec(&person).expect("Error trying to seralize Person");
31//!     let person_deserialized = Person::deserialize(&mut person_serialized.as_slice());
32//! ```
33//!
34//! But with the schema, we can go from borsh serialized, directly to serde_json and then we can easily get JSON as a
35//! string. This makes it much easier for other consumers to handle.
36//!
37//! We can do the do something similar with serializing from serde_json to borsh.
38//!
39//!
40//! ```
41//! fn serialize_from_borsh_schema() {
42//!     let person = Person {
43//!         first_name: "John".to_string(),
44//!         last_name: "Doe".to_string(),
45//!     };
46//!
47//!     let file = File::open("./tests/schema/person_schema.dat").unwrap();
48//!     let mut reader = BufReader::new(file);
49//!     let container = BorshSchemaContainer::deserialize_reader(&mut reader).expect("Deserializing BorshSchemaContainer failed.");
50//!
51//!     let person_value = serde_json::to_value(person).expect("Error serializing person");
52//!     let mut person_writer = Vec::new();
53//!     assert!(person_writer.len() == 0);
54//!
55//!     let _ = serialize_serde_json_to_borsh(&mut person_writer, &person_value, &container).expect("Serialization failed");
56//! }
57//! ```
58//!
59//! Here you can see instead of serializing from the Person struct with the BorshSerialize trait, we were able to go from
60//! serde_json directly to borsh serialization, with person_writer containing the serialized struct as a vec of bytes.
61//!
62//! **Borsh Schema to JSON**
63//!
64//! It's possible to get the schema as JSON. This is useful for consumers that don't have access to the schema binary file.
65//! This can be done using the write_schema_as_json function. Here is an example:
66//!
67//! ```
68//! fn schema_to_json_test() {
69//!     write_schema_as_json(Person::default(), "./tests/schema/person_schema.json".to_string());
70//!     let file = File::open("./tests/schema/person_schema.json").unwrap();
71//!     let reader = BufReader::new(file);
72//!     let result: Value = serde_json::from_reader(reader).expect("Deserialization failed");
73//!     println!("{}", result.to_string());
74//! }
75//! ```
76//!
77//! This will result in the following JSON:
78//!
79//! ```
80//! {
81//!   "declaration": "Person",
82//!   "definitions": [
83//!     [
84//!       "Person",
85//!       {
86//!         "Struct": {
87//!           "fields": {
88//!             "NamedFields": [
89//!               [
90//!                 [
91//!                   "first_name",
92//!                   "string"
93//!                 ],
94//!                 [
95//!                   "last_name",
96//!                   "string"
97//!                 ]
98//!               ]
99//!             ]
100//!           }
101//!         }
102//!       }
103//!     ]
104//!   ]
105//! }
106//! ```
107//!
108//! **Caveats**
109//!
110//! This library is still in early development and there are some caveats to be aware of. The use of u128 and i128 are
111//! somewhat supported. In the case of deserialization u128/i128 are deserialized as strings, but serialization is not
112//! supported.
113
114pub mod deserialize_adapter;
115pub mod serialize_adapter;
116pub mod errors;
117pub mod borsh_schema_util;
borsh_serde_adapter/lib.rs

borsh_serde_adapter/
lib.rs
