Postcard Bindgen

Postcard Bindgen generates code for other languages to serialize and deserialize postcard byte format. This facilitates communication between, for example, a microcontroller and a mobile app using the postcard crate.

Structs and enums can be annotated with PostcardBindings to generate code. The generated code can be exported as an npm package for JavaScript or a pip package for Python.

Supported Languages

• 🌐 JavaScript (>= ES2021)
• 🐍 Python (>= 3.9)

Usage

Rust 1.88 or later is required. Nightly Rust is no longer needed to generate bindings.

Annotate structs and enums with Serialize/Deserialize from the serde crate and the PostcardBindings macro from this crate.

The process has two steps:

1. Annotate structs and enums in a library crate.
2. Import the annotated structs and enums in a binary crate, add the generation logic, and run the binary crate to generate the npm package.

Enable the generating feature if postcard-bindgen is added as a dependency in the generation binary crate.

Example

This example shows how to generate an npm package. The struct Test and the generation logic are in the same Rust file.

#[derive(Serialize, PostcardBindings)]
struct Test {
    name: u8,
    other: u16,
}

fn main() {
    javascript::build_package(
        std::env::current_dir().unwrap().as_path(),
        PackageInfo {
            name: "generation-test".into(),
            version: "0.1.0".try_into().unwrap(),
        },
        javascript::GenerationSettings::enable_all(),
        generate_bindings!(Test),
    )
    .unwrap();
}

The following code can now be used to serialize an object in JavaScript.

import { serialize } from "generation-test";

const test = {
    name: "test",
    other: 23
}

const bytes = serialize("Test", test)

Test Bindings Fixture

From the workspace directory, generate the JavaScript bindings and serialized fixture used by the TypeScript test project:

cargo +1.88 run -p postcard-bindgen --example generate_bindings --features="std generating heapless"

The example writes the js-test-bindings Node package to postcard-bindgen/js-test-bindings and the serialized Rust structs to postcard-bindgen/serialized.bytes, respectively. The TypeScript project at postcard-bindgen/test-bindings-proj uses js-test-bindings as a local dependency, loads serialized.bytes, and deserializes it with the generated bindings. It compares that result with the value produced by serializing and deserializing the same structure in JavaScript.

Then run the TypeScript project:

cd postcard-bindgen/test-bindings-proj
npm install
npm run run

Type mappings

Type Name	Rust	Js	Python
Unit Type	struct UnitStruct;	{}	class UnitStruct: pass t = UnitStruct()
Tuple Struct	struct TupleStruct(u8, u16, u32);	[123, 1234, 12345]	class TupleStruct(tuple[u8]): ... t = TupleStruct(123, 1234, 12345)
Struct	struct Struct { a: u8, b: u16 };	{ a: 123, b: 1234 }	@dataclass class Struct a: u8 b: u16 t = Struct(a = 123, b = 1234)
Enum	enum Enum { A, B(u8), C { a: u8 } };	{ tag: "A", }, { tag: "B", value: 123 }, { tag: "C", value: { a: 123 } }	class Enum: pass class Enum_A(Enum): pass class Enum_B(Enum, tuple[u8]): ... @dataclass class Enum_C(Enum) a: u8 a = Enum_A() b = Enum_B(23) c = Enum_C(a = 23)
Option	struct OptionTuple(Option<u8>); struct OptionStruct { a: Option<u8> }	// OptionTuple(Some(123)) [123] // OptionTuple(None) [undefined] // OptionStruct { a: Some(123) } { a: 123 } // OptionStruct { a: None } {} // or { a: undefined }	# OptionTuple(Some(123)) OptionTuple(123) # OptionTuple(None) OptionTuple(None) # OptionStruct { a: Some(123) } OptionStruct(a = 123) # OptionStruct { a: None } OptionStruct(a = None)
Map	let map_string_key = HashMap::<String, u8>::new(); let map_any_key = HashMap::<u16, u8>::new();	// map_string_key { key: value } // map_any_key new Map()	# map_string_key : Dict[str, u8] = { key: value } # map_any_key : Dict[u16, u8] = { key: value }

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Postcard Bindgen by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions