TypeScript Type Narrowing: From Basic to Expert

ction returns. The following techniques form the foundation of expert-level type narrowing:

typeof Guard

Primitive type checks leverage JavaScript's typeof operator. TypeScript recognizes this pattern and automatically narrows the union within the conditional block.

function padLeft(value: string, padding: string | number) {
  if (typeof padding === 'number') return ' '.repeat(padding) + value;
  return padding + value; // narrowed to string
}

Compiler Behavior: The typeof check triggers control flow analysis. Inside the if block, padding is narrowed to number. In the fallback branch, TypeScript infers the remaining union member (string).

Custom Type Guards

When typeof or instanceof cannot express domain-specific logic, type predicates (parameter is Type) bridge runtime validation and compile-time narrowing.

function isAdmin(user: Admin | User): user is Admin {
  return user.role === 'admin';
}

Compiler Behavior: The user is Admin return type signals to the compiler that a true result guarantees user conforms to Admin. Subsequent usage in conditional branches automatically narrows the type without explicit casting.

Discriminated Unions

Structural unions with a shared literal property (discriminant) enable exhaustive pattern matching. The compiler tracks the discriminant value to narrow the entire object shape.

type Result<T> = { success: true; data: T } | { success: false; error: string };

Compiler Behavior: Accessing result.success narrows the union. When success === true, data is guaranteed to exist and error is removed from the type. This pattern scales to complex state machines and API response handlers.

Pitfall Guide

1. Type Predicate Misconfiguration: Returning boolean instead of parameter is Type breaks control flow analysis. The compiler treats the function as a generic boolean check, preventing automatic narrowing in calling scopes.
2. Narrowing Scope Leakage: TypeScript narrowing is synchronous and block-scoped. Passing a narrowed variable to an async callback, promise chain, or external function resets the type to the original union. Always re-narrow at the consumption boundary.
3. Missing Exhaustiveness Enforcement: Failing to use the never type in switch or conditional branches allows new union members to be silently ignored. Implement const _exhaustiveCheck: never = value; in default branches to force compile-time failures on unhandled cases.
4. Over-Reliance on typeof for Objects: typeof only returns "object", "function", or primitives for complex types. Using it for class instances or custom objects yields false negatives. Prefer instanceof for class hierarchies or custom type guards for interface discrimination.
5. Mutating Narrowed Variables: Reassigning a narrowed variable within the same scope invalidates the control flow analysis. TypeScript resets the type to the original union after mutation. Use immutable patterns or scoped constants to preserve narrowing state.
6. Ignoring unknown vs any in Guard Chains: Using any bypasses all narrowing checks. When handling untrusted payloads, start with unknown and apply sequential guards. This forces explicit narrowing at each step, preventing accidental type leakage.

Deliverables

• Blueprint: Type Narrowing Architecture Map – Visual decision tree for selecting typeof, instanceof, custom guards, or discriminated unions based on payload complexity and performance constraints.
• Checklist: Pre-merge Type Safety Validation – 12-point audit covering exhaustiveness checks, predicate return types, async boundary re-narrowing, and never type enforcement.
• Configuration Templates:
  • tsconfig.json strict mode flags (strictNullChecks, strictFunctionTypes, noUncheckedIndexedAccess)
  • ESLint ruleset: @typescript-eslint/strict-boolean-expressions, @typescript-eslint/no-unnecessary-condition, @typescript-eslint/consistent-type-definitions
  • VS Code workspace settings for enhanced type inference diagnostics and hover preview optimization