TypeScript Core

[chharvey]

The first of several PRs in an attempt to break up #8826 into smaller parts. This PR sets up core typescript functionality and ports over only the top-level types, constants, and enums of the JS API.

Changes:

• adds root-level ts/ folder with README.md, package.json, tsconfig.json, and other project files
• updates root-level CMakeLists.txt, exporting needed variables & methods (like HEAP8) from Emscripten into the JS build
• ts/src/-pre.ts imports the Emscripten-built Binaryen function, calls and awaits it, and exports that as an internal object called BinaryenObj (AssemblyScript calls this object binaryen and exports that publicly).
• ts/src/**: the typescript library sits on top of the Emscripten artifact. it accesses the WASM bindings on BinaryenObj imported from -pre.ts.
• entrypoint ts/src/binaryen.ts for users, exporting all the parts of the public-facing API. Users use a namespace import instead of a default import:

  import * as binaryen from "binaryen.ts";
  

  (this better aligns with the ES Modules standard since it’s no longer a proper object).
  users will still use the same API (binaryen.ExpressionRef, binaryen.i32, binaryen.Module, etc.)
• starting some Node.JS tests at ts/tests/. hopefully this will take some of the weight off the python tests

Non-Changes:

• original binaryen.js-post.js file has not been touched; the tentative plan is to complete the TS migration before phasing out the JS code (unless decided otherwise by repo maintainers)
• python tests also haven’t been touched for now, but maybe a future PR will work on migrating them to Node.JS

API Deprecations (see ts/src/-deprecations.ts for full list; will evolve with more PRs):

• enum names have been singularized (e.g. binaryen.Features → binaryen.Feature)
• deprecations are still accessible as their old symbols (users can still use binaryen.Features, but there is a doc-comment @deprecated warning for intellisense support)

Get started:

brew install node # includes npm
cd ts/
npm ci          # downloads dependencies
npm run make    # rebuilds out-of-tree into ../build/ and copies the built js to ./build/
npm run check   # runs the python tests
npm run compile # compiles typescript to ./dist/
npm run test    # runs the node tests

See ts/package.json, ts/README.md, and ts/docs/API-Overview.md (in this PR) for details.

[chharvey]

TODO:

• package.json: update engines.node and devEngines.runtime.version to ">= 22"
• remove err from EXPORTED_RUNTIME_METHODS and accordingly in binaryen_js.d.ts, -pre.ts, & node tests

[kripken]

In general this looks pretty good to me, but not being a TypeScript person, I'm not the right reviewer here.

Hopefully @ericvergnaud or @brendandahl or other people already cc'd on this issue have time and interest to review this.

[chharvey]

Hi @kripken @tlively @MaxGraey @ericvergnaud , wondering if you could give this a review and/or more feedback. Happy to answer any questions.

I also have a stacked PR (#8881 is next, but there will be more) that depend on this, to break up #8826 into smaller parts as suggested.

Is there continued group interest in moving forward with this? If there is some hesitancy maybe we can continue the discussion in #8656.

Thanks!

[tlively]

I do think it would be nice to move forward with a TS API, especially given how much LLMs love to write typescript. I'm in the same boat as @kripken where I don't really have the background to do a useful review, though. We'll talk with @brendandahl and try to come up with a way forward soon. Thanks for your work on this and your patience in the meantime!

[ericvergnaud]

Given what's happened re TS over the past 2 years i.e. nothing, I believe the governance issue remains unsolved.
The core issue here is that the people who could merge a TS related PR don't have enough time or interest in it, or don't feel competent enough to do a review.
From there I think we should move binaryen for TS to a dedicated repo managed by people who can make things happen. It is not my preferred option but it's the only practical one.

[brendandahl]

Overall, looks pretty good. I'd like to get the typechecking test issue addressed though. Also, I may be missing something, but it also seems we're missing an end-to-end test that uses the result of npm compile in a TypeScript project. This doesn't need to be done in this PR (already huge), but would be good to add in the future.

[brendandahl]

Given what's happened re TS over the past 2 years i.e. nothing, I believe the governance issue remains unsolved. The core issue here is that the people who could merge a TS related PR don't have enough time or interest in it, or don't feel competent enough to do a review. From there I think we should move binaryen for TS to a dedicated repo managed by people who can make things happen. It is not my preferred option but it's the only practical one.

The one thing that has changed, is the burden of maintaining this (due to LLMs). I think we should try out merging this PR and see how keeping it up to date goes. As Thomas mentioned, I don't think this will be too bad anymore since <your favorite LLM> is pretty good at updating simple TS APIs.

[kripken]

@brendandahl That sounds great, thanks!

@ericvergnaud Your review of this code would also be appreciated, if you have interest. I think we are in a better place now than before.

[brendandahl]

One other issue I noticed, after building locally I had a lot of extra untracked files. I'm guessing there's some gitignore that needs to be updated.

[chharvey]

@brendandahl Which files did you notice? I updated the root .gitignore to include docs/, and then there's also a new ts/.gitignore file which lists all the local build files. Let me know if i missed something.