Skip to content
FEE
Frontend Engineering Essentials
Mid Level

Narrowing & Type Guards ​

Narrowing is TypeScript's mechanism for refining a value's type within a conditional branch. When code checks typeof value === 'string', TypeScript knows that within the true branch, value is string. This check — and similar checks using instanceof, the in operator, equality comparisons, and truthiness — are called type guards. TypeScript understands them without explicit annotation and narrows automatically.

The practical consequence is that most narrowing in well-written TypeScript requires no custom code — the built-in guards cover the common cases. Custom type guards using the predicate syntax (value is T) fill the remaining gap: when a narrowing condition is complex enough to extract into a function, the predicate return type tells TypeScript that the function's truthy return narrows the parameter.

Discriminated unions are the most powerful narrowing pattern because they combine type safety with exhaustiveness: a union where each member has a literal type field can be switched on, and TypeScript narrows each branch to the specific member. Adding a new union member without updating all switch statements becomes a compile error rather than a silent runtime fallthrough.

Design Thinking ​

Built-in narrowing: the common cases ​

typeof narrows primitives; instanceof narrows class instances; in narrows objects with a specific property; truthiness narrows away null | undefined; equality (=== 'value') narrows to literal types. TypeScript tracks narrowing through control flow, including across assignments, loops, and early returns.

Discriminated unions: the most powerful pattern ​

A union where each member has a literal type or kind field with a unique value is a discriminated union. Switching on type narrows each branch to the specific member. This is more readable and more maintainable than instanceof chains, and the members are plain objects that can be serialized, deserialized, and pattern-matched consistently.

When custom type guards are necessary ​

When a narrowing condition is complex enough to extract into a helper function, the return type value is T tells TypeScript that a true return means the parameter is T. Without the predicate syntax, the extracted function returns boolean and the narrowing is lost at the call site — the code runs correctly but TypeScript no longer knows the narrowed type in the truthy branch.

Best Practices ​

MUST use discriminated unions with a literal type or kind field for sum types rather than optional fields or instanceof checks. Discriminated unions enable exhaustiveness checking, produce clean narrowing in switch statements without custom guards, and are serializable without prototype information. Optional fields produce ambiguous narrowing — the presence of a field does not indicate which variant the value represents. instanceof creates coupling to constructors and breaks across serialization boundaries.

MUST write type predicates (value is T) as the return type of custom guard functions rather than returning boolean. A guard function that returns boolean does not propagate the narrowing to the call site — TypeScript sees only a boolean, not a narrowing assertion. The predicate syntax function isUser(value: unknown): value is User tells TypeScript that a true return means the parameter satisfies the User type, and narrowing flows correctly into the truthy branch at every call site.

SHOULD prefer in operator narrowing and discriminated unions over instanceof narrowing for plain data objects. instanceof creates coupling to a specific constructor function, breaks across iframe boundaries where two instances of the same class have different constructor references, and does not work for objects created by JSON deserialization since JSON objects never carry class prototypes. Discriminated unions and in narrowing work on plain objects regardless of origin.

SHOULD use assertion functions (asserts condition) to encode preconditions that must hold at a specific point in the code. An assertion function that throws on a falsy condition tells TypeScript that after the call, the condition is narrowed to true. This is useful for guarding initialization values and for expressing invariants that TypeScript cannot infer from control flow alone — for example, asserting that an optional field has been populated before a section of code that requires it.

  • FEE-1701 — Type System Fundamentals & Type Inference
  • FEE-1703 — Utility Types & Type Manipulation
  • FEE-1708 — Runtime Validation & Schema Libraries

References ​