Roadmaps / TypeScript / The milestone project
Read first
The milestone project
Scenario. A company has an Orders service and a web app. In one quarter three incidents came from a field renamed on one side only. You build a contract kit: each endpoint is defined once (path, method, input, output, errors) and the kit derives a server handler type, a typed fetch client, a runtime validator and an OpenAPI document. The workspace has three packages (contract, server, web) in one pnpm workspace. Targets: any drift between server and client is a compile error; bad data at runtime gets a 400 and a typed error body, never a crash; the 60-endpoint stress file type-checks within a budget you set in Week 12 from your own measurements.
| Phase | Checkpoint | Done when |
|---|---|---|
| 1 | Domain types | A domain model (Order, Payment, Refund) uses discriminated unions and a Result type. strict, noUncheckedIndexedAccess and exactOptionalPropertyTypes are on. 20 must-not-compile files (each marked @ts-expect-error with a comment naming the rule) and 20 must-compile files pass tsc --noEmit in CI. A seeded new union member makes every unhandled switch fail to compile. Non-test code has zero any, zero ! and zero unchecked as, checked by lint. |
| 2 | Contract and boundary | One definition per endpoint yields a handler type, a typed client, a validator and an OpenAPI file. Seeded faults: a server returning the wrong shape is a compile error; a client sending a misspelt field is a compile error; a runtime payload with a missing or wrong-typed field gets a 400 with a typed error body; a Date and a bigint survive a round trip exactly as your codec documents. A contract change that removes a response field is flagged as breaking by a check against the previous OpenAPI file (fresher: skip the check). |
| 3 | Build and speed | The workspace builds with project references and incremental builds. Published types pass the attw check (are the types wrong) for ES module and CommonJS consumers. A table gives full check time for TypeScript 6 and TypeScript 7 (three runs each, median) with --extendedDiagnostics numbers for types, instantiations and memory. A --generateTrace run finds the slowest type, and fixing it cuts instantiations on the 60-endpoint file by at least 30%, or you explain in the report why it could not. A branch passes under TypeScript 7 with a written rollback. |
| 4 | Governance and release | The package is published to a local registry with type tests and an API report. A seeded breaking type change (narrowing a parameter type) fails the API report check in CI. A strictness ratchet takes one module of 20,000 lines or more from its starting error count to zero under strict, in ordered steps with a weekly count. Type-aware lint rules no-floating-promises and no-misused-promises are on, and CI blocks any rise in the count of any. A one-page type-safety policy is written. |
| W | Work version (Staff and Principal) | On a real codebase: measure a baseline (errors under strict, count of any, check time), make one change that tightens it (a strictness ratchet, a boundary parse or a compiler upgrade) and measure again. Pass: a target agreed in writing beforehand is met, or the any count and error count fall at least 30% with no rise in production incidents. The ADR is signed by a named stakeholder, scored by someone other than you, and a recheck is booked three months later. Level 4 also needs evidence that another team adopted your policy or checklist and recorded a result. Timebox: six weeks alongside Phases 3 and 4. |
Terms. Structural typing means two types are compatible when their shapes fit, whatever their names. Erased means the compiler removes types before the program runs, so nothing checks data at runtime unless you write code that does. A boundary is any place data enters from outside: a request body, a file, an environment variable, a message.
Evidence to hand in. A repository whose README opens with the problem and the targets above; one ADR (architecture decision record) per decision, each naming a rejected option; type tests and a test report; a one-page design doc; a diagram of how a contract becomes a handler, a client and a validator. Skeletons: Checkpoint 1 is two lists (must-not-compile and must-compile, one line each with the rule it shows) plus the lint output. Checkpoint 3 is the timing table and the before and after trace summaries. Checkpoint 4 is the API report, the ratchet chart (errors per week) and the policy page.
| Level | What you build and hand in |
|---|---|
| Fresher | Core scope: 10 endpoints, one schema library, the four checkpoints, ADRs 1 to 4. |
| Senior | Adds 60 endpoints, the compatibility check, the speed budget and a codemod, plus ADRs 5 and 6. |
| Staff | Adds written decisions with numbers: strictness policy, how much check time developers will accept, the compiler upgrade plan and its rollback. |
| Principal | Adds a strategy for many repositories (shared config, shared lint rules, an any budget), a review checklist other teams reuse, and a measured outcome. |
Do this at work. A solo lab is not promotion evidence. Take a real codebase with loose types, a slow type check or drift between two services, and run Checkpoint W on it. Start with a baseline: errors under strict, count of any, check time and the incidents caused by a type mismatch in the last quarter. Make one change. Measure again. A promotion committee accepts the real decision and who made it, the named stakeholder who relied on it, before and after numbers, and a result checked again three months later.
Solo version. With no real codebase, pick a named open-source JavaScript or TypeScript project of 20,000 lines or more, run the ratchet on one module, and ask a peer or mentor to review the steps and the diff. Replay a recorded set of requests instead of live traffic when you test the validator.
Laptop scale. The whole project runs on a laptop. Nothing needs cloud spend. A local registry (for example Verdaccio) stands in for a real one.
Honest sizing. A first discriminated union takes an hour. A contract kit with inference, validation and OpenAPI takes an experienced engineer a week or more, so Phase 2 has four weeks and the fresher gets an extra one. Type-level code is the slowest to debug, so keep the type tests small and run them often.
Worked reference: what a "3 Proven" hand-in for Checkpoint 2 looks like
The results are illustrative. Run your own faults and hand in your own output.
| Seeded fault | Hand-written types plus a hand-written validator | Schema first (types inferred from the schema) |
|---|---|---|
Server returns total as a string | Compiles (the validator is not tied to the type) | Compile error at the handler |
Client sends custmerId | Compile error | Compile error |
Field note added to the type, not the validator | Compiles; the field is silently dropped | Both change together: one definition |
Payload arrives without total | 400, if someone remembered the check | 400 with a typed error body on every route |
ADR-3 excerpt: Derive the types from the schemas, and keep the schema as the source of truth. Types are erased, so a runtime check needs a runtime object. Writing the type and the validator separately gives two sources that drift, as the table shows. Rejected: generating validators from types at build time, because it adds a build step and handles generics and branded types poorly. Rejected: runtime checks only, because the client loses compile-time safety. Consequences: the kit depends on one schema library, so we depend on a shared schema interface (Standard Schema) and keep the library swappable. Revisit if schema inference becomes the slowest type in the Checkpoint 3 trace.