Build one engine per feature set: erase, downlevel, and downlevel-jsx #6

Closed natemoo.re
targeting bench-tools from engines
Closed opened by natemoo.re
targeting bench-tools from engines

Adds a third engine, so downlevel mode without JSX output loads a 4.7 kB smaller downlevel.wasm.

There is now one engine per feature set: erase.wasm, downlevel.wasm, and downlevel-jsx.wasm for downlevel mode writing JSX. A call loads only the engine its options need. Few programs use more than one mode, and the main use case, making TypeScript or TSX runnable, is plain downlevel or downlevel with JSX.

What changes #

  • scripts/gen/hooks.mjs writes engine/hooks.zena per engine. Each hook is hooks-downlevel.zena's forward when its feature is in the set, and hooks-erase.zena's stub otherwise, so a feature an engine leaves out is never in its import graph. The engine sources are unchanged.
  • The wrapper picks the engine from the mode and JSX runtime. runtime: "preserve" uses downlevel.wasm.
  • @nibling/typestrip/downlevel-jsx.wasm is a new package export.
  • Drops stripV1, dead since ABI v2: it called an undefined load().

Cost #

Downloads, gzip, wrapper included:

uses before after
erase, with or without JSX 17.1 kB 17.0 kB
downlevel 27.1 kB 22.3 kB
downlevel + JSX 27.1 kB 27.0 kB
npm tarball 50.9 kB 69.5 kB
npm unpacked 126.0 kB 171.2 kB

The npm package grows, because three engines each carry the parser.

Alternative considered #

A base engine plus feature modules loaded on demand into its hook table. It gave the smallest package, a 39.8 kB tarball, since the parser ships once, with byte-identical output. But the base has to keep live every strip-side path a module might call: erase-only downloads grew 1.8 kB, downlevel + JSX 2.5 kB, throughput fell up to 4% from the module boundary, and first-pass RSS rose about 4 MiB. docs/architecture.md records it under "Tried and rejected", and docs/decisions/engines.tsv has every measurement.

Verification #

  • scripts/compare-outputs.mjs: output and errors byte-identical to the base branch across 20,772 runs, every mode and JSX runtime, whole and chunked.
  • erase.wasm is byte-identical to the base branch's. downlevel-jsx.wasm is built from the same sources as the base branch's downlevel.wasm, at the same size.
  • pnpm test, including lazy-load, which now proves erase mode's JSX and runtime: "preserve" never load downlevel-jsx.wasm. The 1,603-file TSX sample passes.
  • Throughput: a 5-round A/B of an earlier static build of the same feature sets, at load 2–5, measured +0.2% to +3.8% against the base branch, 26–29% ahead of oxc-transform. A rerun on this exact build was too noisy to resolve (load reached 20), with no difference outside its ranges.

Open questions #

  • The benchmark tables aren't republished for this layout yet. They need a quiet machine for about 25 minutes.

Stacked on #5.

Commits 2

Document the three engines, and record why not a base with feature modules
Build one engine per feature set: erase, downlevel, and downlevel-jsx