knaxuslearn · build · ship

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

  1. 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

  2. Week 28 h
    • Generics, constraints and inference
    • satisfies, as const and const type parameters
    • Variance and why mutable arrays are unsound
    • unknown, any and never

    Hand inA generic Result type and a typed event emitter, each with type tests

  3. Week 38 h
    • Conditional, mapped and template literal types
    • infer and recursion limits
    • Utility types and writing your own
    • Type tests with tsd or expect-type

    Hand inTen medium type challenges, each with a one-line reason and a type test

  4. 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

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 switch over the state is exhaustive through never.
  • 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.

RepoWhat to readWeek
microsoft/TypeScript-WebsiteThe handbook source: narrowing, generics, conditional types1
type-challenges/type-challengesThe challenges and the community solutions, by difficulty3
sindresorhus/type-festHow well-documented utility types are written and tested3
gvergnaud/ts-patternExhaustive matching built in the type system1
microsoft/TypeScriptThe tests/cases folder: how each rule is pinned by a test4

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.

  1. 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.
  2. How does never make a switch exhaustive?
    In the default branch the remaining type is never. Assigning it to a never variable fails to compile if a member was left out.
  3. When do you use unknown, and when any?
    unknown for a value you must check before use (input from outside). any switches checking off, so keep it to a narrow, commented boundary and count it.
  4. 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: xs now holds a string. Use readonly arrays when you only read.
  5. What does noUncheckedIndexedAccess change?
    Index access returns T | undefined, so you must handle a missing element.