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.

Common mistakes

• Optional fields instead of a union. One shape with ok: boolean, value? and error? lets every combination through, including success with no value. Both calls in the example after this list compile and print nonsense.
• Losing the literal. let status = "ok" is inferred as string, so an object built from it no longer matches { status: "ok"; ... }. The same happens to const r = { status: "ok", value: 1 } stored before it is used: its property widens to string. Use const for the variable, annotate the object with the union, or add as const.
• Reading a field only one member has. On a Result, is a compile error until you have narrowed to the member. Narrow on the discriminant (or with ) rather than casting.

What interviewers ask

• What is a discriminated union, and why prefer it to optional fields? A shared literal field on every member; checking it narrows to exactly one shape, so impossible states cannot even be written down.
• How do you make the compiler find every switch you forgot to update? Assign the value to never (or pass it to an assertNever helper) in the default branch; a new member then fails to compile there.
• Union or intersection? A | B is one or the other, and you may only use what both have until you narrow; A & B has everything from both.