You will build wyrm, a small programming language, in TypeScript — by hand.
fn makeCounter() {
let count = 0;
fn inc() { count = count + 1; return count; }
return inc;
}
let counter = makeCounter();
print counter(); // 1
print counter(); // 2
By the end you'll have a scanner, a parser, a tree-walking interpreter with closures, native functions, a REPL, a file runner, and a static resolver pass — and you will have typed every line of it yourself.
- Type everything by hand. No copy-paste. Not even once. Typing is how the syntax gets into your fingers, and the typos you make are how you learn to read compiler errors.
- Tests first. Every lesson gives you the tests before the code. Type the tests, run them, watch them fail, then type the code and watch them pass.
- Zero runtime dependencies. The only packages are
typescriptand@types/node, and both are dev-only. Tests use Node's built-innode:test. - The strictest compiler we can get. See
tsconfig.jsonin lesson 01. - Banned (unless a lesson says otherwise):
any— useunknownand narrow it.ascasts — if the compiler disagrees with you, convince it (narrowing, type guards), don't overrule it. (as constis allowed: it's not a cast, it makes a type narrower.)!non-null assertions — handle theundefinedcase.
- Study Drills are not optional. Every lesson ends with drills that give you no code. A lesson is done when the tests pass and the drills are done.
- When you get stuck: read the error message out loud, all of it. Then re-read the lesson. Then compare your code with the lesson character by character. Then ask.
Each lesson in lessons/ has the same shape:
| Section | What you do |
|---|---|
| Goal | Read. What we're building and why. |
| Concepts | Read carefully. The TypeScript ideas this lesson teaches. |
| Tests first | Type the tests. Run npm test. See them fail (red). |
| The code | Type the code. Run npm run check. See everything pass (green). |
| What you should see | Compare your output. |
| Study Drills | Do them. No code is given. |
| Checkpoint | Tell Claude "lesson NN done" → code review + quiz → tick it off in PROGRESS.md. |
npm test # run all tests
npm run typecheck # run the TypeScript compiler (type errors only, no output files)
npm run check # both — this is the one that counts
npm run wyrm # start the REPL (from lesson 22; in lesson 21 use `node src/main.ts`)
npm run wyrm -- examples/fib.wyrm # run a file (from lesson 22)
⚠️ Node runs.tsfiles by stripping the types — it never checks them. A program with type errors will still run.npm run typecheckis the only thing that tells you the truth. Always usenpm run check.
PROGRESS.md— your checklist.CONTEXT.md— the glossary. When a lesson uses a word like lexeme or environment, it means exactly what's written there.docs/adr/— records of design decisions and why they were made.lessons/— the course.
| # | Lesson | Main TypeScript idea |
|---|---|---|
| 01 | Setup | tsconfig, ES modules, node:test, type stripping |
| 02 | Tokens | literal unions, as const, type predicates |
| 03 | Scanner I | classes, private/readonly, generic Result<T, E> |
| 04 | Scanner II | helper functions, default parameters |
| 05 | The AST | discriminated unions, recursive types |
| 06 | AST printer | exhaustive switch, never, rest parameters |
| 07 | Parser I | recursive descent, precedence |
| 08 | Parser II | custom Error classes, override, instanceof |
| 09 | Pipeline & first CLI | process.argv, exit codes, exactOptionalPropertyTypes |
| 10 | Evaluating expressions | typeof narrowing, union return types |
| 11 | Runtime errors | assertion functions (asserts x is T) |
| 12 | Statements & print | function types, dependency injection |
| 13 | Variables | Map<K, V>, the compiler as a refactoring guide |
| 14 | Blocks & scope | recursive classes, try/finally |
| 15 | if / and / or | adding union members, case fallthrough |
| 16 | while | consolidation |
| 17 | Functions | getters, circular import type |
| 18 | return | modelling control flow as data |
| 19 | Closures | object identity & lifetime |
| 20 | Native functions | generics, mapped tuple types, const type params |
| 21 | The REPL | async/await, streams, for await |
| 22 | Running files | node:fs/promises, unknown errors, top-level await |
| 23 | Resolver (capstone) | static analysis, Map keyed by objects |