Discriminated unions

Reading data that isn't there yet

A shop page asks a server for its products. While it waits, the page is loading. Then the request either succeeds, and the page has a list of products, or it fails, and the page has an error message. Here is a plain JavaScript function that counts the products:

function productCount(state) {
  return `${state.products.length} products`;
}

console.log(productCount({ status: "success", products: ["Tea", "Cake"] }));
console.log(productCount({ status: "error", message: "Network down" }));

Line 1 takes a state object. Line 2 reads state.products.length. Line 5 passes a successful state with two products and prints 2 products. Line 6 passes a failed state, which has a message and no products. So state.products is undefined, reading .length from it throws a TypeError, and the code stops. Nothing warned you before it ran.

In TypeScript you describe the three states as one union type: a type that can be one of several types, written with |, which you read as "or". Each state is an object type with its own fields:

1type ProductsState =2  | { status: "loading" }3  | { status: "success"; products: string[] }4  | { status: "error"; message: string };5 6function productCount(state: ProductsState) {7  return `${state.products.length} products`;8}9 10console.log(productCount({ status: "success", products: ["Tea", "Cake"] }));

Lines 1 to 4 make a type called ProductsState. A state is one of three objects. Each one has a status field, and in each, status has one exact value. In a type, "loading" in quotes means "only the text loading", not any string. A type that is one exact value is called a literal type (the Literal types lesson covers them). Line 3 says a successful state also has products, a list of strings, and line 4 says a failed one has a message.

Line 7 reads state.products, and TypeScript marks it on purpose: Property 'products' does not exist on type 'ProductsState'. That means "not every state has products". The message's second line names one that doesn't: { status: "loading"; }. Line 10 still prints 2 products when you run it, but TypeScript has seen the crash coming. Check the status first:

1type ProductsState =2  | { status: "loading" }3  | { status: "success"; products: string[] }4  | { status: "error"; message: string };5 6function productCount(state: ProductsState) {7  if (state.status === "success") {8    return `${state.products.length} products`;9    //        ^?10  }11  return "No products yet";12}13 14console.log(productCount({ status: "success", products: ["Tea", "Cake"] }));15console.log(productCount({ status: "error", message: "Network down" }));

Line 7 asks whether state.status is "success". Only one shape has that status, so inside the if, TypeScript keeps only that shape. The query on line 9 shows it: state: { status: "success"; products: string[]; }. Line 8 may read the products, and the error is gone. Line 14 prints 2 products, and line 15 prints No products yet instead of throwing.

A shared field that names the shape

"Discriminate" means "tell apart". The field that tells the shapes apart is the tag, also called the discriminant. For a check on the tag to pick exactly one shape:

• every shape in the union has the field, with the same name;
• each shape gives it an exact value, a literal type;
• no two shapes use the same value.

Here is a discount at checkout. It takes a percent off, or a fixed amount off:

1type Discount =2  | { kind: "percent"; percent: number }3  | { kind: "fixed"; amount: number };4 5function priceAfter(discount: Discount, price: number) {6  if (discount.kind === "percent") {7    return price - (price * discount.percent) / 100;8    //                      ^?9  }10  return price - discount.amount;11  //             ^?12}13 14console.log(priceAfter({ kind: "percent", percent: 10 }, 20));15console.log(priceAfter({ kind: "fixed", amount: 5 }, 20));

Lines 1 to 3 say a Discount is one of two shapes. The tag is kind. A percent discount has a percent, and a fixed discount has an amount. Line 6 checks the kind. Inside the if, the query on line 8 shows discount is the percent shape, so line 7 may read discount.percent.

Line 7 also returns, so the code after the if only runs for the other shape. The query on line 11 shows discount is the fixed shape there, and line 10 reads discount.amount. Line 14 prints 18, which is 10% off 20, and line 15 prints 15, which is 5 off 20.

The tag can have any name. kind, type, and status are common. Its values can be text, numbers, or true and false. What matters is that each value is exact. Watch what happens when the tag is any string:

1type Discount =2  | { kind: string; percent: number }3  | { kind: string; amount: number };4 5function priceAfter(discount: Discount, price: number) {6  if (discount.kind === "percent") {7    return price - (price * discount.percent) / 100;8  }9  return price - discount.amount;10}11 12console.log(priceAfter({ kind: "percent", percent: 10 }, 20));

The only change is on lines 2 and 3: kind is a string in both shapes. Now "percent" fits both, so line 6 can't pick one. TypeScript marks line 7, on purpose: Property 'percent' does not exist on type 'Discount', because a fixed discount could get inside the if. Line 9 gets the same error for amount. The code runs and prints 18, but TypeScript can no longer check it for you.

Now change the check yourself. Type a different kind for line 6, and watch the list under the code as you type:

1type Discount =2  | { kind: "percent"; percent: number }3  | { kind: "fixed"; amount: number };4 5function priceAfter(discount: Discount, price: number) {6  if (discount.kind === "percent") {7    return price - (price * discount.percent) / 100;8  }9  return price - discount.amount;10}11 12console.log(priceAfter({ kind: "percent", percent: 10 }, 20));

With "fixed", the two branches swap shapes, and the reads on lines 7 and 9 no longer match: two errors. With the typo "percnt", TypeScript marks line 6 itself, because no discount can have that kind. That's a bug caught on the check, before anyone reads the wrong field. Put "percent" back and the errors go away.

The in & instanceof lesson told shapes apart with in, which asks whether an object has a field. That works too, but a tag is clearer. The table compares the two. Read each row as a question, then each check's answer.

switch on the tag

With three or more shapes, a chain of if checks gets long. A switch on the tag reads better: it compares one value with each case and runs the one that matches. TypeScript narrows inside every case. Here is a shopping cart that describes what the shopper just did:

1type CartAction =2  | { type: "add"; name: string; price: number }3  | { type: "remove"; name: string }4  | { type: "clear" };5 6function describe(action: CartAction) {7  switch (action.type) {8    case "add":9      return `Added ${action.name} for $${action.price}`;10    case "remove":11      return `Removed ${action.name}`;12      //                ^?13    case "clear":14      return "Emptied the cart";15  }16}17 18console.log(describe({ type: "add", name: "Tea", price: 3 }));19console.log(describe({ type: "remove", name: "Tea" }));20console.log(describe({ type: "clear" }));

Lines 1 to 4 describe three cart actions. Adding needs a name and a price, removing needs only a name, and clearing needs nothing else. The tag is type. Line 7 switches on action.type.

• In case "add":, line 9 reads the name and the price.
• In case "remove":, line 11 reads the name. The query on line 12 shows action: { type: "remove"; name: string; }: no price here.
• In case "clear":, line 14 needs nothing from the action.

Lines 18 to 20 print Added Tea for $3, Removed Tea, and Emptied the cart.

Two cases can share one body. TypeScript then keeps both shapes:

1type CartAction =2  | { type: "add"; name: string; price: number }3  | { type: "remove"; name: string }4  | { type: "clear" };5 6function itemName(action: CartAction) {7  switch (action.type) {8    case "add":9    case "remove":10      return action.name;11      //     ^?12    case "clear":13      return "every item";14  }15}16 17console.log(itemName({ type: "remove", name: "Cake" }));18console.log(itemName({ type: "clear" }));

Lines 8 and 9 list "add" and "remove" with nothing between them, so both run line 10. The query on line 11 shows action is the add shape or the remove shape. Both have a name, so line 10 may read it. Line 17 prints Cake and line 18 prints every item.

Now send the function different actions. Each button changes the object on line 17:

1type CartAction =2  | { type: "add"; name: string; price: number }3  | { type: "remove"; name: string }4  | { type: "clear" };5 6function describe(action: CartAction) {7  switch (action.type) {8    case "add":9      return `Added ${action.name} for $${action.price}`;10    case "remove":11      return `Removed ${action.name}`;12    case "clear":13      return "Emptied the cart";14  }15}16 17console.log(describe({ type: "add", name: "Tea", price: 3 }));

The tag decides two things. While the page runs, it decides which case runs: the highlighted lines. Before it runs, it decides what TypeScript expects: an add action must have a price, so Add with no price gets an error and prints $undefined. And A refund isn't one of the three tags, so TypeScript marks it before it can fall through every case and print undefined.

Loading, success, and error as one type

Almost every page that loads data goes through the same moments: waiting for the reply, showing the data, or showing what went wrong. ProductsState describes them, and the function that loads the products gives back one of them:

1type ProductsState =2  | { status: "loading" }3  | { status: "success"; products: string[] }4  | { status: "error"; message: string };5 6async function loadProducts(): Promise<ProductsState> {7  try {8    const response = await fetch("/api/products");9    const products: string[] = await response.json();10    return { status: "success", products };11  } catch (error) {12    return { status: "error", message: String(error) };13  }14}

This code needs a real server at /api/products, so it has no Run button here. Line 6 says loadProducts gives back a Promise<ProductsState>: a promise that later hands over a ProductsState (async and await covers promises). Line 8 asks the server for the products, and line 9 reads the list from its reply. Line 10 returns a success state with that list. If anything goes wrong, line 12 returns an error state with a message. Each return builds one shape, and TypeScript checks it against the shape its tag names. The page starts as { status: "loading" } and shows whatever comes back.

Now put the page in each state. Lines 6 to 15 turn a state into what the page shows. Line 17 stores a state, and line 18 prints what the page shows for it. Each button changes line 17:

1type ProductsState =2  | { status: "loading" }3  | { status: "success"; products: string[] }4  | { status: "error"; message: string };5 6function render(state: ProductsState) {7  switch (state.status) {8    case "loading":9      return "Loading products";10    case "success":11      return state.products.join(", ");12    case "error":13      return `Something went wrong: ${state.message}`;14  }15}16 17const state: ProductsState = { status: "loading" };18console.log(render(state));

Loading, Loaded, and Failed each run their own case, and each case reads only the data its state has. Loaded, but no list says it succeeded without saying what it found. TypeScript checks it against the success shape and reports Property 'products' is missing. Without that check, line 11 would throw a TypeError on the page.

States that can't happen

Before discriminated unions, many pages kept one object with a loading flag and optional fields. In a type, a ? after a field's name makes it optional: the object may leave it out. (The Object types lesson covers this.) Here is the same product list written that way:

1type ProductsState = {2  loading: boolean;3  products?: string[];4  error?: string;5};6 7function render(state: ProductsState) {8  if (state.loading) return "Loading products";9  if (state.error) return `Something went wrong: ${state.error}`;10  return state.products.join(", ");11}12 13console.log(render({ loading: true, products: ["Tea", "Cake"], error: "Network down" }));14console.log(render({ loading: false }));

Lines 1 to 5 describe a state with a loading flag and two optional fields. Line 8 returns early while loading, and line 9 returns early when there's an error. You know that leaves a successful state with products. TypeScript doesn't: nothing in the type ties "not loading and no error" to "has products". So it marks line 10, on purpose: 'state.products' is possibly 'undefined'.

It's right to worry. Line 13 passes a state that is loading, has two products, and failed. TypeScript accepts it, and it prints Loading products. Line 14 passes a state that isn't loading, has no error, and has no products. TypeScript accepts that too, and line 10 throws a TypeError.

Count what the loose type allows. loading is true or false, and products and error are each there or missing: 2 × 2 × 2 = 8 combinations. Only 3 of them make sense. The union allows exactly those 3, so a state that can't happen can't be written:

1type ProductsState =2  | { status: "loading" }3  | { status: "success"; products: string[] }4  | { status: "error"; message: string };5 6const state: ProductsState = {7  status: "loading",8  products: ["Tea", "Cake"],9  message: "Network down",10};

Line 7 says the state is loading. A loading state has no other fields, so TypeScript marks line 8, on purpose: Object literal may only specify known properties, and 'products' does not exist in type '{ status: "loading"; }'. An object literal is an object written out in { }, so this means "this object has a field its shape doesn't list". TypeScript reports the first extra field it finds; remove products and line 9 gets the same error for message.

The table compares the two designs. Read each row as a question, then each design's answer.

A profile page and its API reply

A profile page asks the server for the signed-in user. Many APIs answer with an ok field: true with the data, or false with an error. That's a tag too, with true and false as its two exact values:

1type User = { name: string; email: string };2type UserReply =3  | { ok: true; user: User }4  | { ok: false; error: string };5 6function greeting(reply: UserReply) {7  if (reply.ok) {8    return `Welcome back, ${reply.user.name}`;9  }10  return `Could not load your profile: ${reply.error}`;11  //                                     ^?12}13 14console.log(greeting({ ok: true, user: { name: "Asha", email: "asha@example.com" } }));15console.log(greeting({ ok: false, error: "Signed out" }));

Line 1 describes a User. Lines 2 to 4 say a reply is ok: true with a user, or ok: false with an error. Line 7 checks reply.ok. Inside, only the ok: true shape is left, so line 8 may read reply.user.name. After the if, the query on line 11 shows reply: { ok: false; error: string; }, and line 10 reads the error. Line 14 prints Welcome back, Asha, and line 15 prints Could not load your profile: Signed out.

Here is the function that builds those replies from a real request:

1type User = { name: string; email: string };2type UserReply =3  | { ok: true; user: User }4  | { ok: false; error: string };5 6async function loadUser(id: number): Promise<UserReply> {7  const response = await fetch(`/api/users/${id}`);8  if (!response.ok) {9    return { ok: false, error: `The server said ${response.status}` };10  }11  const user: User = await response.json();12  return { ok: true, user };13}

This code needs a real server, so it has no Run button here. Line 7 asks for the user with fetch. Line 8 checks the browser's own response.ok, which is false when the server answers with an error code like 404. Then line 9 returns a failed reply. Otherwise line 11 reads the user from the reply's JSON, and line 12 returns a successful one. Every page that calls loadUser has to check ok before it can reach the user.

Common mix-ups

A tag only helps when the data really has it. Here a server reply claims to be a success:

1type ProductsState =2  | { status: "loading" }3  | { status: "success"; products: string[] }4  | { status: "error"; message: string };5 6const state: ProductsState = JSON.parse('{ "status": "success" }');7if (state.status === "success") {8  console.log(state.products.length);9}

Line 6 reads a state from a server reply with JSON.parse. JSON.parse gives back the type any, which TypeScript never checks, so it trusts the ProductsState type you wrote. Line 7 checks the tag, and TypeScript reports nothing. But the reply has no products, so line 8 throws a TypeError when it runs. The types are removed before the code runs, so nothing checks that the tag matches the fields.

• "The tag has to be called kind." No. Any name works, as long as every shape has it. type, status, and ok are common too.
• "Any shared field works as a tag." No. Each shape has to give it an exact value. With kind: string in every shape, checking it can't pick one.
• "Optional fields are just as safe." No. They allow states that can't happen, like loading with an error, and they make you check fields TypeScript can't connect.
• "TypeScript checks the tag while the page runs." No. It checks your code before it runs. A reply that says "success" and has no products gets through.
• "Discriminated unions need special syntax." No. They're ordinary unions of object types. The shared field with exact values is all it takes.
• "I can check state.products to find a successful state." No. Until the tag is checked, you can read only fields every shape has, like status. if (state.products) is an error of its own, because a loading state has no products to read.

Practice exercises

Each exercise is TypeScript. When you fix or write code, press Edit & run on the starter code: the errors update as you type, and the console shows what it prints. Try a guess first, then use the hints.

1type Discount =2  | { kind: "percent"; percent: number }3  | { kind: "fixed"; amount: number };4 5function label(discount: Discount) {6  if (discount.kind === "fixed") {7    return `$${discount.amount} off`;8  }9  return `${discount.percent}% off`;10}

1type Discount =2  | { kind: "percent"; percent: number }3  | { kind: "fixed"; amount: number };4 5function label(discount: Discount) {6  if (discount.kind === "fixed") {7    return `$${discount.amount} off`;8    //         ^?9  }10  return `${discount.percent}% off`;11}

type ProductsState =
  | { status: "loading" }
  | { status: "success"; products: string[] }
  | { status: "error"; message: string };

function render(state: ProductsState) {
  switch (state.status) {
    case "loading":
      return "Loading products";
    case "success":
      return state.message;
    case "error":
      return `Something went wrong: ${state.message}`;
  }
}

1type ProductsState =2  | { status: "loading" }3  | { status: "success"; products: string[] }4  | { status: "error"; message: string };5 6function render(state: ProductsState) {7  switch (state.status) {8    case "loading":9      return "Loading products";10    case "success":11      return state.products.join(", ");12    case "error":13      return `Something went wrong: ${state.message}`;14  }15}

1type InfoToast = { text: string };2type UndoToast = { text: string; undoLabel: string };3type Toast = InfoToast | UndoToast;4 5function buttonText(toast: Toast) {6  return toast.undoLabel;7}8 9console.log(buttonText({ text: "Saved" }));

1type InfoToast = { kind: "info"; text: string };2type UndoToast = { kind: "undo"; text: string; undoLabel: string };3type Toast = InfoToast | UndoToast;4 5function buttonText(toast: Toast) {6  if (toast.kind === "undo") {7    return toast.undoLabel;8  }9  return "Close";10}11 12console.log(buttonText({ kind: "info", text: "Saved" }));13console.log(buttonText({ kind: "undo", text: "Tea removed", undoLabel: "Undo" }));

1type SaveState = {2  saving: boolean;3  savedAt?: string;4  error?: string;5};6 7function saveLabel(state: SaveState) {8  if (state.saving) return "Saving";9  if (state.error) return `Not saved: ${state.error}`;10  return `Saved at ${state.savedAt.slice(0, 5)}`;11}12 13console.log(saveLabel({ saving: false, savedAt: "14:30:05" }));

1type SaveState =2  | { status: "saving" }3  | { status: "saved"; savedAt: string }4  | { status: "failed"; error: string };5 6function saveLabel(state: SaveState) {7  switch (state.status) {8    case "saving":9      return "Saving";10    case "saved":11      return `Saved at ${state.savedAt.slice(0, 5)}`;12    case "failed":13      return `Not saved: ${state.error}`;14  }15}16 17console.log(saveLabel({ status: "saved", savedAt: "14:30:05" }));

1type ProductsState =2  | { status: "loading" }3  | { status: "success"; products: string[] }4  | { status: "error"; message: string };5 6function render(state: ProductsState) {7  switch (state.status) {8    case "loading":9      return "Loading products";10    case "success":11      return state.products.join(", ");12    case "error":13      return `Something went wrong: ${state.message}`;14  }15}16 17console.log(render({ status: "idle" }));

1type ProductsState =2  | { status: "idle" }3  | { status: "loading" }4  | { status: "success"; products: string[] }5  | { status: "error"; message: string };6 7function render(state: ProductsState) {8  switch (state.status) {9    case "idle":10      return "Type to search";11    case "loading":12      return "Loading products";13    case "success":14      return state.products.join(", ");15    case "error":16      return `Something went wrong: ${state.message}`;17  }18}19 20console.log(render({ status: "idle" }));

1// Write SignupState here: editing, sending, sent (with the email), or failed (with a message).2 3function statusText(state: SignupState) {4  switch (state.status) {5    case "editing":6      return "Enter your email";7    case "sending":8      return "Sending";9    case "sent":10      return `Check ${state.email} for a link`;11    case "failed":12      return `Try again: ${state.message}`;13  }14}15 16console.log(statusText({ status: "sent", email: "asha@example.com" }));

1type SignupState =2  | { status: "editing" }3  | { status: "sending" }4  | { status: "sent"; email: string }5  | { status: "failed"; message: string };6 7function statusText(state: SignupState) {8  switch (state.status) {9    case "editing":10      return "Enter your email";11    case "sending":12      return "Sending";13    case "sent":14      return `Check ${state.email} for a link`;15    case "failed":16      return `Try again: ${state.message}`;17  }18}19 20console.log(statusText({ status: "sent", email: "asha@example.com" }));

Check your understanding

For each question, ask which shape the code has at that line, and what that shape's fields are. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• A discriminated union is a union of object types that share one field, the tag, with a different exact value in each.
• Checking the tag with ===, !==, or a truthiness check narrows the whole object to one shape.
• A switch on the tag gives each shape its own case, and two cases can share one body.
• The tag needs exact values: text, numbers, or true and false. A tag typed as string can't pick a shape.
• Describe loading, success, and error as one union, so each state carries exactly its own data.
• Optional fields allow states that can't happen; a union rules them out before the code runs.
• Data from a server isn't checked while the page runs, so a wrong tag can still get through.

Coming next: Exhaustiveness checking. It makes TypeScript tell you when a switch forgets one of the union's shapes, like a new state you just added.