Roadmaps / TypeScript / Phase 1
Phase 1 of 4 · Study weeks 1-4
The type system as a design tool
This phase makes the first checkpoint possible: a domain model where wrong states do not compile, and a test suite that proves it.
Topics every week
- Week 18 h
- Structural typing and excess property checks
- Unions, intersections and narrowing
- Discriminated unions
- Exhaustive checks with
never
Hand inA checkout state machine where five impossible states fail to compile
- Week 28 h
- Generics, constraints and inference
satisfies,as constand const type parameters- Variance and why mutable arrays are unsound
unknown,anyandnever
Hand inA generic
Resulttype and a typed event emitter, each with type tests - Week 38 h
- Conditional, mapped and template literal types
inferand recursion limits- Utility types and writing your own
- Type tests with
tsdorexpect-type
Hand inTen medium type challenges, each with a one-line reason and a type test
- Week 48 h
- Soundness holes: assertions, index access, optional against
undefined - Strict flags (
noUncheckedIndexedAccess,exactOptionalPropertyTypes) - Branded types
- Lint rules that ban
any
Hand inCheckpoint 1, and a holes catalogue with your prediction beside the result
- Soundness holes: assertions, index access, optional against
Practice projects
- Practice 1, impossible states (Week 1): model a checkout flow (cart, paid, shipped, refunded) as a discriminated union. Done when: five invalid states each fail to compile with a named reason, and every
switchover the state is exhaustive throughnever. - Practice 2, the type challenges (Week 3): solve ten medium challenges from the type-challenges collection. Done when: each has a passing type test, a one-line explanation, and a note on what happens at a recursion depth you chose.
- Practice 3, the soundness catalogue (Week 4): write eight snippets that compile but fail at runtime (an array write through a wider type, a cast, an unchecked index,
Object.keys, a misused optional). Done when: each has a failing runtime test, and the flag or pattern that closes it. - Optional, a type-safe builder: a fluent builder that refuses to build until every required field is set. Done when: calling
build()early is a compile error with a test.
GitHub repos to study
Existence, last commit and README notices were checked on 22 Nov 2026 by shallow clone. Every repository below had a commit in the last six months. Archive status comes from the README, not from the GitHub setting, so look again before you rely on one.
| Repo | What to read | Week |
|---|---|---|
| microsoft/TypeScript-Website | The handbook source: narrowing, generics, conditional types | 1 |
| type-challenges/type-challenges | The challenges and the community solutions, by difficulty | 3 |
| sindresorhus/type-fest | How well-documented utility types are written and tested | 3 |
| gvergnaud/ts-pattern | Exhaustive matching built in the type system | 1 |
| microsoft/TypeScript | The tests/cases folder: how each rule is pinned by a test | 4 |
Milestone checkpoint
Build the domain package (Checkpoint 1 above). Write the 20 must-not-compile files first, each naming the rule it shows, and watch each one fail for the right reason. Then write the model that satisfies the 20 must-compile files. Turn on the strict flags, add the lint rule that bans any, ! and unchecked as, and add the seeded union member. Hand in the two lists, the lint output, ADR-1 (type or interface, and one rule for the codebase) and ADR-2 (errors as values or exceptions).
Check yourself
Answer each question in your head first, then open it to check.
Why is
{ a: 1, b: 2 }assignable to{ a: number }from a variable but an error as a fresh literal?Excess property checks apply only to fresh object literals. Elsewhere, structural typing allows extra properties.How does
nevermake aswitchexhaustive?In the default branch the remaining type isnever. Assigning it to anevervariable fails to compile if a member was left out.When do you use
unknown, and whenany?unknownfor a value you must check before use (input from outside).anyswitches checking off, so keep it to a narrow, commented boundary and count it.Why does this compile, and what is wrong with it:
const xs: number[] = []; const ys: (number | string)[] = xs; ys.push('a');?Mutable arrays are treated as covariant, which is unsound:xsnow holds a string. Usereadonlyarrays when you only read.What does
noUncheckedIndexedAccesschange?Index access returnsT | undefined, so you must handle a missing element.