Branded Types - TypeScript Expert - ggcoder.com

The Problem: TypeScript Is Structural

TypeScript uses structural typing: two types are compatible if they have the same shape. This means type UserId = string and type PostId = string are completely interchangeable — the compiler will not catch a PostId being passed where a UserId is expected.

structural-problem.ts

1type UserId = string;2type PostId = string;34function getUser(id: UserId): void {5  console.log("fetching user", id);6}78const postId: PostId = "post-42";9getUser(postId); // No error! This is a bug waiting to happen.

A plain type alias does not create a new type — it is just another name for the same underlying type. To create real type-level distinctness with zero runtime cost, we need branded types.

The Brand Pattern: Intersection + Unique Symbol

The core idea is to intersect the base type with a "brand" property that never actually exists at runtime. Because each brand is unique to its type, TypeScript treats them as incompatible.

brand-pattern.ts

1// Using a unique symbol as the brand — each unique symbol is truly distinct2declare const __brand: unique symbol;3type Brand<T, B> = T & { readonly [__brand]: B };45// Alternatively, a simpler string-based brand (less strict but readable)6type UserId = string & { readonly __brand: "UserId" };7type PostId = string & { readonly __brand: "PostId" };89// Now they are incompatible:10declare const userId: UserId;11declare const postId: PostId;1213function getUser(id: UserId): void { /* ... */ }1415getUser(userId); // OK16getUser(postId); // Error: Argument of type 'PostId' is not assignable to parameter of type 'UserId'17getUser("abc");  // Error: plain string is not assignable to UserId

Info

The brand property exists only at the type level. At runtime, a UserId is still a plain string — no __brand property is added to the object. The runtime cost is zero.

Smart Constructors: Controlling Creation

Because you cannot assign a raw string to UserId, you need a smart constructor — a function that performs validation and then uses a type assertion to return the branded type. This is the key insight: every branded value must pass through the validator.

smart-constructors.ts

1type UserId = string & { readonly __brand: "UserId" };2type Email = string & { readonly __brand: "Email" };3type PositiveInt = number & { readonly __brand: "PositiveInt" };45// Smart constructor for UserId — validates UUID format6function UserId(raw: string): UserId {7  if (!/^[0-9a-f-]{36}$/.test(raw)) {8    throw new Error(`Invalid UserId: ${raw}`);9  }10  return raw as UserId; // The only place we use 'as' — gated by validation11}12

You can also use a Result pattern to return errors instead of throwing, or combine branding with a library like Zod for both validation and branding in one step.

Real-World Example: Currency and Units

Branded types are especially valuable for units of measure and currency, where confusing units can cause catastrophic bugs (famously, the 1999 Mars Climate Orbiter crash).

currency-units.ts

1// Currency units — Cents is the canonical internal representation2type Cents = number & { readonly __brand: "Cents" };3type Dollars = number & { readonly __brand: "Dollars" };45function Cents(value: number): Cents {6  if (!Number.isInteger(value) || value < 0) throw new Error("Cents must be a non-negative integer");7  return value as Cents;8}910function Dollars(value: number): Dollars {11  if (value < 0) throw new Error("Dollars must be non-negative");12  return value as Dollars;

Reusable Brand Helper

Rather than repeating the intersection pattern for every branded type, extract it into a reusable Brand<T, B> helper. This is how most large codebases implement branded types.

brand-helper.ts

1// Generic Brand helper2type Brand<T, B extends string> = T & { readonly __brand: B };34// Define all branded types using the helper5type UserId   = Brand<string, "UserId">;6type PostId   = Brand<string, "PostId">;7type Email    = Brand<string, "Email">;8type Cents    = Brand<number, "Cents">;9type Dollars  = Brand<number, "Dollars">;10type Latitude = Brand<number, "Latitude">;11type Longitude = Brand<number, "Longitude">;12

Summary

TypeScript is structural — plain type aliases create no incompatibility between types

The brand pattern intersects a base type with a unique tag: T & { readonly __brand: B }

The brand property is compile-time only — zero runtime cost

Smart constructors are the sole creation point, using a type assertion after validation

Use a Brand<T, B> helper to avoid repeating the intersection pattern

Typical use cases: IDs, validated strings, units of measure, currency, sanitized input

1type UserId = string;2type PostId = string;34function getUser(id: UserId): void {5 console.log("fetching user", id);6}78const postId: PostId = "post-42";9getUser(postId); // No error! This is a bug waiting to happen.

1// Using a unique symbol as the brand — each unique symbol is truly distinct2declare const __brand: unique symbol;3type Brand<T, B> = T & { readonly [__brand]: B };45// Alternatively, a simpler string-based brand (less strict but readable)6type UserId = string & { readonly __brand: "UserId" };7type PostId = string & { readonly __brand: "PostId" };89// Now they are incompatible:10declare const userId: UserId;11declare const postId: PostId;1213function getUser(id: UserId): void { /* ... */ }1415getUser(userId); // OK16getUser(postId); // Error: Argument of type 'PostId' is not assignable to parameter of type 'UserId'17getUser("abc"); // Error: plain string is not assignable to UserId

1type UserId = string & { readonly __brand: "UserId" };2type Email = string & { readonly __brand: "Email" };3type PositiveInt = number & { readonly __brand: "PositiveInt" };45// Smart constructor for UserId — validates UUID format6function UserId(raw: string): UserId {7 if (!/^[0-9a-f-]{36}$/.test(raw)) {8 throw new Error(`Invalid UserId: ${raw}`);9 }10 return raw as UserId; // The only place we use 'as' — gated by validation11}12

1// Currency units — Cents is the canonical internal representation2type Cents = number & { readonly __brand: "Cents" };3type Dollars = number & { readonly __brand: "Dollars" };45function Cents(value: number): Cents {6 if (!Number.isInteger(value) || value < 0) throw new Error("Cents must be a non-negative integer");7 return value as Cents;8}910function Dollars(value: number): Dollars {11 if (value < 0) throw new Error("Dollars must be non-negative");12 return value as Dollars;

1// Generic Brand helper2type Brand<T, B extends string> = T & { readonly __brand: B };34// Define all branded types using the helper5type UserId = Brand<string, "UserId">;6type PostId = Brand<string, "PostId">;7type Email = Brand<string, "Email">;8type Cents = Brand<number, "Cents">;9type Dollars = Brand<number, "Dollars">;10type Latitude = Brand<number, "Latitude">;11type Longitude = Brand<number, "Longitude">;12