#typescript #serialization-deserialization #generate-typescript #bincode #file

bin+lib bincode-typescript

Generates TypeScript serialisation and deserialisation code from Rust structs and enums

1 unstable release

0.1.0 Oct 23, 2020

#1947 in Encoding

MIT license

40KB
1K SLoC

Jinja2 566 SLoC Rust 448 SLoC

bincode-typescript

Generates TypeScript serialisation and deserialisation code from Rust structs and enums

Goals

  • Generate TypeScript code directly from Rust source
  • TypeScript must compile with strict mode enabled
  • Avoid Object Orientated TypeScript for better tree-shaking and optimisation
  • TypeScript should be ergonomic and high performance
    • Use const enum for Unit enums and respect discriminant values!
    • Use TypedArray and copy byte blocks for Vec<{integer,float}> for greater performance

Status

I'm pretty new to Rust and I've just hacked around until the tests pass 🤷‍♂️

There is much room for improvement and PRs are welcome!

Check the source for currently supported Rust types and their TypeScript equivalents.

You may also like to look at the Rust types used in the tests and the TypeScript generated from these.

Current Issues & Limitations

  • All values must be owned
  • Generic structs/enums will almost certainly cause a panic
  • All types must be in a single file
  • Serde attributes are not currently respected
  • Vec<T> are always converted to Uint8Array/Int8Array/etc whenever possible and this might not always be desired.
  • Generated code will not work on node < v11 due to the global usage of TextEncoder/TextDecoder

Example via build.rs

There is currently a single bool option to enable support for node.js Buffer, so if you are running in the browser you probably don't want this enabled.

bincode_typescript::from_file("./src/types.rs", "./ts/types.ts", false);

Example via CLI

There is currently a single option (--buffer-support) to enable support for node.js Buffer.

./bincode-typescript --support-buffer ./src/types.rs > ./ts/types.ts

Tests

Before running the tests, ensure that you have all the node.js dependencies installed by running yarn or npm i.

The tests check serialisation and deserialisation from generated TypeScript by round-tripping encoded data via stdio and asserting the expected values.

Prior Art

This builds on (ie. much TypeScript stolen from) the following projects.

The stated pros and cons are just personal opinion!

ts-rust-bridge

Pros:

  • Function based TypeScript API
  • Great ergonomics for enums with combination of type + interface + module

Cons:

  • Generates both Rust and TypeScript from a DSL. (I want Rust to be the source of truth).
  • Does not use const enum for Unit enums

serde-reflection/serde-generate

Pros:

  • Uses serde so no messing around parsing Rust

Cons:

  • All types have to be run through the registry after build so wont work from build.rs
  • TypeScript classes wrap every type and use inheritance (ie. no const enum)
  • Runtime TypeScript is separate

Dependencies

~3.5MB
~74K SLoC