Rebasely Beta: data may be purged

justintypescript-ultra-strict Public

Markdown · 14.2 KiB · at eb4a6ea

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

  • await inside a match arm: arms compile to arrow functions, so an arm whose body contains await must become an async arrow, and __tsus_match then returns a promise the caller awaits. Example 19 forces this.
  • "abc".match(/\d+/) and a user function literally named match (example 25) must not trigger the macro. The rewrite only fires on match (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 .tsus imports (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 .tsus files only. Examples 13 and 22 have .ts dependencies 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:

  1. No semantic type-checking: tsus build stripped types per-module (ts.transpileModule), so type errors surfaced at runtime.
  2. No exhaustiveness checking: a non-exhaustive match threw TSUS100 at runtime instead of failing at compile time.
  3. The await-in-arm detection was textual, so a string literal containing the word await wrongly made that arm async.
  4. 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 four 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. A single inferred R then works, but it is too strict in a TypeScript way: Idle => tag("Running", ...) and Running => tag("Done", ...) return two different variant types, and TypeScript picks the first as R and rejects the second even when the function declares the union as its return type.

The third version inferred the arms object as a type parameter A extends MatchArms<V> and typed the match as the union of the arms' return types. That handled variants, and examples 1 to 36 passed, but the eval harness's reference solutions (merged while this work was in flight) failed on the most common error-handling line there is: None => Err({ kind: "missing" }) inside a function returning Result<T, QueryError>. With no contextual type reaching the arm, Err infers { kind: string } and the union no longer fits. Plain TypeScript gets this right in a ternary because the return type flows into both branches.

The version that shipped takes the result type from context when there is one and from the arms when there is not. R appears in the match's return type and, wrapped in NoInfer, in the arms' constraint, so it is inferred only from the contextual type. When a context exists, every arm is contextually typed by it (so Err({ kind: "missing" }) infers QueryError) and must be assignable to it, which also moves a wrong-arm error from the whole match onto the offending arm. When there is no context, R stays unknown, and a conditional type switches the result to the union of the arms. 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. Without a context 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 real bugs 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 eval harness's route-match reference had the same kind of latent error: .map((s) => (s.kind === "static" ? 3 : 0)).unwrapOr(1) infers Option<3 | 0>, so the fallback 1 does not fit. It now annotates the callback's return as number.

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

  1. 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.
  2. tsus check uses fixed compiler options and ignores tsconfig.json.
  3. ? binds like ?:, so it needs parentheses inside larger expressions; its return-type check is syntactic and does not see through type aliases.
  4. 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.
  5. If any arm awaits, every arm of that match becomes async.

Learnings from closing the escape hatches (TSUS401-413)

  • Banning untagged Result error types (TSUS410) broke nine of the original examples, all of which used Result<T, string>. Moving them to literal unions (Result<number, "division by zero">) or Tagged<"NotFound", string> cost a line or two each and made every error matchable. The rule is cheap to satisfy when it exists from the start and painful to retrofit, which is the argument for having it.
  • Cloudflare Workers require export default { fetch }, so a blanket default-export ban (TSUS406) is impossible. That forced the boundary to become a file-level concept: *.boundary.tsus relaxes exactly casts and default exports. Being visible in the file name keeps it reviewable, unlike a pragma comment.
  • Fix edits have to be expressed against the original .tsus text, but the rules see macro-expanded code. The rules use the preprocessor's offset map when it is passed in, and otherwise align the two texts themselves (rules/sourcemap.js: a line diff, then a token diff inside changed hunks). Either way a fix is only offered when its range covers text that is identical in both versions, so an edit can never land on generated glue. Example 54 puts fixes inside match arms to keep this honest.
  • Floating promises and unused Results are detectable without full type information for the common case: a call to a function whose declaration (in this file or a relative import) is async, annotated Promise<...> or Result<...>, or built with wrapAsync/wrapSync. When a ts.Program is available the same rules switch to real types.
  • "Safe" fixes are defined by runtime behavior, not by type-checking: any to unknown never changes what runs, but it can surface type errors any was hiding. That is the point of the rule, so it stays a safe fix.