TypeScript for real code · Chapter 9 of 36

Orders in every state

By the end of this chapter you can model something that moves through states, with one shape per state, and let the compiler find every place that forgets one. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Modelling Tapri
  • 4 tasks
  • TypeScript
  • In the all labs plan

The first 2 chapters of TypeScript for real code are free. This one comes with the all labs plan.

Why you need this

A customer opened the tracking screen and read "T1: on the way with undefined". Ravi checked: the order was marked out for delivery before a rider took it. The Order type has a status that is any text and every other field optional, so nothing stops an order on the way with no rider, or a cancelled one with no reason. And Meera wants a new pickup state soon, which means finding every piece of code that looks at a status.

With one loose type, every field is "maybe there", and you read them on hope. A check like order.status === 'out-for-delivery' tells you nothing about order.rider, so TypeScript cannot help, and a new status is found by searching the code and praying.

What you build: 4 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    Order: one shape per status

    Replace the loose Order type with a union of five object types, one per status. Each has status set to its exact text and id: string, plus only its own data: 'placed' has placedAt: string (a time like '16:02'), 'brewing' has readyInMinutes: number, 'out-for-delivery' has rider: string, 'delivered' has deliveredAt: string and 'cancelled' has reason: string.

    Then an order out for delivery with no rider is a type error, and so are a placed order with a rider and a status like 'lost'. { status: 'delivered', id: 'T4', deliveredAt: '16:20' } is a fine Order.

  2. Task 2

    describe: one line for every status

    describe writes one line for the tracking screen, with a switch on order.status:

    'placed' gives 'T1: placed at 16:02', 'brewing' gives 'T2: brewing, ready in 4 min', 'out-for-delivery' gives 'T3: on the way with Raju', 'delivered' gives 'T4: delivered at 16:20' and 'cancelled' gives 'T5: cancelled (rain)', each starting with the order's own id.

    Keep the parameter an Order, so describe('placed') is a type error, and end the switch with default: return assertNever(order).

  3. Task 3

    assertNever: accept only never

    Give value the type never, so a call to assertNever only compiles when every case has been handled before it: assertNever('placed') is a type error, and so is a whole order object. The return type stays never.

    At runtime a value can still sneak in from JSON, so it throws an Error whose message is 'Unexpected order: ' followed by the value as JSON. For { status: 'lost' } the message is 'Unexpected order: {"status":"lost"}'.

  4. Task 4 · interview question

    Interview: a ready state, handled everywhere

    Meera wants a pickup counter. Add a sixth shape to Order: status 'ready' with id: string and counter: number, so { status: 'ready', id: 'T7', counter: 2 } is an Order.

    Then run typecheck and fix every place it points at, until the whole file has no type errors. describe gives 'T7: ready at counter 2' for that order, and a ready order can no longer be cancelled: canCancel gives false for it, and still true for a placed order. Dev will ask how many places the compiler found, and how it found them.

What you will learn

  • Discriminated unions: one object type per state, each with an exact tag, joined with |.
  • Narrowing on the tag: after a check on the tag, TypeScript knows the shape and its fields.
  • Exhaustiveness with never: when every case is handled, what is left is never, and a forgotten case becomes a type error.

More in Modelling Tapri

Build "Orders in every state" yourself

Tapri’s codebase grows, and types keep it honest. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of TypeScript for real code are free. This one comes with the all labs plan.