TypeScript 42 🔷 Branded Types and Nominal Typing Tricks
TypeScript’s type system is structural, not nominal. This is a deliberate design choice that matches how JavaScript is typically written — objects and functions are compared by their shape, not by their declared name. But structural typing has a real cost: two values that are structurally identical are interchangeable to the compiler, even when they represent completely different concepts. A UserId and an OrderId are both strings. A Meter and a Second are both numbers. A validated email and a raw user input are both strings. TypeScript sees no difference, so passing the wrong one compiles cleanly and fails at runtime. Branded types are the community’s answer: a pattern that adds a phantom tag to a type, making it nominally distinct to the compiler while remaining structurally identical at runtime. This chapter covers what branded types are, how to create them, the different branding techniques and their tradeoffs, how to combine them with runtime validation, and when they are worth the ceremony.
Key point: A branded type is an intersection of a base type with a phantom property — a property that exists only in the type system, never at runtime. type UserId = string & { readonly __brand: "UserId" } is still a string at runtime, but TypeScript treats it as distinct from plain string and from other branded strings. The brand is a compile-time fiction. A constructor function is the only sanctioned way to produce one, and that function is where validation belongs. The unique symbol technique is the most robust because each symbol is genuinely unique across modules. Branded types turn documentation conventions (“this argument is a user ID”) into compiler-enforced invariants.
Why structural typing fails for domain primitives
The structural rule is simple: if x has all the members that y requires, x is assignable to y. Dog is assignable to Animal if Dog has every property Animal has. Extra properties do not matter. This works beautifully for object shapes — it is why JavaScript code and TypeScript interfaces fit together with almost no friction.
The failure is with primitives and near-primitives. A string is a string. There is no shape to compare beyond the primitive itself. So getUser(productId) compiles when both are typed string, even though the intent is clearly wrong. The compiler has no information to reject it. The same applies to numbers: addMeters(seconds) is structurally valid.
Why this is not a bug in TypeScript. The alternative — a nominal system like Java or C# — would require every type to be explicitly declared and named, which would break the anonymous object patterns that JavaScript relies on. TypeScript chose structural compatibility for ergonomics. Branded types are a targeted patch for the specific cases where structural compatibility is dangerous.
Where the danger concentrates. IDs, tokens, validated strings, units of measure, and any value where the semantic meaning matters more than the structural shape. These are the cases where a swap compiles, runs, and produces subtly wrong results.
Why the compiler cannot help without branding. TypeScript has no way to know that one string is a user ID and another is an order ID. The names of variables and parameters are not part of the type. Branding adds that information to the type itself, where the compiler can use it.
The unique symbol technique
The most robust branding technique uses a unique symbol as the phantom property key. A unique symbol is a symbol whose type is tied to its declaration and is never equal to any other symbol type, even across module boundaries when imported.
declare const UserIdBrand: unique symbol;
declare const OrderIdBrand: unique symbol;
type UserId = string & { readonly [UserIdBrand]: typeof UserIdBrand };
type OrderId = string & { readonly [OrderIdBrand]: typeof OrderIdBrand };The [UserIdBrand] computed property key is the brand. Because UserIdBrand is a unique symbol, no other brand can accidentally use the same key. The property is readonly to signal that it is never assigned. At runtime, the property does not exist — it is a type-level fiction.
Constructor functions complete the pattern. The brand is created only through a function that casts the raw value.
function createUserId(id: string): UserId {
return id as UserId;
}
function createOrderId(id: string): OrderId {
return id as OrderId;
}The function is intentionally simple here; validation is added in the next section. The point is that the cast is centralized. Direct as UserId casts scattered through the codebase undermine the pattern.
Why unique symbol is preferred over string literals. A brand like { readonly __brand: "UserId" } uses a string literal as the key. Two different developers could independently define a brand with the same string "UserId" for incompatible purposes, and the types would merge. A unique symbol cannot be duplicated. The TypeScript team’s own compiler uses the _fooIdBrand interface pattern, but the community consensus for new code is unique symbol.
const userId = createUserId("user-123");
const orderId = createOrderId("order-456");
processOrder(userId, orderId); // ✅
processOrder(orderId, userId); // ❌ OrderId is not assignable to UserId
processOrder("user-123", orderId); // ❌ string is not assignable to UserIdThe compiler now enforces the distinction that was previously only in the developer’s head.
A reusable Brand helper
Writing the intersection type for every branded primitive is repetitive. A generic helper collapses it to one line per brand.
declare const __brand: unique symbol;
type Brand<T, TBrand extends string> = T & { readonly [__brand]: TBrand };
type UserId = Brand<string, "UserId">;
type OrderId = Brand<string, "OrderId">;
type Email = Brand<string, "Email">;
type PositiveNumber = Brand<number, "PositiveNumber">;Brand<T, TBrand> takes a base type and a brand name, and produces the intersection. The __brand symbol is a single shared key; the TBrand string parameter distinguishes the resulting types. This is the pattern most libraries and codebases converge on because it is concise without losing the uniqueness guarantee.
Why the brand name is a string literal, not a unique symbol, in this helper. The __brand key itself is unique symbol, which prevents cross-library collisions. The TBrand parameter is a string literal that names the brand within this project. Two different brands in the same project cannot share a name, and two different projects using different __brand symbols cannot collide.
Limitation of the string-literal brand. A determined developer can still write string & { readonly [__brand]: "UserId" } manually and produce a type that TypeScript considers identical to Brand<string, "UserId">. This is a minor concern in practice — the helper is a convention that the team follows, and the compiler checks the result. If absolute cross-module uniqueness is required, the per-brand unique symbol technique is the answer.
Runtime validation with branded constructors
A branded type is a promise that the value has been validated. Without validation, the brand is a lie — a string that has been cast to UserId but might be "not-a-user-id". The constructor function is where the validation belongs.
type Email = Brand<string, "Email">;
function createEmail(input: string): Email {
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
if (!emailRegex.test(input)) {
throw new Error(`Invalid email format: ${input}`);
}
return input as Email;
}The function either returns a value the compiler knows is an Email or throws. There is no path that returns an unvalidated Email. Callers cannot construct one any other way without an explicit cast, which is a visible red flag in review.
Positive numbers and units of measure follow the same pattern. createPositiveNumber(-1) throws; createPositiveNumber(5) returns PositiveNumber. The type carries the invariant, and the constructor enforces it.
Why validation belongs at the boundary. The raw value enters the system as a plain string from an HTTP request, a file, or user input. The constructor is called once at that boundary. Inside the system, every function that accepts Email can trust the invariant without re-validating. This is the same principle as parsing JSON once at the edge instead of checking shapes deep in the application.
// At the boundary
const rawEmail = req.body.email;
const email = createEmail(rawEmail); // throws if invalid
// Inside the system
function sendNewsletter(to: Email): void {
// no validation needed — the type guarantees it
}Why throwing is the right behavior for constructors. Returning
Email | nullforces every caller to handle the failure, which pushes validation logic everywhere. Throwing at the boundary and using a try/catch or a Result type at the edge keeps the interior clean. The branded type is for the validated region, not the raw-input region.
Branded types in API responses and Express
The Express example is one of the most concrete uses of branded types. A route handler receives a raw string from req.params, and the first thing it does is convert it to a branded type before passing it to the service layer.
app.get('/users/:userId', (req, res) => {
const rawUserId = req.params.userId;
const userId = createUserId(rawUserId); // branded
const user = getUserById(userId);
res.json(user);
});The service function getUserById accepts UserId, not string. If someone later writes a route that passes a raw req.params.somethingElse without converting, the compiler rejects it. This prevents a class of bug where the wrong parameter name is used and the raw string is passed through.
Response types benefit too. If UserResponse.id is typed UserId and PostResponse.authorId is typed UserId, the frontend receives the distinction through the generated types. A component that expects UserId cannot accidentally receive an OrderId from a response object.
Session tokens are another natural fit. SessionToken is a branded string that cannot be confused with UserId or a raw string. The token is generated once, branded, stored in a response, and verified in subsequent requests.
When to brand and when not to
Branded types are not free. They add constructor functions, import requirements, and a layer of indirection at every boundary. The cost is justified when the semantic distinction is real and the failure mode is silent.
When branding is worth it:
- Two primitives of the same underlying type represent different concepts (
UserIdvsOrderId,MetervsSecond) - A value must pass validation before use (
Email,PositiveNumber,ISODateString) - A value must not be confused with a raw primitive (
ValidatedInputStringvsstring) - The cost of a swap is high (database queries with wrong IDs, financial calculations with wrong units)
When branding adds noise without benefit:
- The value is genuinely just a string with no invariant (display names, free-text comments)
- The code is a throwaway script where the ceremony exceeds the safety
- The team is not bought in — one person doing
as UserIddefeats the pattern for everyone - A union or template literal type already expresses the constraint better (a
TaskStatusthat is one of three known values is a union, not a branded string)
The union-type alternative. If the set of allowed values is known and finite, a union of string literals is more precise than a brand. type TaskStatus = "pending" | "rejected" | "resolved" catches typos at compile time because "rejecting" is not in the union. A branded string would not. Choose the tool that matches the constraint: brands for “any string that has passed validation,” unions for “one of these specific strings.”
Complete Example Session
// ============================================
// PART 1: THE PROBLEM
// ============================================
function processOrder(userId: string, orderId: string) {
// ...
}
const userId = "user-123";
const orderId = "order-456";
processOrder(orderId, userId); // ✅ compiles, ❌ logically wrong
// ============================================
// PART 2: BRAND HELPER
// ============================================
declare const __brand: unique symbol;
type Brand<T, TBrand extends string> = T & { readonly [__brand]: TBrand };
// ============================================
// PART 3: BRANDED TYPES
// ============================================
type UserId = Brand<string, "UserId">;
type OrderId = Brand<string, "OrderId">;
type Email = Brand<string, "Email">;
type PositiveNumber = Brand<number, "PositiveNumber">;
// ============================================
// PART 4: CONSTRUCTORS WITH VALIDATION
// ============================================
function createUserId(id: string): UserId {
if (!id.startsWith("user-")) {
throw new Error("Invalid user ID format");
}
return id as UserId;
}
function createOrderId(id: string): OrderId {
if (!id.startsWith("order-")) {
throw new Error("Invalid order ID format");
}
return id as OrderId;
}
function createEmail(input: string): Email {
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
if (!emailRegex.test(input)) {
throw new Error(`Invalid email format: ${input}`);
}
return input as Email;
}
function createPositiveNumber(value: number): PositiveNumber {
if (value <= 0) {
throw new Error(`Number must be positive: ${value}`);
}
return value as PositiveNumber;
}
// ============================================
// PART 5: TYPE-SAFE USAGE
// ============================================
function processOrderSafe(userId: UserId, orderId: OrderId) {
console.log(`Processing order ${orderId} for user ${userId}`);
}
const uid = createUserId("user-123");
const oid = createOrderId("order-456");
processOrderSafe(uid, oid); // ✅
// processOrderSafe(oid, uid); // ❌ OrderId is not UserId
// processOrderSafe("user-123", oid); // ❌ string is not UserId
// ============================================
// PART 6: VALIDATION THROWS
// ============================================
try {
createEmail("not-an-email");
} catch (e) {
console.log((e as Error).message); // Invalid email format
}
const validEmail = createEmail("user@example.com"); // ✅
// ============================================
// PART 7: BRANDED NUMBERS
// ============================================
function divide(a: number, b: PositiveNumber): number {
return a / b;
}
const positive = createPositiveNumber(5);
divide(10, positive); // ✅
// divide(10, 0); // ❌ number is not PositiveNumber
// ============================================
// PART 8: DATES
// ============================================
type ISODateString = Brand<string, "ISODateString">;
function createISODateString(date: Date): ISODateString {
return date.toISOString() as ISODateString;
}
function saveEvent(eventDate: ISODateString, title: string) {
console.log(`Saving event: ${title} at ${eventDate}`);
}
const now = new Date();
const isoDate = createISODateString(now);
saveEvent(isoDate, "Team Meeting"); // ✅
// saveEvent(now.toLocaleDateString(), "Team Meeting"); // ❌ string is not ISODateString
// ============================================
// PART 9: THE `unique symbol` VARIANT
// ============================================
declare const UserIdBrand: unique symbol;
declare const OrderIdBrand: unique symbol;
type StrictUserId = string & { readonly [UserIdBrand]: typeof UserIdBrand };
type StrictOrderId = string & { readonly [OrderIdBrand]: typeof OrderIdBrand };
// These are not assignable to each other or to the Brand<> versions
// unless explicitly cast
// ============================================
// PART 10: LIMITS
// ============================================
// Branded types do not survive serialization
const json = JSON.stringify(uid);
// json is just '"user-123"' — the brand is compile-time only
// Branded types do not protect against `as` casts
const fake = "anything" as UserId; // compiles — do not do thisEach part isolates one branded-type concept. Parts 1 through 5 show the core pattern, parts 6 through 8 show validation and real domains, part 9 shows the stricter unique symbol variant, and part 10 names the limits.
Quick Reference
Branding Techniques
| Technique | Example | Uniqueness |
|---|---|---|
unique symbol | string & { [sym]: void } | ✅ Strongest |
| String literal key | string & { __brand: "UserId" } | ⚠️ Collision possible |
| Enum brand | enum B {}; string & B | ✅ Good |
| Interface brand | interface B { _brand: string } | ✅ Good |
Brand<T, Name> helper | Brand<string, "UserId"> | ✅ Practical |
Creating a Brand
| Step | Code |
|---|---|
| Declare symbol | declare const __brand: unique symbol; |
| Define helper | type Brand<T, B extends string> = T & { readonly [__brand]: B }; |
| Define type | type UserId = Brand<string, "UserId">; |
| Constructor | function createUserId(s: string): UserId { ... return s as UserId; } |
| Use | function f(id: UserId) { ... } |
Assignability
| From | To | Allowed? |
|---|---|---|
UserId | string | ✅ (branded extends base) |
string | UserId | ❌ |
UserId | OrderId | ❌ |
UserId | UserId | ✅ |
OrderId | UserId | ❌ |
When to Brand
| Situation | Brand? |
|---|---|
Two same-type concepts (UserId vs OrderId) | ✅ |
Value must be validated (Email, PositiveNumber) | ✅ |
Unit of measure (Meter, Second) | ✅ |
| Genuinely just a string (display name) | ❌ |
| Known finite set of values | ❌ (use union) |
| Throwaway script | ❌ |
Brand vs Union
| Need | Tool |
|---|---|
| “Any validated string” | Brand |
| “One of three specific strings” | Union |
| “String matching a pattern” | Template literal type |
| “Number that is positive” | Brand |
Best Practices
✅ Do This:
// Use a shared Brand helper
declare const __brand: unique symbol;
type Brand<T, B extends string> = T & { readonly [__brand]: B }; // ✅
// Centralize construction in a validated function
function createEmail(s: string): Email {
if (!isValidEmail(s)) throw new Error("Invalid email");
return s as Email;
} // ✅
// Call the constructor at system boundaries only
const email = createEmail(req.body.email); // ✅
// Use unique symbols for brands that cross module boundaries
declare const UserIdBrand: unique symbol; // ✅
// Combine with Zod for schema validation
const UserIdSchema = z.string().startsWith("user-").brand("UserId"); // ✅❌ Don’t Do This:
// Don't scatter `as UserId` casts
const id = raw as UserId; // ⚠️ defeats the pattern
// Don't brand values with no invariant
type DisplayName = Brand<string, "DisplayName">; // ⚠️ noise
// Don't use a brand where a union is more precise
type Status = Brand<string, "Status">; // ⚠️ use "pending" | "done"
// Don't assume the brand survives serialization
JSON.parse(JSON.stringify(userId)); // ⚠️ brand lost
// Don't forget validation in the constructor
function createUserId(s: string): UserId {
return s as UserId; // ⚠️ no validation
}Common Pitfalls
| Pitfall | Problem | Solution |
|---|---|---|
| Unvalidated constructor | Brand is a lie | Add validation before cast |
as UserId everywhere | Pattern undermined | Constructor is the only cast |
| Brand on serialization | Brand lost in JSON | Re-brand after parse |
| Union confused with brand | Imprecise | Use union for finite sets |
| String-literal brand collision | Two “UserId” brands merge | Use unique symbol |
| Over-branding | Ceremony exceeds value | Brand only where swaps are dangerous |
| No helper, repeated intersections | Verbose and error-prone | Define Brand<T, B> once |
| Team not using constructors | One as defeats all | Enforce in review, lint |
Real-World Examples
1. User ID vs Order ID
type UserId = Brand<string, "UserId">;
type OrderId = Brand<string, "OrderId">;
function getOrder(userId: UserId, orderId: OrderId) {}2. Validated email
type Email = Brand<string, "Email">;
function createEmail(s: string): Email { /* regex check */ }3. Positive number
type PositiveNumber = Brand<number, "PositiveNumber">;
function createPositiveNumber(n: number): PositiveNumber { /* n > 0 */ }4. ISO date string
type ISODateString = Brand<string, "ISODateString">;
function createISODateString(d: Date): ISODateString {
return d.toISOString() as ISODateString;
}5. Express route parameter
app.get('/users/:userId', (req, res) => {
const userId = createUserId(req.params.userId);
const user = getUserById(userId);
});6. Session token
type SessionToken = Brand<string, "SessionToken">;
function createSessionToken(t: string): SessionToken { /* ... */ }7. Meter vs Second
type Meter = Brand<number, "Meter">;
type Second = Brand<number, "Second">;8. Zod integration
const UserIdSchema = z.string().startsWith("user-").brand("UserId");
type UserId = z.infer<typeof UserIdSchema>;9. Safe divide
function divide(a: number, b: PositiveNumber): number {
return a / b;
}10. Validated input string
type ValidatedInputString = string & { __brand: "User Input Post Validation" };
function validateUserInput(s: string): ValidatedInputString { /* ... */ }Visual: Structural vs Nominal Typing
┌────────────────────────────────────────────────────────┐
│ STRUCTURAL (TypeScript default) │
│ │
│ interface Ball { diameter: number } │
│ interface Sphere { diameter: number } │
│ │
│ let ball: Ball = { diameter: 10 }; │
│ let sphere: Sphere = { diameter: 20 }; │
│ │
│ sphere = ball; // ✅ same shape │
│ ball = sphere; // ✅ same shape │
│ │
│ "If it has a diameter, it is a Ball." │
│ │
└────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────┐
│ NOMINAL (with branding) │
│ │
│ type UserId = string & { __brand: "UserId" }; │
│ type OrderId = string & { __brand: "OrderId" }; │
│ │
│ let uid: UserId = "u1" as UserId; │
│ let oid: OrderId = "o1" as OrderId; │
│ │
│ oid = uid; // ❌ different brands │
│ uid = oid; // ❌ different brands │
│ │
│ The brand is the name. │
│ │
└────────────────────────────────────────────────────────┘Visual: The Brand is a Fiction
┌────────────────────────────────────────────────────────┐
│ COMPILE TIME │
│ │
│ type UserId = string & { readonly [__brand]: "UserId" }│
│ ▲ │
│ │ │
│ phantom property │
│ exists only in types │
│ │
│ createUserId("user-123") → UserId │
│ (brand attached) │
│ │
└────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────┐
│ RUNTIME │
│ │
│ const id = createUserId("user-123"); │
│ typeof id === "string" // true │
│ id.__brand // undefined │
│ │
│ JSON.stringify(id) // '"user-123"' │
│ The brand is gone. │
│ │
└────────────────────────────────────────────────────────┘Visual: Constructor as Boundary
┌────────────────────────────────────────────────────────┐
│ UNVALIDATED REGION VALIDATED REGION │
│ (plain strings) (branded types) │
│ │
│ req.body.email ──► createEmail() ──► Email │
│ │ │
│ ├── validate │
│ ├── throw if bad │
│ └── cast to brand │
│ │
│ Once inside, every function accepts Email and │
│ trusts the invariant without re-checking. │
│ │
└────────────────────────────────────────────────────────┘Visual: unique symbol vs String Literal Brand
┌────────────────────────────────────────────────────────┐
│ STRING LITERAL BRAND │
│ │
│ type A = string & { __brand: "UserId" }; │
│ type B = string & { __brand: "UserId" }; │
│ │
│ A and B are the SAME type. │
│ Two independent declarations collide. │
│ │
└────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────┐
│ UNIQUE SYMBOL BRAND │
│ │
│ declare const UA: unique symbol; │
│ declare const UB: unique symbol; │
│ │
│ type A = string & { [UA]: void }; │
│ type B = string & { [UB]: void }; │
│ │
│ A and B are DIFFERENT types. │
│ UA and UB can never be equal. │
│ │
└────────────────────────────────────────────────────────┘Summary
| Item | Value |
|---|---|
| Brand definition | T & { readonly [__brand]: Name } |
| Helper | type Brand<T, B> = T & { [__brand]: B } |
| Uniqueness | unique symbol for cross-module |
| Constructor | Validated function returning branded type |
| Assignability | UserId → string ✅; string → UserId ❌ |
| Runtime | Brand does not exist |
| Serialization | Brand is lost |
| Best for | IDs, tokens, validated strings, units |
| Avoid for | Free text, throwaway scripts, finite sets (use union) |
Key takeaways:
- TypeScript is structural — two strings are the same type, even when they mean different things
- Branded types add a phantom property that makes structurally identical types nominally distinct to the compiler
- The
unique symboltechnique is the most robust because each symbol is genuinely unique across modules - A
Brand<T, B>helper collapses the intersection to one line per type - Constructors are the only sanctioned way to create a brand, and validation belongs there
- Brands are compile-time only — they vanish at runtime and do not survive JSON serialization
- Brand for safety, not ceremony — use it when swapping two same-type values causes silent bugs; use unions for finite sets
- Combine with Zod for schema-driven validation that produces branded types at parse time
Remember: Structural typing is a feature, not a limitation, but it leaves a gap for domain primitives. Branded types fill that gap with a single intersection and a constructor. The brand is a fiction the compiler believes in, and that belief is enough to turn a class of runtime bugs into compile-time errors.
Stop using slow, ad-bloated tool sites! 🤮
🔎 Search “KandZ Tools” on Google to use many professional utilities for free.
KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)
⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free
🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!