Typescript Strict

Deep TypeScript strictness workflow—incremental enablement, compiler flags, typing boundaries, narrowing, generics, utility types, and safe refactors. Use when adopting strict mode, reducing any, or hardening large TS codebases.

TypeScript Strict Mode (Deep Workflow)

Strictness is a gradient, not a single switch. The goal is fewer runtime surprises without blocking delivery—via incremental migration and clear typing boundaries at IO edges.

When to Offer This Workflow

Trigger conditions:

• Enabling strict, strictNullChecks, noImplicitAny, or noUncheckedIndexedAccess
• Legacy codebase full of any and @ts-ignore
• Runtime bugs that types would have caught (undefined, wrong shapes)
• Library authoring needing accurate .d.ts exports

Initial offer:

Use six stages: (1) baseline & goals, (2) compiler flags roadmap, (3) boundary typing, (4) narrowing & exhaustiveness, (5) generics & patterns, (6) verify & guardrails). Confirm TS version, build tool (tsc, esbuild, etc.), and monorepo layout.

---

Stage 1: Baseline & Goals

Goal: Know current pain and target strictness with metrics.

Actions

• Capture tsc --noEmit error count and top files by errors
• Identify critical packages vs leaf apps for sequencing
• Define non-goals (e.g., “no perfect types for untyped third-party JSON this quarter”)

Exit condition: Baseline error count + priority directories.

---

Stage 2: Compiler Flags Roadmap

Goal: Enable flags incrementally—fix clusters, not the whole repo at once.

Typical order (adapt)

1. strictNullChecks (often highest value)
2. noImplicitAny on new files + ratchet old
3. strictFunctionTypes, strictBindCallApply
4. noUncheckedIndexedAccess (verbose—plan for undefined unions)
5. exactOptionalPropertyTypes (sharp edges—later)

Techniques

• // @ts-expect-error with ticket over blind @ts-ignore
• Path-specific tsconfig extends for stricter packages
• CI gate: no new any in changed lines (eslint @typescript-eslint/no-explicit-any)

Exit condition: Flag timeline with owners per package.

---

Stage 3: Boundary Typing (IO Edges)

Goal: Validate external data once; internal code trusts narrowed types.

Patterns

• zod / io-ts / valibot for runtime parse at API boundary
• satisfies for config objects—keeps literal types
• Avoid casting from unknown without validation

APIs

• Generated types from OpenAPI/graphql-codegen when possible
• Branded types for IDs (type UserId = string & { __brand: 'UserId' }) to prevent mix-ups

Exit condition: New IO code has parse → typed pipeline documented.

---

Stage 4: Narrowing & Exhaustiveness

Goal: Control flow analysis works for you—discriminated unions, never checks.

Practices

• Discriminated unions for states: { status: 'loading' } | { status: 'ok', data: T }
• switch with assertNever(x) for compile-time exhaustiveness
• Optional chaining vs explicit undefined handling—be consistent in module

Nullability

• Prefer undefined vs null one convention per codebase section

Exit condition: Representative modules refactored with fewer optional footguns.

---

Stage 5: Generics & Patterns

Goal: Reuse without any soup—constraints and defaults.

Guidance

• extends constraints; avoid unconstrained generics unless truly generic
• Conditional types sparingly—readability over cleverness in app code
• ReturnType / Parameters for inference glue
• Avoid mutable array inference surprises—explicit element types when needed

Performance

• Huge mapped types can slow tsc—split types or simplify

Exit condition: Style guide section for generics in shared libraries.

---

Stage 6: Verify & Guardrails

Goal: Strictness sticks—regressions caught in CI.

CI

• tsc --noEmit required green for affected projects
• Type-aware ESLint rules; pre-commit optional
• dtslint or tsd for library typings tests when authoring packages

Refactor safety

• Small PRs per module; runtime tests still required—types don’t replace tests

---

Final Review Checklist

• Baseline metrics and roadmap for flags
• IO boundaries validated with schemas or codegen
• Discriminated unions / exhaustiveness for key state machines
• Generics style documented for shared code
• CI enforces typecheck on merge

Tips for Effective Guidance

• Prefer unknown over any—forces narrowing at use site.
• When user fights noUncheckedIndexedAccess, show helper getters or Record patterns.
• Monorepo: align TypeScript version across packages—version skew causes phantom errors.

Handling Deviations

• AllowJS mixed codebase: typed wrappers for critical paths first.
• Third-party untyped libs: local d.ts or wrapper module with narrow exports.