Type Guards & Narrowing

Also Known As

TL;DR

Explanation

TypeScript narrows types inside conditional branches automatically (typeof, instanceof, truthiness). Custom type guards use the is predicate: function isString(v: unknown): v is string { return typeof v === 'string'; }. Discriminated union narrowing works via a shared literal field (kind, type). The in operator narrows to types that have a given property. Exhaustiveness checks with never ensure all cases are handled. Common pattern: unknown input → series of type guards → fully typed value. Assertion functions (asserts v is T) throw instead of returning false.

Diagram

flowchart TD
    INPUT["input: string | number | unknown"]
    CHECK{Type guard check}
    INPUT --> CHECK
    CHECK -- typeof === string --> STR[Narrowed: string<br/>toUpperCase safe]
    CHECK -- typeof === number --> NUM[Narrowed: number<br/>toFixed safe]
    CHECK -- is predicate --> CUSTOM[Custom narrowing<br/>v is MyType]
    CHECK -- discriminant field --> DISC[kind === circle<br/>radius available]
    style STR fill:#238636,color:#fff
    style NUM fill:#238636,color:#fff

Watch Out

Common Misconception

Why It Matters

Common Mistakes

• Using as Type (type assertion) instead of a proper type guard — assertions bypass the compiler and lie about the type.
• Forgetting the is predicate return type — without it, TypeScript doesn't narrow in the calling scope.
• Checking instanceof on plain objects — use in or a discriminant field instead.
• Not handling the never case in exhaustive switches — add a default branch that assigns to never to catch missing cases.

Avoid When

• Avoid writing type guards for every minor check — inline typeof/instanceof is fine for simple cases.

When To Use

• Processing unknown or any input from external sources (API responses, JSON.parse, user input).
• Working with union types that need different handling per variant.
• Building exhaustive switch statements over discriminated unions.

Code Examples

function processInput(input: string | number) {
    // Unsafe cast — no runtime check
    const s = input as string;
    console.log(s.toUpperCase()); // Crashes if input is number
}

// User-defined type guard
function isString(v: unknown): v is string {
    return typeof v === 'string';
}

function processInput(input: string | number) {
    if (isString(input)) {
        console.log(input.toUpperCase()); // input is string here
    } else {
        console.log(input.toFixed(2));    // input is number here
    }
}

// Discriminated union narrowing
type Shape = { kind: 'circle'; radius: number } | { kind: 'rect'; width: number; height: number };
function area(s: Shape): number {
    switch (s.kind) {
        case 'circle': return Math.PI * s.radius ** 2;
        case 'rect':   return s.width * s.height;
        default: const _exhaustive: never = s; return _exhaustive;
    }
}

References

• ↗ https://www.typescriptlang.org/docs/handbook/2/narrowing.html

Tags

Related Terms