TypeScript for real code · Chapter 29 of 36

Not just a number

By the end of this chapter you can make types that share a base type (two kinds of number, two kinds of id) impossible to mix up, and make sure every such value was checked when it was made. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Real-world TypeScript
  • 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

Meera found two bugs in one week. UPI works in paise and the menu in rupees, and the bill for a masala chai (₹40) and a cutting chai (₹25) came to 4025 paise, ₹40.25, because one item was added in rupees. Then the support screen cancelled an order with the customer's id where the order's id should be.

Both bugs had types. Rupees and Paise were aliases of number, and an alias is only a new name: TypeScript compares types by their shape, and both shapes are number. The same goes for two kinds of id that are both string.

What you build: 4 tasks

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

  1. Task 1

    Brand: a type a plain value cannot pass for

    Brand<T, Name> is T plus a readonly marker property that no plain value has, whose type is Name, instead of just T. With type Cups = Brand<number, 'Cups'> and type Kulhads = Brand<number, 'Kulhads'>, a plain 3 is not Cups (a type error), and Cups are not Kulhads (a type error).

    A brand still works like its base type: Cups can be used as a number and added to, and a Brand<string, 'RiderName'> still has toUpperCase.

  2. Task 2

    rupees and paise: two brands of number, each checked

    Make Rupees and Paise two different brands of number (use Brand, with the names 'Rupees' and 'Paise'), so a plain 40 is not Rupees, Rupees are not Paise, and Paise are not Rupees: each of those is a type error.

    rupees(n) and paise(n) are the only way to make them. They check that n is a whole number, 0 or more, and throw a RangeError otherwise, then brand it: rupees(40) is 40, rupees(0) is 0 and paise(4000) is 4000, while rupees(2.5), rupees(-1) and paise(0.5) throw a RangeError. rupees returns exactly Rupees and paise exactly Paise. The cast after the check is the one place an as belongs.

  3. Task 3

    toPaise and totalPaise: keep the bill's units straight

    toPaise(rupees(40)) is 4000, and totalPaise adds up a list of Paise: totalPaise([paise(4000), paise(2500)]) is 6500 and totalPaise([]) is 0. Both return exactly Paise, so toPaise(paise(4000)) is a type error (those are already paise), and so is totalPaise([rupees(40)]) (a bill in paise cannot have rupees in it).

    Bunty's bill below mixes up the units and comes to 4025: once the brands are in, typecheck points at the mistake. Fix it, so bill is 6500.

  4. Task 4 · interview question

    Interview: OrderId and UserId, swapped arguments caught

    An OrderId looks like 'ord-17' and a UserId like 'usr-4'. Make them two different brands of string, so plain strings are a type error where either is wanted and an OrderId is not a UserId; each is still usable as a string. orderId() and userId() check the format and throw an Error otherwise: orderId('usr-4'), userId('ord-17') and orderId('17') all throw.

    cancelOrder takes the order first, then who cancelled it, so cancelOrder(user, order) is a type error. cancelForCustomer passes them the wrong way round: fix it, so cancelForCustomer(userId('usr-4'), orderId('ord-17')) is 'ord-17 cancelled by usr-4'. Dev will ask why a plain alias for an id does not protect you.

What you will learn

  • Brands: an intersection with a marker property that no plain value has, so two numbers or two strings become different types.
  • Checked constructors: one small function per brand that checks the value, then brands it with the only cast in the code.
  • Arithmetic and brands: a brand works like its base type, but a sum of brands is a plain number again.

More in Real-world TypeScript

Build "Not just a number" 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.