Roadmaps / TypeScript / Phase 4
Phase 4 of 4 · Study weeks 13-16
Large codebases, libraries and governance
This phase makes the last checkpoint possible: types other teams can rely on, a strictness plan that ships in steps and a policy people follow.
Topics every week
- Week 138 h
- A strictness ratchet for a large codebase
- Type-aware lint rules (
no-floating-promises,no-misused-promises) - An
anybudget in CI - JSDoc-typed JavaScript with
checkJs
Hand inA ratchet plan and the first week's error count falling
- Week 148 h
- Library type design: overloads against generics
- The public API surface
- An API report in CI
- Semver for types
Hand inAn API report and a seeded breaking change that fails CI
- Week 158 h
- Codemods with
ts-morphorjscodeshift - Converting JavaScript to TypeScript
- Declaration files for untyped packages
- Reviewing type-heavy changes
Hand inA codemod that migrates 50 call sites and is safe to run twice
- Codemods with
- Week 168 h
- A type-safety policy and review checklist
- Governance: ownership, shared config, exceptions
- Knowing when a type is too clever
- The upgrade policy
Hand inCheckpoint 4, the policy page and the decision memo
Practice projects
- Practice 1, the ratchet (Week 13): pick a module of 20,000 lines or more and plan the order of fixes. Done when: the error count falls on a weekly chart, and CI blocks any rise.
- Practice 2, the API surface (Week 14): write a small library with one overloaded function and one generic function. Done when: a checked-in API report shows both, and a seeded breaking change fails CI.
- Practice 3, the codemod (Week 15): write a codemod for one repeated pattern across 50 or more call sites. Done when: running it twice changes nothing the second time, and you reviewed a sample of 10 changes by hand.
- Optional, declarations for an untyped package: write
.d.tsfiles for a small untyped package. Done when: type tests cover every exported function.
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 |
|---|---|---|
| sindresorhus/type-fest | Public type API design, docs and tests | 14 |
| microsoft/rushstack | API Extractor: how an API report is produced and checked | 14 |
| dsherret/ts-morph | Reading and rewriting TypeScript code from a script | 15 |
| facebook/jscodeshift | A codemod runner and its testing helpers | 15 |
| DefinitelyTyped/DefinitelyTyped | How community type packages are written and tested | 15 |
Milestone checkpoint
Run Checkpoint 4. Publish the kit to a local registry with type tests and an API report, then narrow a parameter type and watch CI fail. Run the strictness ratchet on your chosen module in ordered steps. Turn on the two type-aware lint rules and the any budget. Write the one-page policy: which strict flags are on, how any and assertions are allowed and counted, who reviews exceptions, and how an upgrade of the compiler is decided. Hand in the API report, the ratchet chart, the policy, ADR-6 (what counts as a breaking change) and the decision memo.
Check yourself
Answer each question in your head first, then open it to check.
Why ratchet strictness in steps instead of turning
stricton at once?Thousands of errors block every merge. A ratchet fixes one module at a time, never lets the count rise and keeps feature work moving.What does
no-floating-promisescatch?A promise that is created and neither awaited nor handled, so a failure is lost as an unhandled rejection.When do you write overloads, and when a generic?
Overloads when the return type depends on which kind of argument you pass, listed most specific first. A generic when one rule relates input and output for every case. Overloads give worse error messages.Name three type-only changes that break callers.
Narrowing a parameter type, widening a return type, making an optional property required, and renaming or removing an export. Compiler upgrades can also change what type-checks, so type changes need a policy, not only semver.When is
anyacceptable?At a narrow, commented boundary where the shape is checked straight away (for example wrapping an untyped library), and only inside theanybudget. Preferunknown.