TypeScript Type Narrowing: How Control Flow Analysis Works

Type narrowing is TypeScript working out a more specific type for a value at a particular point in the code, based on the checks the code has already made. A string | number parameter becomes string inside if (typeof x === "string") and number in the else.

function pad(value: string | number): string {
  if (typeof value === "number") {
    // value: number
    return value.toFixed(2).padStart(8);
  }
  // value: string (number was handled above)
  return value.padStart(8);
}

console.log(`[${pad(3.14159)}]`); // [    3.14]
console.log(`[${pad("abc")}]`);   // [     abc]

Calling value.toFixed(2) before the check would be a compile error, because toFixed does not exist on string. The check is ordinary JavaScript and runs at run time; the narrowing is the compiler reading it and adjusting the type. Nothing extra is emitted.

Control Flow Analysis

TypeScript follows every path through a function: if/else, early return and throw, switch, loops, and the short-circuit operators &&, ||, ?? and ?:. At each point, a variable's type is whatever is still possible there.

function firstWord(text: string | null | undefined): string {
  if (text == null) return "(none)";   // removes null and undefined
  // text: string
  const trimmed = text.trim();
  const space = trimmed.indexOf(" ");
  return space === -1 ? trimmed : trimmed.slice(0, space);
}

function lengthOrZero(list?: string[]): number {
  return list && list.length > 0 ? list.length : 0; // list: string[] after &&
}

console.log(firstWord("  hello typed world")); // hello
console.log(firstWord(undefined));             // (none)
console.log(lengthOrZero(["a", "b"]), lengthOrZero()); // 2 0

The early-return style ("guard clauses") is the most readable way to narrow: handle the odd cases first and the rest of the function works with the clean type.

Every Way to Narrow

The last three are covered on the type guards and discriminated unions pages. The rest are below.

Truthiness Narrowing

if (x) removes null and undefined (and false, 0, "" literal types). It is short, and it has one classic trap: 0 and "" are falsy, so valid values get treated as missing.

function describeCount(count: number | undefined): string {
  if (!count) return "unknown";   // bug: 0 is falsy too
  return `${count} items`;
}

function describeCountFixed(count: number | undefined): string {
  if (count === undefined) return "unknown";
  return `${count} items`;
}

console.log(describeCount(0));      // unknown
console.log(describeCountFixed(0)); // 0 items

For numbers and strings, compare with undefined or null explicitly (or use ??). Truthiness is fine for objects, arrays and functions, which are never falsy.

Equality Narrowing

===, !==, == and != narrow both sides. Comparing with a literal narrows to that literal; == null (loose equality) matches both null and undefined in one check, and is the one place loose equality is idiomatic.

type Status = "active" | "paused" | "deleted";

function label(status: Status, note: string | null | undefined): string {
  if (status === "deleted") return "gone";
  // status: "active" | "paused"
  const suffix = note != null ? ` (${note})` : ""; // note: string in the true branch
  return status.toUpperCase() + suffix;
}

console.log(label("paused", "until Monday")); // PAUSED (until Monday)
console.log(label("active", undefined));      // ACTIVE
console.log(label("deleted", null));          // gone

Comparing two variables narrows both to what they could have in common: if a: string | number and b: string | boolean pass a === b, both are string inside the if.

The in Operator

"key" in obj narrows a union of object types to the members that have (or may have) that property.

type Fish = { name: string; swim: () => string };
type Bird = { name: string; fly: () => string };

function move(pet: Fish | Bird): string {
  if ("swim" in pet) {
    return pet.swim(); // pet: Fish
  }
  return pet.fly();    // pet: Bird
}

console.log(move({ name: "Nemo", swim: () => "splash" })); // splash
console.log(move({ name: "Tweety", fly: () => "flap" }));  // flap

in also works on unknown once you know it is an object: after typeof v === "object" && v !== null && "id" in v, TypeScript knows v has an id property of type unknown. For unions you design yourself, a shared tag property (kind: "fish") is clearer than probing for methods: that pattern is called a discriminated union.

Assignment Narrowing

A variable has a declared type, and a narrowed type that follows its assignments. Assigning a value narrows it to that value's type, up to the declared type.

let id: string | number = "a-17";
console.log(id.toUpperCase()); // id: string here, so string methods work

id = 42;
console.log(id.toFixed(1));    // id: number now

// id = true; would be an error: the declared type is still string | number

Where Narrowing Is Lost

Narrowing is local and conservative. A few situations reset it:

• A different expression. Checking obj.name narrows obj.name (and obj["name"]), but not obj[key] when key is a string variable rather than a literal, and not a copy made before the check.
• Callbacks and reassignment. Inside a callback, a narrowed let keeps its narrowing only if it is not assigned again after the callback is created. A const or a parameter that is never reassigned stays narrowed.
• Checks hidden in helpers. A function isString(x: unknown): boolean tells the compiler nothing. Give it a type predicate return type, x is string, and calls to it narrow like typeof does.

// This does not compile: x is reassigned after the callback, so the callback loses the narrowing.
function run(flag: boolean): void {
  let x: string | undefined = flag ? "ready" : undefined;
  if (x !== undefined) {
    [1, 2].forEach(() => console.log(x.length));
  }
  x = undefined;
}

run(true);

The compiler reports index.ts(5,38): error TS18048: 'x' is possibly 'undefined'. The callback could run later, after x = undefined. Delete that last assignment (or copy the value into a const inside the if) and it compiles and prints 5 twice.

A helper that returns boolean can be fixed by declaring what it proves. That is what a type guard is:

function isString(value: unknown): value is string {
  return typeof value === "string";
}

Since TypeScript 5.5 the compiler infers such predicates for simple arrow functions, which is why list.filter((x) => x !== undefined) now returns an array without undefined.