code-review-typescript

TypeScript Code Review Patterns

Stack-specific rules loaded by dh:code-reviewer when tsconfig.json, *.ts, or *.tsx files are detected.

Strict Mode

• tsconfig.json must enable strict: true — this covers noImplicitAny, strictNullChecks, strictFunctionTypes, and others
• exactOptionalPropertyTypes: true is required in new projects — prevents undefined from being assigned to optional properties
• noUncheckedIndexedAccess: true is required when indexing arrays or records — prevents silent undefined propagation
• Any @ts-ignore comment without an accompanying explanation comment is a blocking finding
• @ts-expect-error is preferred over @ts-ignore — it fails if the error goes away

Type Safety

• any type without an explanatory comment is a blocking finding
• Type assertions (as SomeType) without runtime validation at the same boundary are a blocking finding
• unknown is the correct type for values from external sources — validate before narrowing, not after
• object as a type is not meaningful — use Record<string, unknown> or a specific interface
• Non-null assertions (value!) without a comment explaining why null is impossible are a blocking finding

Discriminated Unions Over Booleans

• Multiple boolean flags encoding state are a blocking finding — model as a discriminated union instead
• State machine logic with isLoading, isError, isSuccess as separate booleans allows impossible combinations

// WRONG: boolean flags allow impossible states
interface State {
  isLoading: boolean;
  isError: boolean;
  data: User | null;
}

// RIGHT: discriminated union — impossible states are unrepresentable
type State =
  | { status: "loading" }
  | { status: "error"; error: Error }
  | { status: "success"; data: User };

Branded Types

• Domain primitives that are structurally identical but semantically distinct must use branded types to prevent mix-ups
• UserId and OrderId are both string at runtime — without brands, they are interchangeable to the type checker