knaxuslearn · build · ship

Roadmaps / TypeScript / Phase 2

Phase 2 of 4 · Study weeks 5-8

Runtime boundaries and the contract

This phase makes the second checkpoint possible: types that match real data, because every boundary parses what it receives.

Topics every week

  1. Week 58 h
    • Types are erased
    • Parse at the boundary, do not assert
    • Schema libraries and the Standard Schema interface
    • Types inferred from schemas

    Hand inA parser that turns unknown JSON into domain types, with 10 malformed payloads tested

  2. Week 68 h
    • Errors as values and typed errors
    • Exceptions at the edges
    • An error contract for the API
    • Exhaustive handling of error unions

    Hand inAn error model where each endpoint lists its errors and a client switch is exhaustive

  3. Week 78 h
    • One contract, three uses: handler, client, validator
    • A typed fetch wrapper
    • Serialisation pitfalls (Date, bigint, Map, undefined)
    • Codecs

    Hand inA round-trip table of what each value becomes through JSON, and a codec that restores it

  4. Week 88 h
    • OpenAPI and JSON Schema output
    • Contract tests
    • Versioning and compatibility (additive against breaking)
    • Deprecation

    Hand inCheckpoint 2, and a compatibility check against the previous OpenAPI file

Practice projects

  • Practice 1, the boundary parser (Week 5): parse an order payload from unknown with a schema. Done when: ten malformed payloads each return a typed error naming the failing path, and the parser has zero as.
  • Practice 2, the error contract (Week 6): give each endpoint an explicit error union. Done when: a client switch on error.code is exhaustive, and adding a new error code breaks the build in every client that ignores it.
  • Practice 3, the round trip (Week 7): send Date, bigint, Map, undefined and NaN through JSON. Done when: a table lists what each becomes, and a codec test restores the originals or rejects them on purpose.
  • Optional, a second schema library: replace the schema library behind the Standard Schema interface. Done when: the contract tests pass unchanged and you report the type-check time difference.

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
colinhacks/zodHow a schema becomes an inferred type, and how errors are built5
standard-schema/standard-schemaThe shared interface: what a library must expose5
honojs/honoTyped routes and the RPC client built from them7
trpc/trpcEnd-to-end types from a router, and the cost in type complexity7
OAI/OpenAPI-SpecificationThe OpenAPI document you generate in Week 88

Milestone checkpoint

Build the contract kit (Checkpoint 2 above). Define three endpoints first and generate the handler type, the client, the validator and the OpenAPI file from them. Write the seeded faults as tests: wrong server shape, misspelt client field, missing runtime field, the Date and bigint round trip. Then add endpoints up to your scope. Hand in the fault table with your own results, ADR-3 (schema first or types first, with the rejected options) and ADR-4 (how errors cross the wire).

Check yourself

Answer each question in your head first, then open it to check.

  1. Why can a TypeScript type not validate a request at runtime?
    Types are erased before the program runs. A runtime check needs code that inspects the value.
  2. What does "parse, do not validate" mean?
    Turn unknown into a precise type once, at the boundary, and fail there. Inner code then never sees bad data.
  3. Why is JSON.parse(text) as Order dangerous?
    The assertion silences the checker and checks nothing. Any shape passes until something breaks later and far away.
  4. What happens to a Date and a bigint through JSON?
    A Date becomes an ISO string and stays a string after JSON.parse. JSON.stringify throws on a bigint. Use a codec at each end.
  5. Which contract changes break existing clients?
    Removing or renaming a response field, adding a required request field, narrowing an accepted input, or changing a type. Adding an optional response field is usually safe, if clients ignore unknown fields.