Branded types

Two IDs that TypeScript keeps apart

A shop has users and products, and both have IDs. A user ID looks like "u-1" and a product ID looks like "p-7". Both are strings, so TypeScript can't tell them apart, and passing one where the other belongs is an easy mistake. This lesson gives each kind of ID a brand, so TypeScript can:

1type UserId = string & { readonly __brand: "UserId" };2type ProductId = string & { readonly __brand: "ProductId" };3 4function loadUser(id: UserId) {5  return `Loading user ${id}`;6}7 8const userId = "u-1" as UserId;9const productId = "p-7" as ProductId;10 11console.log(loadUser(userId));12console.log(loadUser(productId));

Line 1 makes a type called UserId. Read it as "a string that also carries the brand "UserId"". Line 2 does the same for ProductId. Lines 4 to 6 are a function that loads a user, so it asks for a UserId. Lines 8 and 9 make one ID of each kind. The as in "u-1" as UserId says "treat this text as a UserId"; a later section explains it.

Line 11 passes the user ID and prints Loading user u-1. Line 12 passes the product ID, and TypeScript marks it, on purpose here: Argument of type 'ProductId' is not assignable to parameter of type 'UserId'. In plain words: "you passed a product ID, and this function wants a user ID". Run it anyway, and it prints Loading user p-7: the wrong record, with no warning. With the brand, the mistake is caught before the code runs.

Why look-alike values get mixed up

Why does TypeScript need help here? A type alias like type Cents = number gives a type a second name, and nothing more (the Type aliases & interfaces lesson covers this). Here a shop stores prices in cents, but one price was written in dollars:

1type Cents = number;2type Dollars = number;3 4function chargeCard(amount: Cents) {5  return `Charging ${amount} cents`;6}7 8const price: Dollars = 4.5;9//    ^?10console.log(chargeCard(price));

Lines 1 and 2 name two units. Line 4 says chargeCard takes Cents. Line 8 makes a price of 4.5 dollars. The query on line 9 shows what TypeScript sees: const price: number. The name Dollars is already gone, because it only ever meant number. Line 10 passes the dollars to chargeCard with no error, and prints Charging 4.5 cents. The customer pays 4 and a half cents instead of 4.50 dollars.

This is structural typing at work: TypeScript compares types by what they contain, not by their names (the Structural typing lesson covers it). Cents and Dollars both contain "a number", so they are the same type. The same goes for UserId and ProductId as plain strings. To keep them apart, their types must contain something different.

One way is to wrap each value in an object, like { kind: "user", value: "u-1" }. That works, but now every ID is an object when the code runs: you write .value everywhere, and the server's plain strings must be wrapped first. A brand keeps the value a plain string and changes only the type.

Adding a brand to a type

A brand is built from something you know: an intersection, A & B, a value that is an A and a B at the same time (the Intersection types lesson covers it). Here is what a plain string can and can't do with a branded type:

1type UserId = string & { readonly __brand: "UserId" };2 3const fromText: UserId = "u-1";4const fromAs = "u-1" as UserId;5 6console.log(fromAs.toUpperCase());7console.log(fromAs.length);

Line 1 has three parts:

• string: a UserId is a string.
• { readonly __brand: "UserId" }: and it has a property called __brand whose type is exactly the text "UserId". readonly means no code may change it. The two underscores are a habit that says "not a real property, don't use it".
• &: both at once.

No real string has a __brand property, so line 3 gets an error, on purpose: Type 'string' is not assignable to type 'UserId'. The next line of the message says why: Type 'string' is not assignable to type '{ readonly __brand: "UserId"; }'. The text is a string, but it has no brand.

So how do you ever make a UserId? Line 4 uses as, a type assertion: you tell TypeScript "trust me, this is a UserId", and it does (the Type assertions lesson covers as). Lines 6 and 7 show that a UserId is still a string: toUpperCase() prints U-1, and length prints 3.

Now try different values. Each button changes what line 10 passes to loadUser:

1type UserId = string & { readonly __brand: "UserId" };2type ProductId = string & { readonly __brand: "ProductId" };3 4function loadUser(id: UserId) {5  return `Loading user ${id}`;6}7 8const userId = "u-1" as UserId;9const productId = "p-7" as ProductId;10console.log(loadUser(userId));

Only two values fit: a value that already is a UserId, and text that you assert is one. A product ID and plain text are both errors. Even productId as UserId is refused: Conversion of type 'ProductId' to type 'UserId' may be a mistake means no value can be both, because the two brands can never match.

Writing string & { readonly __brand: … } for every brand gets long. A small generic type, a type with a parameter, writes it once (the Generic types & interfaces lesson covers them):

1type Brand<T, Name extends string> = T & { readonly __brand: Name };2 3type UserId = Brand<string, "UserId">;4type OrderId = Brand<string, "OrderId">;5type Cents = Brand<number, "Cents">;6 7const orderId = "o-42" as OrderId;8//    ^?9const price = 450 as Cents;10console.log(orderId, price);

Line 1 says: Brand takes a type T and a name, and gives back T with that name as its brand. Name extends string means the name must be text. Lines 3 to 5 make three brands with it, two on strings and one on a number. The query on line 8 shows const orderId: OrderId, and line 10 prints o-42 450.

The table below compares the three ways to keep IDs apart. Read each row as a question, then each way's answer.

Hiding the brand with unique symbol

The brand only exists in the types. That's what makes it free when the code runs, but it also means the __brand property is a promise nobody keeps:

1type UserId = string & { readonly __brand: "UserId" };2 3const userId = "u-1" as UserId;4const brandName = userId.__brand;5//    ^?6console.log(brandName);7console.log(typeof userId);

Line 4 reads userId.__brand, and TypeScript allows it. The query on line 5 says const brandName: "UserId". But line 6 prints undefined, and line 7 prints string: when the code runs, userId is the plain string "u-1", with no properties of its own.

Your editor also suggests __brand after every userId., which invites mistakes like line 4. A common fix is to name the brand's property with a symbol that only one file can see. In JavaScript, every Symbol() is a new value equal to no other, and it can be a property's key (the Symbols lesson covers them). Here the brand lives in a file of its own:

1declare const brand: unique symbol;2 3export type Brand<T, Name extends string> = T & { readonly [brand]: Name };

Line 1 says "there is a constant called brand, and its type is unique symbol": a type that only this one symbol has. declare means the line only describes it, and makes no value; it is removed with the types (the Declaration files lesson covers declare). Line 3 builds the Brand helper with [brand] as the property's key. The file exports Brand, but not brand.

1import type { Brand } from "./brand";2 3type UserId = Brand<string, "UserId">;4type ProductId = Brand<string, "ProductId">;5 6function loadUser(id: UserId) {7  return `Loading user ${id}`;8}9 10const productId = "p-7" as ProductId;11console.log(loadUser(productId));12console.log(productId.__brand);

Line 1 imports only the type. Lines 3 and 4 make two brands, and line 11 still catches the mix-up, on purpose. This time the message says Types of property '[brand]' are incompatible. Line 12 shows the difference, also on purpose: Property '__brand' does not exist on type 'ProductId'. There is no __brand to read or suggest, and ids.ts has no way to name brand, because brand.ts never exported it. Run it anyway, and it prints Loading user p-7 and undefined, as before: the symbol changes the types, not the values.

Constructor functions: the one way in

as UserId checks nothing. You could write "hello" as UserId and TypeScript would believe you. So most projects allow as in exactly one place for each brand: a function that checks the value first. People call it a constructor function or a smart constructor. It's a plain function; it has nothing to do with a class's constructor or with new.

1type Email = string & { readonly __brand: "Email" };2 3function toEmail(text: string): Email {4  const email = text.trim().toLowerCase();5  if (!/^\S+@\S+\.\S+$/.test(email)) {6    throw new Error(`Not an email: "${text}"`);7  }8  return email as Email;9}10 11function sendReceipt(to: Email) {12  return `Receipt sent to ${to}`;13}14 15const email = toEmail(" Asha@Example.com ");16//    ^?17console.log(sendReceipt(email));

Line 1 is the brand. Lines 3 to 9 are the constructor, toEmail. Line 4 removes spaces at both ends and makes the letters small. Line 5 tests the text against a regular expression, a pattern for text (the Patterns & flags lesson covers them). \S+@\S+\.\S+ means "some characters that aren't spaces, an @, more of them, a dot, and more". If the text doesn't match, line 6 throws an error. Only text that passed reaches line 8, the one as Email.

Lines 11 to 13 are sendReceipt, which asks for an Email. Line 15 makes one from messy text, and the query on line 16 shows const email: Email. Line 17 prints Receipt sent to asha@example.com.

Now type your own text. Only line 16 changes, and the console shows what the code prints:

1type Email = string & { readonly __brand: "Email" };2 3function toEmail(text: string): Email {4  const email = text.trim().toLowerCase();5  if (!/^\S+@\S+\.\S+$/.test(email)) {6    throw new Error(`Not an email: "${text}"`);7  }8  return email as Email;9}10 11function sendReceipt(to: Email) {12  return `Receipt sent to ${to}`;13}14 15try {16  const email = toEmail(" Asha@Example.com ");17  console.log(sendReceipt(email));18} catch (error) {19  console.log(error instanceof Error ? error.message : error);20}

Notice that the type checker never complains here. It can't know whether some text is an email; only the running code can find that out. The brand's job is different: it makes sure every Email in your program went through that check.

Throwing isn't always what you want. In a form, you'd rather show a message. A type guard, a function whose return type is value is Type, checks the text and narrows it, with no error to catch (the Type predicates & assertion functions lesson covers them):

1type Email = string & { readonly __brand: "Email" };2 3function isEmail(text: string): text is Email {4  return /^\S+@\S+\.\S+$/.test(text);5}6 7function sendReceipt(to: Email) {8  return `Receipt sent to ${to}`;9}10 11function submit(typed: string) {12  if (isEmail(typed)) {13    return sendReceipt(typed);14    //                 ^?15  }16  return `Please check ${typed}`;17}18 19console.log(submit("ravi@example.com"));20console.log(submit("ravi"));

Line 3 says isEmail returns text is Email: when it returns true, TypeScript treats the text as an Email. Inside the if on line 12, the query on line 14 shows (parameter) typed: Email, so line 13 can call sendReceipt. Line 19 prints Receipt sent to ravi@example.com, and line 20 prints Please check ravi. This guard has no as at all: the predicate does the branding.

Here is what happens when as leaks out of the constructor:

1type Email = string & { readonly __brand: "Email" };2 3function sendReceipt(to: Email) {4  return `Receipt sent to ${to}`;5}6 7const wrong = "not an email" as Email;8console.log(sendReceipt(wrong));

Line 7 asserts that "not an email" is an Email. There are no errors, and line 8 prints Receipt sent to not an email. A brand is only as good as the code that creates it, so keep each as Email inside the function that checks.

Units: cents are not dollars

Brands work on numbers too. Shops often store money as whole cents, because numbers with a decimal point can be slightly off (0.1 + 0.2 is 0.30000000000000004; the Number & Math in depth lesson explains why). Here are the cents and dollars from before, with brands:

1type Cents = number & { readonly __brand: "Cents" };2type Dollars = number & { readonly __brand: "Dollars" };3 4function dollarsToCents(amount: Dollars): Cents {5  return Math.round(amount * 100) as Cents;6}7 8function chargeCard(amount: Cents) {9  return `Charging ${amount} cents`;10}11 12const price = 4.5 as Dollars;13console.log(chargeCard(price));14console.log(chargeCard(dollarsToCents(price)));

Lines 1 and 2 brand two numbers. Lines 4 to 6 convert: dollarsToCents takes Dollars, multiplies by 100, rounds to a whole number with Math.round, and brands the result as Cents. Line 13 makes the same mistake as before, and this time TypeScript marks it, on purpose: Argument of type 'Dollars' is not assignable to parameter of type 'Cents'. Line 14 converts first, and prints Charging 450 cents.

Brands have one surprise with numbers. Math gives back a plain number:

1type Cents = number & { readonly __brand: "Cents" };2 3function addCents(a: Cents, b: Cents): Cents {4  return (a + b) as Cents;5}6 7const tea = 300 as Cents;8const cake = 450 as Cents;9const sum = tea + cake;10//    ^?11const total = addCents(tea, cake);12//    ^?13console.log(sum, total);

Line 9 adds two Cents, and the query on line 10 shows const sum: number. TypeScript knows that + on two numbers gives a number, but not that cents plus cents is still cents, so the brand is gone. Lines 3 to 5 are a small helper that adds and puts the brand back, so the query on line 12 shows const total: Cents. Line 13 prints 750 750: the same value, with different types.

The same idea works for any value with rules: a Percent from 0 to 100, a Quantity that is a whole number, a Slug made of small letters and dashes for a web address, or an Email. Each gets a brand and one function that checks and brands.

IDs and prices in a shopping cart

Here is how the pieces fit in a real cart. The server sends plain data. One function per brand checks it as it comes in, and from then on, the types carry the checks with them:

1type ProductId = string & { readonly __brand: "ProductId" };2type Cents = number & { readonly __brand: "Cents" };3 4function toProductId(text: string): ProductId {5  if (!text.startsWith("p-")) throw new Error(`Not a product id: ${text}`);6  return text as ProductId;7}8 9function checkCents(amount: number): Cents {10  if (!Number.isInteger(amount) || amount < 0) throw new Error(`Not a price in cents: ${amount}`);11  return amount as Cents;12}13 14type CartLine = { id: ProductId; price: Cents; quantity: number };15 16function readLine(item: { id: string; price: number; quantity: number }): CartLine {17  return { id: toProductId(item.id), price: checkCents(item.price), quantity: item.quantity };18}19 20function lineTotal(line: CartLine): Cents {21  return checkCents(line.price * line.quantity);22}23 24const reply = [{ id: "p-7", price: 450, quantity: 2 }, { id: "p-9", price: 300, quantity: 1 }];25const cart = reply.map(readLine);26for (const line of cart) {27  console.log(`${line.id}: ${lineTotal(line)} cents`);28}

Lines 1 and 2 are the brands. Lines 4 to 7 and 9 to 12 are their constructors: a product ID must start with p-, and a price must be a whole number of cents, 0 or more. Line 14 is a cart line that uses both brands. Lines 16 to 18, readLine, turn one plain item from the server into a CartLine, checking each field on the way.

Line 24 stands in for the server's reply. In a real app, it comes from response.json(), and you check its shape first (the Typing fetch & JSON lesson shows how). Line 25 reads every item. Lines 20 to 22 compute a line's total, and use checkCents to brand the result of the multiplication. Lines 26 to 28 print p-7: 900 cents and p-9: 300 cents.

Everything after line 25 can trust the cart: every id is a checked ProductId, and every price is a whole number of cents. The checks happen once, at the edge of the program, instead of in every function.

Now sort some lines. Each one is checked after these lines:

1type UserId = string & { readonly __brand: "UserId" };2type OrderId = string & { readonly __brand: "OrderId" };3type Cents = number & { readonly __brand: "Cents" };4 5const userId = "u-1" as UserId;6const orderId = "o-42" as OrderId;7const price = 450 as Cents;8console.log(userId, orderId, price);

Common mix-ups

Most mix-ups about brands come from forgetting that they are only types. Here is a user with a branded ID, as the code sees it when it runs:

1type UserId = string & { readonly __brand: "UserId" };2 3const user = { id: "u-1" as UserId, name: "Asha" };4console.log(typeof user.id);5console.log(JSON.stringify(user));

Line 3 makes a user whose id is a UserId. Line 4 prints string. Line 5 turns the user into JSON text and prints {"id":"u-1","name":"Asha"}: no brand anywhere. When that JSON comes back from a server, the ID is a plain string again, and needs its constructor (the JSON lesson covers JSON.stringify).

• "A brand checks the value." No. A brand only records that some code said the value is right. The check is the constructor's job, and as skips it.
• "A branded value has a __brand property." No. The property exists only in the types. Reading it gives undefined.
• "type UserId = string already keeps IDs apart." No. An alias is a second name for string, and any string fits.
• "Math on Cents gives Cents." No. It gives a plain number. Put the brand back with a helper like addCents.
• "A branded string can't be used as a string." No. It fits anywhere a string goes, and every string method works on it. Only the other direction is blocked.
• "Brands cost something when the code runs." No. The value is the same plain string or number, with nothing added. The constructor's check is the only extra work.

Practice exercises

Each exercise is TypeScript. When you fix 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.

type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };

function cancelOrder(id: OrderId) {
  return `Cancelled ${id}`;
}

const userId = "u-1" as UserId;
const orderId = "o-42" as OrderId;
console.log(cancelOrder(orderId));
console.log(cancelOrder(userId));

1type UserId = string & { readonly __brand: "UserId" };2type OrderId = string & { readonly __brand: "OrderId" };3 4function cancelOrder(id: OrderId) {5  return `Cancelled ${id}`;6}7 8const userId = "u-1" as UserId;9const orderId = "o-42" as OrderId;10console.log(cancelOrder(orderId));11console.log(`Signed in as ${userId}`);

1type Cents = number & { readonly __brand: "Cents" };2 3const tea = 300 as Cents;4const twoTeas = tea * 2;

1type Cents = number & { readonly __brand: "Cents" };2 3const tea = 300 as Cents;4const twoTeas = tea * 2;5//    ^?

1type UserId = string & { readonly __brand: "UserId" };2type OrderId = string & { readonly __brand: "OrderId" };3type Cents = number & { readonly __brand: "Cents" };4 5const orderId = "o-42" as OrderId;6console.log(orderId);

1type Brand<T, Name extends string> = T & { readonly __brand: Name };2 3type UserId = Brand<string, "UserId">;4type OrderId = Brand<string, "OrderId">;5type Cents = Brand<number, "Cents">;6 7const orderId = "o-42" as OrderId;8//    ^?9console.log(orderId);

1type Quantity = number & { readonly __brand: "Quantity" };2 3function toQuantity(n: number): Quantity {4  // Throw unless n is a whole number from 1 to 99.5  return n as Quantity;6}7 8for (const n of [2, 0, 2.5]) {9  try {10    console.log(`Added ${toQuantity(n)}`);11  } catch (error) {12    console.log(error instanceof Error ? error.message : error);13  }14}

1type Quantity = number & { readonly __brand: "Quantity" };2 3function toQuantity(n: number): Quantity {4  if (!Number.isInteger(n) || n < 1 || n > 99) {5    throw new Error(`Not a quantity: ${n}`);6  }7  return n as Quantity;8}9 10for (const n of [2, 0, 2.5]) {11  try {12    console.log(`Added ${toQuantity(n)}`);13  } catch (error) {14    console.log(error instanceof Error ? error.message : error);15  }16}

1type Slug = string & { readonly __brand: "Slug" };2 3function isSlug(text: string): boolean {4  return /^[a-z0-9-]+$/.test(text);5}6 7function pageUrl(slug: Slug) {8  return `/blog/${slug}`;9}10 11function linkFor(title: string) {12  const text = title.toLowerCase().replaceAll(" ", "-");13  return isSlug(text) ? pageUrl(text) : "No link";14}15 16console.log(linkFor("Hello World"));17console.log(linkFor("Tea & Cake"));

1type Slug = string & { readonly __brand: "Slug" };2 3function isSlug(text: string): text is Slug {4  return /^[a-z0-9-]+$/.test(text);5}6 7function pageUrl(slug: Slug) {8  return `/blog/${slug}`;9}10 11function linkFor(title: string) {12  const text = title.toLowerCase().replaceAll(" ", "-");13  return isSlug(text) ? pageUrl(text) : "No link";14}15 16console.log(linkFor("Hello World"));17console.log(linkFor("Tea & Cake"));

1type Cents = number;2type Dollars = number;3 4function dollarsToCents(amount: Dollars): Cents {5  return Math.round(amount * 100);6}7 8function chargeCard(amount: Cents) {9  return `Charging ${amount} cents`;10}11 12const price: Dollars = 4.5;13console.log(chargeCard(price));

1type Cents = number & { readonly __brand: "Cents" };2type Dollars = number & { readonly __brand: "Dollars" };3 4function dollarsToCents(amount: Dollars): Cents {5  return Math.round(amount * 100) as Cents;6}7 8function chargeCard(amount: Cents) {9  return `Charging ${amount} cents`;10}11 12const price = 4.5 as Dollars;13console.log(chargeCard(dollarsToCents(price)));

Check your understanding

For each question, ask two things: what does the checker see, brand and all, and what does the code do when it runs, after the types are gone? The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• TypeScript compares types by shape, so type UserId = string and type ProductId = string are the same type.
• A brand, string & { readonly __brand: "UserId" }, adds a marker only the checker sees, so look-alike values stop fitting each other.
• A Brand<T, Name> helper writes it once. A unique symbol key that its file doesn't export hides the brand from other files.
• Make branded values in one place: a constructor that checks and throws, or a type guard. Keep as inside it.
• Math on a branded number gives a plain number; a small helper puts the brand back.
• When the code runs, a brand is gone: the value is the same plain string or number, and data from a server needs its constructor again.

Coming next: Type-safe APIs & routes. One description of a server's routes types the client, the path's parameters, and every response.