Here is how Cartwheel’s Order type looked before anyone thought about it:
type Order = {\n id: number;\n status: 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned';\n trackingNumber?: string; // set once shipped\n deliveredAt?: string; // set once delivered\n cancelReason?: string; // set if cancelled\n refundCents?: number; // set if returned\n};It looks reasonable, and it is a trap. Four optional fields can each be present or absent, so this type allows 5 × 2⁴ = 80 shapes. Cartwheel’s business has five. A shipped order with no tracking number compiles. A cancelled order with a delivery date compiles. And every time you read order.trackingNumber, you get string | undefined and reach for !, which is you telling the compiler “trust me” eighty times a week.
A discriminated union gives each state its own object type and joins them with |. Each member has a shared property with a different literal value, the discriminant:
type ProcessingOrder = { id: number; status: 'processing' };\ntype ShippedOrder = { id: number; status: 'shipped'; trackingNumber: string };\ntype DeliveredOrder = { id: number; status: 'delivered'; trackingNumber: string; deliveredAt: string };\ntype CancelledOrder = { id: number; status: 'cancelled'; cancelReason: string };\ntype ReturnedOrder = {\n id: number;\n status: 'returned';\n trackingNumber: string;\n deliveredAt: string;\n refundCents: number;\n};\n\ntype Order = ProcessingOrder | ShippedOrder | DeliveredOrder | CancelledOrder | ReturnedOrder;Now the type allows exactly five shapes. Notice that nothing is optional any more: a shipped order has a tracking number. The impossible states are not checked at runtime; they are simply not expressible:
\nconst o: Order = { id: 1042, status: 'shipped' };\n// Error: Type '{ id: number; status: \"shipped\"; }' is not assignable to type 'Order'.\n// Property 'trackingNumber' is missing in type '{ id: number; status: \"shipped\"; }'\n// but required in type 'ShippedOrder'.Checking the discriminant narrows the whole object. Inside each case, TypeScript knows exactly which member you have:
function describe(order: Order): string {\n switch (order.status) {\n case 'processing':\n return `#${order.id} is being packed`;\n case 'shipped':\n return `#${order.id} is on its way (${order.trackingNumber})`;\n case 'delivered':\n return `#${order.id} arrived on ${order.deliveredAt}`;\n case 'cancelled':\n return `#${order.id} was cancelled: ${order.cancelReason}`;\n case 'returned':\n return `#${order.id} was refunded $${(order.refundCents / 100).toFixed(2)}`;\n }\n}No !, no ?., no ?? ''. And notice the explicit : string return type. If someone adds an 'on-hold' status to the union next month, the end of this function becomes reachable, and TypeScript reports Function lacks ending return statement and return type does not include ‘undefined’. The compiler finds every place that needs updating. You will make this check explicit and louder with never in Branded Types and Exhaustive Checks.
The union pays off most in functions that change state. Type their inputs and outputs as specific variants:
\nfunction ship(order: ProcessingOrder, trackingNumber: string): ShippedOrder {\n return { id: order.id, status: 'shipped', trackingNumber };\n}\n\nfunction cancel(order: ProcessingOrder, reason: string): CancelledOrder {\n return { id: order.id, status: 'cancelled', cancelReason: reason };\n}Now “you cannot ship an order twice” and “you cannot cancel a shipped order” are compile-time facts. A caller with an Order in hand must narrow first:
function shipIfReady(order: Order, tracking: string): Order {\n if (order.status !== 'processing') return order;\n return ship(order, tracking); // order is ProcessingOrder here\n}The return types matter as much as the parameters. Because ship returns a ShippedOrder rather than an Order, the caller can hand the result straight to a function that needs a tracking number, such as printLabel(shipped), without checking status again. Each transition carries the knowledge forward. Return the wide Order and you throw that knowledge away, forcing every caller to narrow again.
Real orders have more than an id: a customer, a placed-at timestamp, line items. Repeating those in five variants invites drift, so pull them into a base type and intersect it with each state’s own fields:
type OrderBase = { id: number; customerId: number; placedAt: string };\n\ntype Shipped = OrderBase & { status: 'shipped'; trackingNumber: string };\ntype Cancelled = OrderBase & { status: 'cancelled'; cancelReason: string };Each variant is still a separate member with its own literal status, so narrowing works exactly as before. The base type also gives you a natural parameter type for functions that do not care about the state, such as function customerLink(order: OrderBase), which accepts every variant.
You can also destructure the discriminant. Since TypeScript 4.4, const { status } = order; if (status === 'shipped') { … } narrows order too, as long as order is a const or an unassigned parameter. That keeps long switch statements readable without giving up the narrowing.
A discriminated union is right when states carry different data. When the variants differ only in a label (say, a channel of 'web' | 'mobile_app' | 'marketplace' with the same fields), a plain literal union on one property is enough. Reach for the full pattern when you catch yourself writing optional fields with comments like “only set when…”.
In the exercise, you will turn Cartwheel’s bag-of-optionals Order into a union and make ship accept only orders that can be shipped. Next lesson: literal types, as const and satisfies, the tools that keep those literals from widening back into string.
status.","Checking the discriminant with === or switch narrows the whole object, so state-specific fields become available without !.","Functions that move between states should accept and return specific variants, like ship(order: ProcessingOrder): ShippedOrder.","An explicit return type on a switch over the discriminant turns a forgotten case into a compile error."],"further":[{"title":"Discriminated unions (Narrowing)","url":"https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"},{"title":"Unions and intersection types (Everyday Types)","url":"https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#union-types"}],"quiz":[{"q":"An Order type has a status with 5 values and 4 optional fields. Roughly how many shapes does the type allow, and how many of them are valid states if each status uses a fixed set of fields?
status controls which fields exist.","why":"Nothing in an optional-field type ties fields to status. The compiler sees them as independent."},{"text":"80 allowed (5 × 2⁴), 5 valid.","why":"Correct. Each optional field can be present or absent independently, so most combinations are impossible states that still compile."},{"text":"20 allowed (5 × 4), 5 valid.","why":"Optional fields multiply, they do not add. Four independent yes/no choices give 16 combinations per status."}],"answer":1},{"q":"Given the union below, what is the type of order inside the case 'returned': branch?
type Order =\n | { status: 'processing'; id: number }\n | { status: 'delivered'; id: number; deliveredAt: string }\n | { status: 'returned'; id: number; deliveredAt: string; refundCents: number };Order, because switch does not narrow objects","why":"Switching on a literal discriminant narrows the whole object, which is the point of the pattern."},{"text":"{ status: 'delivered' … } | { status: 'returned' … }, because both have deliveredAt","why":"Narrowing follows the discriminant value, not the shared fields. Only one member has status: 'returned'."},{"text":"{ status: 'returned'; id: number; deliveredAt: string; refundCents: number }","why":"Correct. Only that member’s status can equal 'returned', so refundCents is available as a plain number."}],"answer":2},{"q":"Which signature best uses the union to prevent shipping an order twice?
","options":[{"text":"ship(order: Order, tracking: string): Order","why":"This accepts a delivered or cancelled order too, and the caller loses the knowledge that the result is shipped."},{"text":"ship(order: Order, tracking: string): ShippedOrder","why":"The return type is better, but any order, including one already shipped, can still be passed in."},{"text":"ship(order: ShippedOrder, tracking: string): ShippedOrder","why":"This only accepts orders that are already shipped, which is the opposite of what the function should allow."},{"text":"ship(order: ProcessingOrder, tracking: string): ShippedOrder","why":"Correct. Only a processing order can go in, and the caller gets back a value the compiler knows is shipped."}],"answer":3},{"q":"You add an 'on-hold' status to the Order union. Which function is guaranteed to get a compile error until you handle it?
string whose switch returns in every case and has no default.","why":"Correct. With the new member unhandled, the end of the function is reachable, so TypeScript reports that it lacks an ending return statement."},{"text":"A function that uses if (order.status === 'shipped') … else ….","why":"The else branch silently absorbs the new status, which is exactly the bug you want to avoid."},{"text":"A function with a default: branch that returns 'Unknown'.","why":"The default handles the new status at runtime, so the compiler has no reason to complain."}],"answer":0}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"// Every field that only some statuses have is optional,\n// so impossible states (shipped with no tracking number…) compile.\ntype Order = {\n id: number;\n status: 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned';\n trackingNumber?: string; // shipped, delivered, returned\n deliveredAt?: string; // delivered, returned\n cancelReason?: string; // cancelled\n refundCents?: number; // returned\n};\n\nfunction ship(order: Order, trackingNumber: string): Order {\n return { id: order.id, status: 'shipped', trackingNumber };\n}\n\nfunction describe(order: Order): string {\n switch (order.status) {\n case 'processing': return `#${order.id} is being packed`;\n case 'shipped': return `#${order.id} is on its way (${order.trackingNumber})`;\n case 'delivered': return `#${order.id} arrived on ${order.deliveredAt}`;\n case 'cancelled': return `#${order.id} was cancelled: ${order.cancelReason}`;\n case 'returned': return `#${order.id} was refunded $${(order.refundCents! / 100).toFixed(2)}`;\n }\n}\n\n// ---- Type tests (do not edit) ----\ntype T1 = ExpectReplace the bag-of-optionals Order with a discriminated union of five variants (one per status), where every field a state has is required and fields it does not have are absent:
processing: idshipped: id, trackingNumberdelivered: id, trackingNumber, deliveredAtcancelled: id, cancelReasonreturned: id, trackingNumber, deliveredAt, refundCentsThen change ship so it only accepts a processing order and returns a shipped one. The three @ts-expect-error lines must become real errors, and describe should no longer need !.
status set to a single string literal, and join them with |.","Naming the variants (ProcessingOrder, ShippedOrder…) lets you use them in ship’s signature.","function ship(order: ProcessingOrder, trackingNumber: string): ShippedOrder"],"explanation":"Each variant now carries exactly the data its state has, so an object literal without trackingNumber cannot be a shipped order, and an excess deliveredAt on a cancelled order is flagged. Inside each case, the status check narrows order to one variant, so refundCents is a plain number and the ! is unnecessary. Typing ship with ProcessingOrder in and ShippedOrder out moves the rule “only processing orders ship” from a code review comment into the compiler.
ship returns a shipped order with the tracking number and the same id","describes":"describe still describes returned and cancelled orders"}},"words":719,"readMinutes":3}