Migration to TypeScript (2026)

[chharvey]

Hello Binaryen team,

This PR starts a significant effort to migrate the JS API to TypeScript!

There's already an ongoing open discussion: #8656. Anyone is more than welcome to join and voice their thoughts.

---

For any non-JS developers, TypeScript is a type-safe superset of JavaScript that attempts to catch errors at compile-time rather than at runtime. I believe it brings many benefits to a project like this, including:

• static, structural typing
• code as inline documentation
• “intellisense” & autocomplete support in modern IDEs/editors
• ECMAScript modules, code-splitting, tree-shaking

TypeScript typings have been maintained separately by the AssemblyScript project, which means they drift out of sync as Binaryen evolves. This PR brings the typings and the implementation into the same codebase so they are always in sync. In other words, JavaScript development is now just TypeScript development.

Aside from the general benefits of TS, this effort also reorganizes the codebase into a more logical structure rather than having everything in one monolithic file. This makes the code easier to navigate, maintain, and contribute to.

---

In this PR, I haven’t touched any of the original JS code (/src/js/binaryen.js-post.js) or the existing tests, but instead copied it into a completely new TS codebase at /ts/. If my proposal is accepted, my plan is to phase out the existing code and tests little by little, making sure there are no breakages in the process. That'll probably look like more incremental PRs in the future instead of combined into one giant one.

For examples and development guide, see the /ts/README.md file. I also got started on migrating a handful of tests, but they can wait for another PR.

Under the hood, the biggest architectural change is how the TypeScript layer integrates with the Emscripten build. Currently, the post.js file is appended directly to the Emscripten output via the --post-js flag and the entire thing is compiled together into a single bundle. In my approach, Emscripten first builds and bundles the WASM bindings into an artifact which is then imported and wrapped by the TS. This decouples WASM binding generation from TypeScript API development, meaning the two can evolve independently without requiring a full rebuild every time the TS layer changes. It also makes the TypeScript layer independently testable and debuggable. Users can step through the code without having to navigate a minified bundle.

There are several other important changes I've made to the API, which I think more intuitively organizes the code and creates a more predictable access surface. The API Overview doc, specifically the deprecations section, gives a high-level overview. For the complete API generated from code, see the docs hosted on gh-pages of my fork. If anyone has strong opinions, I'm open to suggestion. We want both developers and users to be happy.

---

Some open questions, which we can discuss either here or in #8656.

1. The entire TS codebase, including package files and new Node.JS tests, lives under the top-level /ts/ folder. Is that where it should stay? How do the Binaryen repo owners prefer to organize the code?
2. Docs are generated at /docs/binaryen.ts/ from the root level, but this is only to get the gh-pages branch to work. (Ideally they'd live alongside the TS source code.) If we decide to publish docs elsewhere, they can be moved.
3. Do we want to publish to NPM? I already have binaryen.ts registered at https://www.npmjs.com/package/binaryen.ts, if we decide to stick with it. New contributor permissions can be added if needed.

---

I'm hoping this can make a positive impact on the long-term health of the project, and I'm committed to carefully following through. All feedback is appreciated, and thank you!

[ericvergnaud]

@chharvey you need to fix the build before any review can take place

[ericvergnaud]

Also, I'm a bit surprised that you present this PR as your sole contribution ?
IIUC this discussion my contribution was key to this effort, but you make it sound like you deserve all the merit ?
A more respectful approach would be to base this PR on my initial proposal, and augment it with your proposed changes...

[chharvey]

@ericvergnaud My intention was not to take all the credit, and i apologize if that's how it's perceived. I did give you a shout-out in my opening message in #8656 and mentioned that the work you did was the spark and inspiration behind my proposal.

When i first checked out your branch my initial goal was to propose a PR with modifications into it, but it was far behind the latest main at the time and there were too many conflicts. The JS file had fallen too far out of sync with your proposed TS changes and i couldn't resolve it. That's why i decided to start from scratch and leave the original JS code untouched in this PR. Furthermore i reorganized all the JS code into modules in the TS codebase so it deviated too far from a simple one-to-one translation.

Anyway i realize you did contribute a lot of effort to the TS development side of things and i don’t want that to go unnoticed, so my thanks goes to you for taking initial action. I’m looking forward to any constructive feedback you might have on this PR; if you have any suggestions to apply from your branch then i'm more than happy to accommodate. I'm hoping we can work together to finalize this effort and continue to provide TS maintenance as the Binaryen C++ codebase evolves.

[ericvergnaud]

It's not "how it's perceived", it's how it "is": none of my commits, not a single mention of my work.
I just merged latest main into my generate-typescript branch, and there are only 3 minor conflicts, so where do you take it that "there were too many conflicts", and why din't you reach out to me to address them ?
You're not acting in good faith, which translates into: you've just managed to ruin the recent progress re governance, which was the only blocker for merging #6192.
Your PR does the same as #6192 i.e. introduce TypeScript as a target language, just in a different way, which was never discussed.
There are good API proposals in this PR, and they would have been worth a few PRs on top of #6192.
What we have now is 3 concurrent PRs: #6192, #8826 and #6224, which only increases the size of the problem to solve.