typescript

TypeScript

House conventions for TypeScript 5+. Apply them to code you are writing or changing — don't refactor untouched files to match unless asked.

Conventions

• Model the domain in types, not in checks. Branded types (type UserId = string & { readonly __brand: 'UserId' }) and discriminated unions push errors to compile time, where they cost nothing. A runtime guard catches the same bug in production.
• Discriminated unions for anything with states — request lifecycles, form state, parse results. The compiler then forces every state to be handled, so a new variant surfaces as an error rather than a silent fallthrough.
• satisfies over as. satisfies validates against a type while keeping the narrow inferred literal; as throws the check away. Reach for as only when you know something the compiler cannot, and say why in a comment.
• Const objects over enum. as const objects are plain values with no emit and no nominal-typing surprises; enum generates runtime code and const enum breaks under isolatedModules.
• any is a bug report. Use unknown and narrow. If any is genuinely unavoidable at a boundary, isolate it in one adapter function rather than letting it spread through call sites.
• Separate type-only imports (import type { … }). Bundlers erase them cleanly; mixed imports can keep a runtime dependency alive that you meant to drop.
• Let inference work. Annotate exported/public signatures and let everything internal infer — over-annotation is noise that drifts from the real type.
• Ship .d.ts for anything consumed as a library (declaration: true). Without it, consumers fall back to any and your type work stops at the package boundary.
• Monorepos: project references + composite. Incremental builds only rebuild what changed; a single flat tsconfig recompiles the world on every edit.

The two idioms worth showing

Exhaustiveness only actually holds if you force it. A switch over a union compiles fine when a new variant appears — assertNever is what turns that into a build error at every site that needed updating:

function assertNever(x: never): never {
  throw new Error(

A brand is only worth having if the sole way to obtain one is a function that validates:

The as inside the constructor is the one legitimate use — it's the boundary where validation converts an unverified value into a verified one. Casting to Email anywhere else defeats the whole type.

tsconfig baseline

strict: true does not enable everything worth having. Add these — each one catches a class of bug the default set misses:

noUncheckedIndexedAccess is the highest-value one and the most disruptive to adopt: it makes arr[i] return T | undefined, which is the truth. Turn it on for new projects; for existing ones, expect a migration.

Module resolution: NodeNext when Node runs the output, bundler when a bundler does.