Unions and narrowing

A union says a value is one of several types.

type Id = string | number;

Until you prove which one it is, you may only do what both allow. That is not the compiler being awkward: at runtime the value really could be either.

Narrowing

A check the compiler understands narrows the type inside that branch.

function label(id: string | number): string {
  if (typeof id === "string") return id.toUpperCase();  // string here
  return id.toFixed(0);                                 // number here
}

typeof, instanceof, in, Array.isArray and a plain comparison against a literal all narrow.

Discriminated unions

The pattern worth knowing by name. Give every member a shared literal field, and checking that field narrows the whole object:

type Result =
  | { status: "ok"; value: number }
  | { status: "failed"; error: string };

function show(r: Result): string {
  if (r.status === "ok") return `got ${r.value}`;
  return `failed: ${r.error}`;   // r.value is not even offered here
}

This is how you model a thing that either worked or did not, without an optional field that is sometimes set and sometimes not.

Try it

Catching the case you forgot

Assigning the narrowed value to never at the end makes the compiler fail when someone adds a new member to the union and forgets this switch:

default: {
  const impossible: never = r;
  throw new Error(`unhandled: ${impossible}`);
}

Add { status: "pending" } to the union and that line stops compiling. That is the compiler finding, at build time, every place a new case needs handling.