What is a discriminated union?

A discriminated union is a union of object types that share a literal discriminant property. Because the property has a different literal value in each member, checking it tells the compiler exactly which shape is present. The rest of the object's fields are then available without casts.

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

function render(state: State): string {
  switch (state.status) {
    case "success":
      return state.data.join(", ");
    case "error":
      return state.message;
    default:
      return state.status;
  }
}

Why the discriminant matters

• The discriminant must be a literal type, not a broad string
• Each member can carry fields that only make sense in that state
• Checking the discriminant narrows the entire object
• The pattern works with switch, if and user-defined guards
• It makes impossible combinations unrepresentable

A common mistake is making variant fields optional on a single interface. That allows states like loading with data or success without data, which the type cannot prevent. Separate members with a literal discriminant model the real states more accurately.