Mastering TypeScript Type Narrowing: From Guards to Control Flow Analysis

1. Type Narrowing and Type Guards

In business development we often encounter a situation where a request can succeed or fail, resulting in a value that may have multiple possible shapes. We want a single function to handle both cases.

interface SuccessResult {
  data: unknown;
  code: number;
}

interface FailureResult {
  error: unknown;
  code: number;
}

function handler(input: SuccessResult | FailureResult) {
  return new Promise((resolve, reject) => {
    if (success) {
      resolve(input.data);
    } else {
      reject(input.error);
    }
  });
}

Using a simple if...else check works, but the compiler still sees input as SuccessResult | FailureResult inside the branches, so accessing data or error triggers an error.

We can replace the helper function with a type‑guard that uses the is keyword:

function isSuccess(res: SuccessResult | FailureResult): res is SuccessResult {
  return "data" in res;
}

Or inline the check:

function handler(input: SuccessResult | FailureResult) {
  return new Promise((resolve, reject) => {
    if ("data" in input) {
      resolve(input.data);
    } else {
      reject(input.error);
    }
  });
}

Both approaches are examples of "type guards"; the is keyword explicitly provides the narrowed type to the compiler.

The type SuccessResult | FailureResult is a discriminated (or tagged) union. See the articles “The Other Side of TypeScript: Type Programming” and “TypeScript 4.6 beta Release” for more details.

Another example shows multi‑branch narrowing with never for exhaustive checks:

const strOrNumOrBool: string | number | boolean = false;

if (typeof strOrNumOrBool === "string") {
  console.log("str!");
} else if (typeof strOrNumOrBool === "number") {
  console.log("num!");
} else if (typeof strOrNumOrBool === "boolean") {
  console.log("bool!");
} else {
  const _exhaustiveCheck: never = strOrNumOrBool;
  throw new Error(`Unknown input type: ${_exhaustiveCheck}`);
}

Each if narrows the union, and the final else block proves that all cases have been handled.

2. Evolution of Type‑Based Control Flow Analysis

TypeScript’s control‑flow analysis (CFA) originally dealt only with code flow. Since version 1.8 it gained improvements such as unreachable code detection. Later versions added type‑based CFA, which narrows union types based on runtime checks.

TypeScript 2.0: Introduction

Version 2.0 introduced CFA for variables and parameters, enabling narrowing of discriminated unions.

TypeScript 3.2: Destructuring and Rest

Support for type inference of { foo, ...rest } patterns and generic contexts was added.

TypeScript 3.7: asserts and never Functions

The asserts keyword lets a function act as a type guard that throws on failure. Example:

function assert(condition: any, msg?: string): asserts condition {
  if (!condition) {
    throw new AssertionError(msg);
  }
}

function assertIsString(val: any): asserts val is string {
  if (typeof val !== "string") {
    throw new AssertionError("Not a string!");
  }
}

Functions returning never also participate in CFA, allowing exhaustive checks after a call that always throws.

TypeScript 3.9: Intersection of Discriminated Unions

When intersecting two discriminated unions, the compiler now produces never for impossible members, catching errors earlier.

TypeScript 4.0–4.6: Incremental Enhancements

Subsequent releases added CFA for class properties, generic constraints, independent const‑declared guards, destructured guards, template‑string literal types, and tuple‑based discriminated unions. Highlights include:

Class property types are inferred from constructor assignments.

Generic parameters with constraints are used as the apparent type during CFA.

Const‑declared guard variables now narrow types.

Destructuring a discriminated union and checking the discriminant narrows the other fields.

Template‑string literal types can be used in guards (e.g., `${string}Success`).

Tuple‑based discriminated unions allow precise narrowing of callback arguments.

3. Miscellaneous & Summary

From its inception, TypeScript’s control‑flow analysis has steadily become more precise, offering developers stronger guarantees and better editor support. Each minor version after 4.3 adds refinements that bring the type system closer to the realities of real‑world code, making exhaustive checking and type safety increasingly practical.