Learnings from running the examples with no toolchain
Phase 1 was writing 26 example projects under examples/ and running them with stock tooling. Everything failed, in three distinct ways, and each failure dictated a piece of the MVP design.
Failure 1: the extension is a hard wall
node examples/01-hello/src/main.tsus and node --experimental-strip-types both die with ERR_UNKNOWN_FILE_EXTENSION before reading a single byte. Node's type-stripping only accepts .ts/.mts, so a new extension means we own the compile step end to end. There is no incremental "mostly works" path.
Consequence for the MVP: tsus build must exist and must emit plain .js before anything runs. Compiled output has to be standard ESM so Node and Cloudflare Workers can consume it with zero knowledge of .tsus.
Failure 2: match blocks are not parseable TypeScript
Renaming 04-match-option/src/main.tsus to .ts and running tsc --noEmit produces TS1005: ',' expected and TS1109: Expression expected at the match arms. The TS parser cannot recover into anything useful, so we cannot implement match as a tsc plugin or an AST transform over the original source.
Consequence: the MVP needs a preprocessor that runs before the TypeScript parser, scanning raw text and rewriting match (expr) { Pattern(x) => body } into a plain function call (__tsus_match). The scanner has to be a real tokenizer that understands strings, template literals (including nested ${}), and comments, because example 24 deliberately plants fake match blocks inside all of those. A regex will not survive it.
Failure 3: import specifiers with .tsus extensions break resolution
Even with compiled output, import { safeSqrt } from "./math.tsus" would still fail at runtime because nothing on disk has that name after compilation. The examples with import chains (12, 20, 21, 22) all hit this.
Consequence: the build step rewrites .tsus and .ts specifiers to .js in emitted code, and compiles sibling .ts files too, so a mixed ts+tsus project comes out as one coherent dist tree.
Smaller findings baked into the design
awaitinside a match arm: arms compile to arrow functions, so an arm whose body containsawaitmust become anasyncarrow, and__tsus_matchthen returns a promise the caller awaits. Example 19 forces this."abc".match(/\d+/)and a user function literally namedmatch(example 25) must not trigger the macro. The rewrite only fires onmatch (expr) {where the token is not preceded by.or an identifier character, and only when a{follows the closing paren.- Bare string-literal patterns (
"/" => ...in the worker example) mean patterns are not just variant tags; the runtime match needs literal equality patterns plus a_wildcard. - Circular
.tsusimports (example 21) are fine as long as the cycle is function-level, because compiled output is ESM and ESM handles cycles with hoisted bindings. The compiler does not need to detect cycles for the MVP. - The checker rules (no class, no null, no undefined, no var, no throw) apply to
.tsusfiles only. Examples 13 and 22 have.tsdependencies that use classes, null, and undefined on purpose; the checker must scope itself by extension or mixed projects are impossible.
Outcome
With the MVP in place (packages/runtime + packages/cli), the harness reported 26/26 examples passing, including the five that pass by being rejected with the expected diagnostic code. The MVP's known limitations, in honesty order, were:
- No semantic type-checking:
tsus buildstripped types per-module (ts.transpileModule), so type errors surfaced at runtime. - No exhaustiveness checking: a non-exhaustive match threw
TSUS100at runtime instead of failing at compile time. - The
await-in-arm detection was textual, so a string literal containing the wordawaitwrongly made that arm async. - Regex literals were not tokenized; a regex containing a quote or brace character could confuse the scanner.
All four are closed now. The next section is what closing them taught us.
Learnings from the compiler foundation
The scanner is free, the context is not
ts.createScanner already knows strings, comments, numbers, and every operator, including the ones that matter for ?: it emits ?. and ?? as their own tokens, so telling them apart from a bare ? costs nothing. What it cannot know is parser context. Two tokens need a rescan: / (division or regex) and } (end of a block or the resume of a template after ${). Regexes are decided by a one-token lookbehind (after an identifier, literal, ), ], or } it is division), and templates by remembering the brace depth at each TemplateHead. Example 32 is the regex /["']/g`, which the old hand-written scanner read as the start of a string and a template.
Typing match took three tries
The obvious signature, <V, R>(value: V, arms: { [K in TagOf<V>]: (p: Payload<V, K>) => R }) => R, type-checks the arms but infers R as unknown: TypeScript cannot infer through a mapped type whose keys are a conditional type of another type parameter. Every match silently became unknown.
Currying fixes inference. __tsus_match(value)(arms) fixes V in the first call, so in the second the mapped type has concrete keys. Then there was a choice about the result type. A single R is Rust-like (arms must agree, errors land on the offending arm), but it rejects the most common tagged-union code: Idle => tag("Running", ...), Running => tag("Done", ...) returns two different variant types, and TypeScript will not unify them into the declared union. So the arms object is inferred as a type parameter A extends MatchArms<V>, and the match's type is the union of the arms' return types. Exhaustiveness comes from the constraint, unknown arms from an extra mapped type that maps foreign keys to never.
One more wrinkle: when the constraint fails (the real error), TypeScript falls back to it, and if the constraint's arms return unknown, every use of the match reports a second, misleading error. The constraint returns any, which only ever surfaces after a match is already reported broken.
_ cannot be a key in the same object without turning the mapped type into a union, which breaks contextual typing for the arm parameters, so a wildcard match lowers to a separate __tsus_match_or(value)(arms, otherwise).
Literal patterns are a different shape
String patterns (the worker router) cannot share the keyed-object design: number and string literals would collide as keys, and the literal "_" would collide with the wildcard. They lower to __tsus_match_lit(value)([[literal, handler], ...], otherwise?). A const type parameter keeps each literal's type, each literal is checked against the subject's type, and the otherwise parameter is a rest tuple that is required exactly when Exclude<V, literals> is not never. So a "GET" | "POST" | "DELETE" subject needs no _ once all three are listed, and a plain string subject always needs one.
? is a parse error with a useful shape
const x = load()?; is not TypeScript, but the parser's error recovery turns it into a conditional expression whose true branch is a zero-width missing identifier. That node gives the operand (the condition) and its precise extent, and walking its parents gives the enclosing function and the statement to hoist an early return in front of. A candidate is only accepted when the token after ? is ;, ), ], }, ,, or the end of input, and when the true branch is missing, so valid ternaries, optional parameters ((x?) => x), optional tuple elements, and ?: in types never match.
Two consequences of riding the conditional operator's precedence: ? covers everything to its left, which is exactly right for await load()? (it unwraps the awaited value), and a()? + 1 is a syntax error that wants parentheses. Rust's postfix ? binds tighter, and we chose not to fight the parser over it.
Hoisting is only sound where the operand always runs, so ? in a ?: branch, on the right of &&/||/??, or in a loop condition is rejected (TSUS303) rather than silently evaluated early. ? inside a match arm is rejected too (TSUS300): arms are closures and cannot return from the enclosing function.
The type plumbing is three identity functions. __tsus_try constrains the operand to Result | Option (TSUS301 when it is not), a type guard narrows the bail case, and __tsus_bail re-types an Err<T, E> as Err<never, E> so it fits any Result<U, E>. When it does not fit, TypeScript's error lands on the generated return, which is how TSUS302 is detected.
Diagnostics are classified by where they land
Every lowering pass writes through an emitter that records each output run as either a verbatim copy (maps offset-for-offset) or synthesized glue (maps to one anchor). Passes compose, so any offset in the final TypeScript maps back to the .tsus file. The same table classifies TypeScript's errors into stable codes: a TS2345 that lands on a match's copied { is a missing arm (TSUS201, with the missing variants read off the subject's type through the checker), an error on a copied arm name is TSUS202, a TS2345 at the start of a __tsus_try( argument is TSUS301, anything on the generated return is TSUS302. Everything else is TSUS200 with the TS code attached.
The runtime import is prepended on line 1 with no newline, so line numbers in the lowered code, the emitted JS, and stack traces without source maps still match the .tsus file.
Semantic checking found a real bug immediately
Example 16 had passed since the MVP, but wrapAsync(readFile) infers from readFile's last overload, so the Ok payload was string | Buffer, and text.trim() was a type error that only worked at runtime because the call happened to pass "utf8". The first ts.createProgram run flagged it. The fix pins the overload: wrapAsync((file: string) => readFile(file, "utf8")).
The virtual compiler host serves each .tsus file as <file>.tsus.ts and resolves ./x.tsus specifiers itself; everything else goes through TypeScript's normal bundler resolution, so .ts files importing .tsus (example 14) and .tsus importing .ts (example 13) both type-check as one program.
Caches remember old compilers
After the runtime's match signature changed, next build in example 27 produced an empty page: Next's persistent webpack cache in .next/cache kept serving the old loader output, which called the new runtime with the old arguments. Webpack cannot see through the loader's dynamic import() to the compiler files, so the loader now declares them with addBuildDependency.
Known limitations now
- The bundler plugins transform one file at a time and only run the syntactic rules; type errors surface in
tsus check, not in the framework build. tsus checkuses fixed compiler options and ignorestsconfig.json.?binds like?:, so it needs parentheses inside larger expressions; its return-type check is syntactic and does not see through type aliases.- Match arms are typed as a union, and raw object literals in arms are not contextually typed by the declared return type (
tagwidens tostring); usetag(...). - The regex lookbehind treats
/after)or}as division, commas in type arguments inside an arm body rely on a merge heuristic, and an arm body cannot be a statement block. - If any arm awaits, every arm of that match becomes async.