Lesson 13 of 80

Discriminated Unions

Q: Model an API response as loading/success/error using a discriminated union, and explain why this is better than one object with optional fields.

A strong answer covers: A union of object shapes sharing a common literal-typed discriminant field (e.g. status); Checking the discriminant narrows the whole type to the matching shape, giving safe access to that shape's specific fields; Prevents invalid states (both data and message set, or neither) that an all-optional-fields object would allow.

A union of object shapes that all share one common literal-typed field — checking that one field is enough for the compiler to know everything else about the shape, no type guard needed.

13 min read

Check your understanding

Every option explains itself — why the right one is right, and why each wrong one is wrong. Miss one and it comes back later on a spaced-repetition schedule.

Question 1 of 2

Why must the discriminant field (like `status`) be a literal type rather than plain `string` for this narrowing to work?

Without a literal type, there's no specific value for TypeScript to match against a particular union memberPlain string fields cause a compile error inside a union typeIt doesn't actually matter — narrowing works identically either way

Stuck? Ask the AI tutor

Hints without spoilers, and a plain explanation of why a wrong answer was wrong — answered only from this lesson. Free account, no card.

Interview questions on Discriminated Unions

What interviewers actually ask about this, and what a strong answer has to cover.

Model an API response as loading/success/error using a discriminated union, and explain why this is better than one object with optional fields.

A strong answer covers

A union of object shapes sharing a common literal-typed discriminant field (e.g. status)
Checking the discriminant narrows the whole type to the matching shape, giving safe access to that shape's specific fields
Prevents invalid states (both data and message set, or neither) that an all-optional-fields object would allow

Likely follow-ups

How would you add exhaustiveness checking so the compiler errors if a new state is added but not handled?
Why does the discriminant field need to be a literal type rather than plain string?
Can a discriminated union have more than one discriminant field?

Practice these with the AI interviewer →

The plain-language idea

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

function render(state: State) {
  if (state.status === "success") {
    console.log(state.data);      // ✅ narrowed — TS knows this branch only has `data`
  }
  if (state.status === "error") {
    console.log(state.message);   // ✅ narrowed to the error shape
  }
}

The shared status field — called the discriminant — is a literal type in every branch of the union. Checking state.status === "success" doesn't just compare a string; it narrows state's entire type down to exactly the union member with status: "success", so TypeScript now knows data exists (and message doesn't).

Discriminated unions: one check, whole type narrowedStep 1 of 4

State could be any of three shapes: loading, success{data}, or error{message}.

What people usually miss

Watch out

The discriminant must be a literal type, not a general one. If status were typed as plain string instead of the literal "loading" | "success" | "error", checking state.status === "success" wouldn't narrow anything — TypeScript needs the literal to match a specific union member.
This pairs directly with never and exhaustiveness checking: a switch over every discriminant value, with a default branch that assigns state to a variable typed never, makes the compiler itself flag it as an error if a new state shape is ever added and a case is forgotten.
This is the practical, idiomatic replacement for one giant object with lots of optional fields. { status: string; data?: string; message?: string } lets you accidentally have both data and message set, or neither — a discriminated union makes the invalid combinations impossible to construct in the first place.

Why this matters in interviews

Modeling API response states (loading / success / error) is one of the most common real interview exercises, and reaching for a discriminated union instead of one sprawling optional-fields object is the single strongest signal of TypeScript fluency in that exercise.