Narrowing & Discriminated Unions

The plain-language idea

A value typed string | number can't be treated as either until TypeScript can prove which one it actually is in that branch of code. That proof comes from narrowing — runtime checks like typeof, instanceof, in, or a truthy check, each of which TypeScript's control-flow analysis understands and uses to shrink the type within that branch.

A discriminated union is the most powerful version of this: a union of object shapes that all share one common property with a distinct literal value (the "discriminant" or "tag"). Checking that one property narrows the entire object.

See it in a real thing: narrowing an API response

type ApiResponse =
  | { status: "success"; data: string }
  | { status: "error"; message: string };

function handle(res: ApiResponse) {
  if (res.status === "success") {
    console.log(res.data);      // ✅ TS knows this branch is the success shape
  } else {
    console.log(res.message);   // ✅ narrowed to the error shape here
  }
}

Checking res.status doesn't just narrow status itself — it narrows res's entire type, which is why res.data becomes accessible in one branch and res.message in the other, with no manual casting anywhere.

A discriminated union: two object shapes sharing one common property, status, with different literal values.

BackNext

What people usually miss

Watch out

• Narrowing doesn't survive into a later closure. If you narrow res.status === "success" and then reference res inside a setTimeout callback, TypeScript can't prove res hasn't changed by the time that callback runs — the narrowing doesn't carry through into a deferred function.
• The in operator narrows without a dedicated tag field. if ("data" in res) narrows based on which property actually exists, useful when the union wasn't designed with an explicit discriminant.
• Exhaustiveness checking is a compile-time safety net for a very real bug: someone adds a new variant to a union months later, and every existing switch handling that union silently misses it — without a never check, that's a runtime gap; with one, it's a build failure pointing at the exact spot.
• Not every union is a discriminated union. string | number narrows fine with typeof, but there's no shared "tag" property — the discriminated-union pattern specifically applies to unions of object shapes with a common literal property.

Why this matters in interviews

Modeling state as a discriminated union ({status: "loading"} | {status: "success", data} | {status: "error", error}) instead of a pile of optional/possibly-undefined fields is one of the clearest signals of TypeScript fluency — it makes invalid states (like data and error both being set) impossible to represent at all, not just unlikely.