Approach to type definition generation for web users

[ianthetechie]

Background

Since GSoC 2024, Ferrostar has included support for the web, via WASM cross-compilation and JavaScript bindings. The bindings are what allow easy interoperability between web developers and the core, which is compiled to WASM. Web devs speak JS, sending objects back and forth, and the bindings ensure that happens smoothly.

The generated bindings are vanilla JS for maximum compatibility. However, even among Vanilla JS users, editors are usually capable of consuming information from .d.ts files, and nearly all popular JS packages publish definitions either together or in a separate npm package.

This document discusses approaches considered to publishing type definitions for the web, what we settled on, and why so that we can effectively re-evaluate as the landscape morphs.

Approaches evaluated

We looked at three crates in total:

• ts-rs
• tsify
• typescript-definitions (immediately discarded as it is no longer developed actively; no further discussion but noted for the sake of history)

ts-rs

@CatMe0w, who did the initial implementation work, did a proof of concept with ts-rs in #181. At the time, there were some limitations with how it generated the types, as it initially spread definitions across multiple files. This PR has been merged and made it into release 10.0.0 a few weeks ago. This is no longer an issue, so we could generate a single definition file with ts-rs in the future if we decide it's a better crate.

The original implementor also left the above comment on #181 in reference to ts-rs:

The generated type declarations are not yet well integrated with wasm-pack artifacts, and function types still use any. Additionally, to generate the type declarations, you need to run cargo test before running wasm-pack.

The maintainers did not pursue this issue further, but it presumably solvable.

tsify

Given the above issues faced during GSoC (on which the contributor spent significant time), we suggested looking at tsify as an alternative. As you can see in the PR, the changes were minimal, and we are currently using it to generate type definitions. tsify is a more minimalist crate, but it does appear to be fairly well maintained (a bit less active than ts-rs, but that's not necessarily a bad thing). It does the job of generating a single .d.ts file automatically as part of the wasm-pack build.

So far, tsify seems to do its job well without any hiccups, but in case it ever becomes unmaintained, we can revisit ts-rs.