The refund bug from the first lesson came down to two numbers that looked the same: dollars and cents. Cartwheel has the same problem everywhere. An order id and a customer id are both number. An amount in cents and a quantity are both number. Structural typing, which you met in Structural Typing and Assignability, considers same-shaped things identical, so it happily lets you write cancelOrder(customer.id).
The fix is to make the shapes differ, without changing anything at runtime.
\nA branded type intersects a primitive with a property that only exists in the type system:
\ndeclare const brand: unique symbol;\ntype Brand<T, B extends string> = T & { readonly [brand]: B };\n\ntype OrderId = Brand<number, 'OrderId'>;\ntype CustomerId = Brand<number, 'CustomerId'>;\ntype Cents = Brand<number, 'Cents'>;declare const brand: unique symbol declares a symbol that never exists at runtime; using it as the property key means no real object can accidentally have it, and nothing outside this file can forge it by name. An OrderId is still a number for every purpose (you can compare it, print it, send it as JSON), but TypeScript no longer accepts a plain number or a CustomerId in its place:
function cancelOrder(id: OrderId) {}\n\ncancelOrder(customer.id);\n// Error: Argument of type 'CustomerId' is not assignable to parameter of type 'OrderId'.\ncancelOrder(1042);\n// Error: Argument of type 'number' is not assignable to parameter of type 'OrderId'.If a plain number is not an OrderId, where do OrderIds come from? From exactly one function per brand, a smart constructor that validates and then casts:
function toOrderId(n: number): OrderId {\n if (!Number.isInteger(n) || n < 1000) throw new Error(`Invalid order id: ${n}`);\n return n as OrderId;\n}\n\nfunction toCents(n: number): Cents {\n if (!Number.isSafeInteger(n)) throw new Error(`Cents must be a whole number, got ${n}`);\n return n as Cents;\n}This is the one legitimate home for as in branded code. Because the cast only happens after validation, every OrderId anywhere in the system is known to be a valid id. A brand is a receipt: it proves the value went through the check.
Branding cents is half the job. The other half is currency. Make the currency a type parameter, so Money<'USD'> and Money<'EUR'> are different types:
type Currency = 'EGP' | 'AED' | 'SAR' | 'JOD' | 'GBP' | 'EUR' | 'USD' | 'CAD';\ntype Money<C extends Currency = Currency> = { cents: Cents; currency: C };\n\nfunction add<C extends Currency>(a: Money<C>, b: Money<NoInfer<C>>): Money<C> {\n return { cents: toCents(a.cents + b.cents), currency: a.currency };\n}\n\nadd(usdPrice, usdShipping); // Money<'USD'>\nadd(usdPrice, eurShipping);\n// Error: Argument of type 'Money<\"EUR\">' is not assignable to parameter of type 'Money<\"USD\">'.Two details matter. Without NoInfer, both arguments would be inference sites and C would quietly become 'USD' | 'EUR', the exact trap from Controlling Inference. And a.cents + b.cents is a plain number: arithmetic strips brands, because TypeScript has no idea whether the result still means “cents”. Re-brand deliberately, through the constructor, so the rule “cents are whole numbers” is checked again.
Do not brand everything. Each brand adds a constructor call wherever values enter the system, and a test fixture has to go through it too. Brand where two values share a primitive type, are easy to confuse, and are expensive to confuse: ids of different entities, amounts in different units, and strings that must pass validation before use, such as an Email or a Sku. A quantity that is only ever multiplied by a price does not need one. On a large codebase, a dozen well-chosen brands catch most of the “right type, wrong meaning” bugs; a hundred of them mostly generate casts.
Brands make values distinct. The other everyday pattern makes handling complete. You saw in Discriminated Unions for Domain States that a missing return can reveal a missed case. A never check makes that explicit and works even when the function returns nothing:
function assertNever(value: never): never {\n throw new Error(`Unhandled value: ${JSON.stringify(value)}`);\n}\n\nfunction notifyCustomer(order: Order): void {\n switch (order.status) {\n case 'processing': return sendEmail('We are packing your order');\n case 'shipped': return sendEmail(`Track it: ${order.trackingNumber}`);\n case 'delivered': return sendEmail('Enjoy!');\n case 'cancelled': return sendEmail(`Cancelled: ${order.cancelReason}`);\n case 'returned': return sendEmail('Refund on its way');\n default: return assertNever(order);\n }\n}In the default branch, every handled member has been narrowed away, so order is never, and passing it to a never parameter compiles. Add an 'on-hold' status and order becomes the on-hold variant in that branch, which is not assignable to never: compile error, pointing at the exact switch to update. At runtime, if bad data ever sneaks past the types, the function throws with a clear message instead of doing nothing.
If you prefer not to define a helper, default: throw new Error(`Unhandled: ${order satisfies never}`) does the same check inline. And for lookups, Record<OrderStatus, string> with satisfies gives you exhaustiveness for free: a missing key is a compile error.
In the exercise you will brand Cartwheel’s ids and cents, make add reject mixed currencies, and add an exhaustive check. Next lesson tackles the other thing every checkout must handle: failures you expect.
OrderId and a CustomerId stop being interchangeable even though both are numbers.","Create branded values only in smart constructors that validate first; that is the one place an as cast belongs.","Arithmetic on branded numbers returns plain number, so money helpers must re-brand their results deliberately.","Money<NoInfer<C>> on the second argument stops add(usd, eur) from inferring a mixed-currency union.","A default branch that passes the value to a never parameter, or checks it with satisfies never, turns a missed union member into a compile error."],"further":[{"title":"Unique symbol types","url":"https://www.typescriptlang.org/docs/handbook/symbols.html#unique-symbol"},{"title":"Exhaustiveness checking (Narrowing)","url":"https://www.typescriptlang.org/docs/handbook/2/narrowing.html#exhaustiveness-checking"}],"quiz":[{"q":"type OrderId = number & { readonly [brand]: 'OrderId' }. What does the brand property look like at runtime?
OrderId value carries a hidden symbol property.","why":"Primitives cannot carry properties, and the brand is only declared, never assigned. It exists in the type system alone."},{"text":"The value is boxed into a Number object with the symbol attached.","why":"Nothing boxes the value. A cast like n as OrderId emits no code at all."},{"text":"It does not exist; the value is a plain number, and the brand lives only in the type.","why":"Correct. That is why brands are free at runtime, and also why data from JSON.parse is never branded until you construct it."}],"answer":2},{"q":"Where should as OrderId appear in a well-designed codebase?
OrderId.","why":"That turns the brand into decoration; any number can be cast anywhere and the guarantee is gone."},{"text":"Only inside the smart constructor that validates the number first.","why":"Correct. One validated entry point means every OrderId in the system has been checked."},{"text":"Nowhere; brands should be created with satisfies.","why":"satisfies checks against a type without changing it, so it cannot add a brand that the value does not have."}],"answer":1},{"q":"add<C extends Currency>(a: Money<C>, b: Money<C>) is called as add(usd, eur). What happens?
C becomes 'USD' | 'EUR' and the call compiles."},{"text":"It compiles, because C is inferred as 'USD' | 'EUR'; mark the second parameter Money<NoInfer<C>> to reject it.","why":"Correct. With NoInfer, C comes from the first argument only, and Money<'EUR'> fails against Money<'USD'>."},{"text":"It throws at runtime because the brand does not match.","why":"Brands do not exist at runtime, so nothing can throw because of one."}],"answer":1},{"q":"A new 'on-hold' status is added. Which function fails to compile until it handles it?
function label(s: OrderStatus): string {\n switch (s) {\n case 'processing': return 'Packing';\n // …one case for every other existing status…\n default: return assertNever(s);\n }\n}default branch s is 'on-hold', which is not assignable to never.","why":"Correct. The default branch only sees the members no case handled, and assertNever accepts none."},{"text":"None; default handles every value, so the compiler is satisfied.","why":"A plain default would hide the new status. Passing the value to a never parameter is what makes it a check."},{"text":"Every function that uses OrderStatus, including ones that only store it.","why":"Only code that claims exhaustiveness is affected. Functions that store or pass the status through keep compiling."},{"text":"Only functions that use if statements instead of switch","why":"The check is about the never parameter, not the statement used; it works with if chains too."}],"answer":0}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"// Brand these three so they stop being interchangeable numbers.\ntype OrderId = number;\ntype CustomerId = number;\ntype Cents = number;\n\nfunction toOrderId(n: number): OrderId {\n if (!Number.isInteger(n) || n < 1000) throw new Error(`Invalid order id: ${n}`);\n return n;\n}\n\nfunction toCustomerId(n: number): CustomerId {\n if (!Number.isInteger(n) || n < 1) throw new Error(`Invalid customer id: ${n}`);\n return n;\n}\n\nfunction toCents(n: number): Cents {\n if (!Number.isSafeInteger(n)) throw new Error(`Cents must be a whole number, got ${n}`);\n return n;\n}\n\ntype Currency = 'USD' | 'EUR' | 'EGP';\ntype MoneyHarden Cartwheel’s checkout types:
\nOrderId, CustomerId and Cents so they are distinct from number and from each other, and make the three smart constructors return branded values.add reject Money values in different currencies.describePayment handle cash-on-delivery (return 'Cash on delivery') and add an exhaustiveness check that fails to compile if a payment kind is ever unhandled, and throws at runtime for an unknown kind.declare const brand: unique symbol; type Brand<T, B extends string> = T & { readonly [brand]: B };.","The smart constructors are the one place to cast: return n as OrderId;. For add, remember why C turns into a union: both arguments are inference sites.","Write function assertNever(value: never): never { throw … } and call it in a default: branch with the narrowed value."],"explanation":"The intersection with a unique symbol property makes each branded type a strict subset of number that no plain number (or other brand) can satisfy, while costing nothing at runtime. Casting only inside validating constructors means every branded value has been checked. Money<NoInfer<C>> makes the second argument check-only, so C comes from the first argument and Money<'EUR'> is rejected. In describePayment, the default branch receives whatever the cases did not handle; when that is nothing, it is never and assertNever compiles, and if a kind slips through at runtime it throws instead of returning undefined.
toOrderId rejects 999 and accepts 1042","adds":"add sums two amounts in the same currency","cash":"describePayment handles cash on delivery","throws-unknown":"describePayment throws for an unknown payment kind"}},"words":729,"readMinutes":3}