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
- 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
unknownJSON into domain types, with 10 malformed payloads tested - 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
switchis exhaustive - Week 78 h
- One contract, three uses: handler, client, validator
- A typed
fetchwrapper - 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
- 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
unknownwith a schema. Done when: ten malformed payloads each return a typed error naming the failing path, and the parser has zeroas. - Practice 2, the error contract (Week 6): give each endpoint an explicit error union. Done when: a client
switchonerror.codeis 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,undefinedandNaNthrough 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.
| Repo | What to read | Week |
|---|---|---|
| colinhacks/zod | How a schema becomes an inferred type, and how errors are built | 5 |
| standard-schema/standard-schema | The shared interface: what a library must expose | 5 |
| honojs/hono | Typed routes and the RPC client built from them | 7 |
| trpc/trpc | End-to-end types from a router, and the cost in type complexity | 7 |
| OAI/OpenAPI-Specification | The OpenAPI document you generate in Week 8 | 8 |
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.
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.What does "parse, do not validate" mean?
Turnunknowninto a precise type once, at the boundary, and fail there. Inner code then never sees bad data.Why is
JSON.parse(text) as Orderdangerous?The assertion silences the checker and checks nothing. Any shape passes until something breaks later and far away.What happens to a
Dateand abigintthrough JSON?ADatebecomes an ISO string and stays a string afterJSON.parse.JSON.stringifythrows on abigint. Use a codec at each end.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.