Migration to TypeScript (2026)#8826
Open
chharvey wants to merge 267 commits into
Open
Conversation
post.js converts statically-defined members into instance members, but hides the static ones from public API. The deprecations can be deleted.
- `repository.url` was missing "git+" - adds "prepublishOnly" script - updates "files" field to include `./build/` - `package.json` is included by default - `package-lock.json` is excluded by default
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
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.mdfile. 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-jsflag 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.
/ts/folder. Is that where it should stay? How do the Binaryen repo owners prefer to organize the code?/docs/binaryen.ts/from the root level, but this is only to get thegh-pagesbranch to work. (Ideally they'd live alongside the TS source code.) If we decide to publish docs elsewhere, they can be moved.binaryen.tsregistered 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!