Native TypeScript Type Stripping in Boa's Parser

[AlbertMarashi]

Summary

I want to propose modifying Boa's parser to natively strip TypeScript type annotations at parse time, so .ts files can be executed directly without any prior transpilation step. This is explicitly not about implementing a type checker, a TypeScript compiler, or anything like that — purely discarding type-level syntax during parsing, leaving all JavaScript semantics untouched.

I also want to propose a clear policy: any TypeScript feature that introduces runtime semantics — const enum, namespace, legacy decorators, etc. — should be a hard parse error. We are not implementing TypeScript. We are implementing type stripping.

---

Motivation

TypeScript is just reality now

Most JavaScript written today is TypeScript. Requiring users to run a transpilation step before handing code to Boa makes us a second-class runtime for the majority of real-world JS projects before we even get evaluated. Type stripping is the minimum viable thing we can do to fix that.

The maintenance concern is overstated

I've seen the objection that supporting TypeScript means tracking TypeScript's release cadence on top of ECMA262 and ECMA402. I think this conflates type stripping with full TypeScript support — they aren't the same thing at all.

TypeScript's type annotation syntax sits in well-defined, stable grammatical positions that have no effect on control flow or semantics:

• : Type after parameters and variable bindings
• <T> generic annotations on functions and calls
• as Type cast expressions
• interface and type alias declarations
• Access modifiers (public, private, protected, readonly) on class members
• ! non-null assertions
• satisfies Type expressions

These positions have been stable for years. They basically can't change without breaking the entire TypeScript ecosystem. The maintenance surface is small, well-bounded, and completely different in character from tracking evolving ECMA spec semantics. If TypeScript adds a new annotation position in a future release, that's a contained, small fix — not a systemic commitment.

Node.js v22 shipped native type stripping and made the same judgment call. Deno has had it since v1.0. Bun has it. These are production runtimes with far higher stability requirements than us, and they all concluded the tradeoff was worth it.

Transpilation pipelines are genuinely painful

Every transformation step between source and execution introduces real problems that I think we underestimate:

Debugging is broken. Transpiled and bundled output produces stack traces like:

Error at bundle.min.js:1:84920

Source maps are supposed to fix this but they drift out of sync, don't survive all transform pipelines cleanly, and add their own complexity. With native type stripping the stripped output is essentially identical to the original source — line numbers, column numbers, variable names all 1:1. Stack traces just point at your actual code.

Transpilers introduce their own bugs. Targeting older JS versions means nullish coalescing gets rewritten, async/await gets transformed, class fields get emulated — all with subtle behavioral differences from native semantics. Type stripping touches nothing semantic. The JS that executes is exactly what you wrote.

Build environments are non-deterministic. The same TypeScript source can produce meaningfully different JavaScript depending on tsconfig.json settings, which transpiler you're using (tsc, esbuild, swc, babel), and what version of each. Native type stripping is deterministic and has zero configuration surface.

This is especially important for Boa's embedded use case

Boa's pitch is being an embeddable Rust-native JS engine. If someone embeds Boa to offer scripting in their Rust application, their users are going to want to write TypeScript. Without type stripping, the host application has to ship a transpiler dependency, manage a build pipeline, and pay a cold-start cost on every script load. Native stripping reduces this to a parse-time token discard — essentially free.

---

We Don't Have to Implement This From Scratch

This is actually one of the strongest arguments for doing this. There is already mature, production-grade Rust tooling that does exactly this:

• [swc](https://github.com/swc-project/swc) — Rust-native TypeScript/JS transform, used in production by Next.js, Deno, and others. The type stripping logic is well-established and we could either use it directly as a crate or study its implementation as a reference for our own.
• [oxc](https://github.com/oxc-project/oxc) — newer Rust-native parser and transformer, explicitly designed for performance. Also handles type stripping. Node.js v22's --experimental-strip-types is backed by amaro which wraps oxc-transform.
• [deno_ast](https://github.com/denoland/deno_ast) — Deno's own AST/parsing crate built on top of swc, another reference point.

We have options. We can integrate one of these crates directly, or we can base our own implementation off their grammar rules without reinventing the wheel. Either way, we're not starting from zero.

---

Scope

What this covers

• Stripping type annotation tokens during parsing
• interface and type alias declarations (discarded entirely — no runtime artifact)
• Generic syntax <T> on functions and calls
• as Type cast expressions
• Class member access modifiers (public, private, protected, readonly)
• Non-null assertions !
• satisfies Type expressions
• declare statements (discarded entirely)
• Discarding import type module imports
• Discarding import { type Foo, X } (type Foo) import fields.

What this explicitly bans with a hard parse error

Any TypeScript syntax that introduces runtime semantics that can't be expressed as pure JS is a parse error. We are not in the business of compiling TypeScript. If it needs the TypeScript compiler to lower it to JS, we reject it:

• const enum — gets inlined by the TypeScript compiler, has no JS equivalent
• enum — compiles down to an IIFE, introduces real runtime behavior
• namespace / module — same problem, compiles to real JS object structure
• Legacy experimentalDecorators behavior — out of scope entirely, use TC39 decorators
• emitDecoratorMetadata — requires type information at runtime, not our problem

The error message should be clear: "This TypeScript feature introduces runtime semantics and cannot be handled by type stripping. Please compile with tsc first."

Out of scope entirely

• Type checking or inference — not our job
• Declaration file (.d.ts) generation — not our job
• tsconfig.json handling — not our job
• Language server features — not our job

---

Implementation Approach

Type stripping is purely syntactic — no semantic analysis required. The parser hits a token that starts a type annotation, consumes tokens until the annotation ends, discards them, and moves on.

Rough touch points in boa_parser:

Lexer — a small set of new token kinds to recognize type-level syntax. Colon already exists but needs context to distinguish type annotation from ternary/object literal. Type keywords to add: type, interface, as, readonly, declare, satisfies, abstract.

Parser — annotation skip sites — type annotations appear at predictable grammatical positions. At each site the parser optionally consumes a type annotation and discards it:

VariableDeclaration:
  let x [: TypeAnnotation] = expr

Parameter:
  (a [: TypeAnnotation], b [: TypeAnnotation])

FunctionDeclaration:
  function f<T>(a: T) [: ReturnType] { }

ClassMember:
  [AccessModifier] [readonly] field [: TypeAnnotation]

Top-level declarations to discard entirely:

interface Foo { x: number }  // → nothing, completely discarded
type Bar = string | number   // → nothing, completely discarded
declare const x: number      // → nothing, completely discarded

Given that swc and oxc are both Rust crates, we should seriously evaluate whether integrating one of them for the stripping pass is lower cost than implementing the grammar rules ourselves. Even if we eventually want our own implementation, using swc/oxc as a reference for the exact grammar positions TypeScript uses is going to save time.

---

Prior Art

• Node.js v22 — --experimental-strip-types backed by amaro / oxc-transform
• Deno — native TypeScript since v1.0, uses swc under the hood
• Bun — native TypeScript via its own parser
• oxc — Rust-native parser/transformer, explicit type stripping support
• swc — Rust-native, production-proven, used by half the JS ecosystem

---

Open Questions

1. Do we integrate swc/oxc as a crate or implement our own stripping pass based on their grammar rules?
2. Should type stripping be opt-in via a runtime flag or automatic on .ts file extension detection?

---

Conclusion

Type stripping is a small, well-bounded parser feature with a large real-world payoff. It doesn't require us to become a TypeScript compiler, track TypeScript's type system, or take on significant ongoing maintenance. We have mature Rust crates we can lean on directly. The policy of hard-erroring on anything that introduces runtime semantics keeps the scope locked and the implementation honest.

The question isn't whether we want to support TypeScript. The question is whether we want Boa to be usable for the majority of JavaScript code written today.

[AlbertMarashi]

Source: https://github.com/tc39/proposal-type-annotations

---

The tc39 proposal to add type annotations to the javascript language itself also provides additional justifications as to why supporting type annotations in the language is a good idea.

[jedel1043]

A counterargument of this proposal is that for most folks, having something that "kind" of compiles Typescript but not really is worse than just straight up telling everyone that we do not support Typescript.

Imagine you're an embedder and you happily pass your Typescript files to Boa, and they compile and run perfectly fine. Everything's good and you deploy to prod knowing that you didn't need to create a whole Typescript pipeline for it.

Then, 3 months down the line, you slightly change your Typescript code and now everything breaks because Boa didn't support the Typescript feature you used, and now you require bundling a Typescript compiler. This would be very annoying for users that expect Boa to "just work".

That's why right now I'm very wary about adding Typescript support. because it's either we don't support it and delegate that to Typescript compilers, or we do and we need to properly support consts, enums, namespace, etc.

Also, this is kind of null if https://github.com/tc39/proposal-type-annotations goes forward, so my preference would be to help push that proposal onto stage 2 and implement that when the time comes.

[AlbertMarashi]

It's not even a controversial call on our part because the ecosystem has already made it:

isolatedModules — TypeScript's own compiler flag, required by basically every modern bundler (esbuild, swc, oxc, Vite, Babel), explicitly bans const enum and makes enum usage a warning. If you're using any modern toolchain you're already forbidden from using them.

Verbatim module syntax — TypeScript 5.0 added --verbatimModuleSyntax which is now the recommended default and also restricts enum usage.

oxc, swc, esbuild — none of them support const enum at all. They all error or warn on it. These are the tools half the JS ecosystem runs through today.

Node.js --experimental-strip-types — explicitly bans enum and namespace, hard errors.

The TypeScript team themselves — have said on record that if they were designing TypeScript today, enum wouldn't exist. The recommended replacement is as const objects which are pure JS.

So we wouldn't even be making an opinionated call by banning them — we'd just be aligning with what esbuild, swc, oxc, Vite, and Node.js already enforce.

---

Plus, we're seeing a lot of things moving towards WASM, AI-generated code, cloud editors, new IDEs, etc - and Boa has a serious edge to offer a unique combo here. People wanna be able to write and run quick typescript modules on the web in various applications without having to add a bunch of extra tooling in their app to support it.

[jedel1043]

Also, Deno, Node and Bun are Runtimes, not engines, so they have the liberty of just bundling a Typescript compiler, because they can be opinionated about what users to serve and what use cases to enable. We don't have that liberty unfortunately.

[jedel1043]

I'm not talking about literally bundling tsc. I'm talking about bundling a Typescript compiler in the sense that they bundled code that parses Typescript into their runtimes.

[jedel1043]

And again, they're Runtimes, so they play in a completely different field than an engine. Our engine needs to at least comply with the ECMAScript specification, and adding new parser rules would kind of go against ECMAScript compliance. That's why I mentioned that we don't have the liberty of being opinionated about what we do and don't support on the parser side.

[AlbertMarashi]

Do you think that this is maybe somebesidesthing that could be gated in the parser behind a feature flag? - that way it's clear what is ECMAScript and what is TypeScript in the codebase?

All we'd really be doing is treating these AST nodes as a type of whitespace/comment, making them invisible, is there any downside besides potential maintenance?

[jedel1043]

If we need to gate this behind a feature flag and fill our parser with non-standard extensions, then I think it would be better to instead have a separate crate that does this. At the end of the day, Boa's VM only understands ECMAScript, so a separate compiler can just compile Typescript instead of Javascript and output an AST that our Bytecompiler can understand.

[AlbertMarashi]

@jedel1043 what if the approach was to somehow augment the parser such that we could stream in javascript code, but perhaps provide some kind of annotation to skip or treat certain ranges or spans of text (type annotations) as "ignored" in the lexer/parser?

In other words, we have a typescript module that we want to run in Boa.JS - but whilst we're feeding in the typescript code, we tell the lexer/parser to treat certain bytes/chars as "whitespace"/"comments" (except it's just normal plain text) - the idea being that it retains the original typescript source code positions?...

I guess what I am describing is a way to manually signal/trigger boa to think that we're inside of a comment, without actually being in one?

[jedel1043]

What would be feasible though is to have some kind of API for converting a Typescript AST compiled by oxc/swc into our own AST representation, preserving all source code information in the way. This way users can just "hook" their favorite TS compiler in the compilation pipeline, then pass that transparently to Boa for Bytecode compilation.