Nominal Typing via Branded Types

Snippet

Nominal Typing via Branded Types

TypeScript uses structural typing, but sometimes we need nominal typing to prevent accidental mixing of logically different primitives (like different currencies or IDs). Branding 'tags' a type with a unique property that doesn't exist at runtime but enforces strict separation at compile time.

snippet.ts
typescript
type Brand<K, T> = K & { __brand: T };
 
type USD = Brand<number, "USD">;
type EUR = Brand<number, "EUR">;
 
const usd = 10 as USD;
const eur = 10 as EUR;
 
function addUSD(a: USD, b: USD): USD {
  return (a + b) as USD;
}
 
// Error: Argument of type 'EUR' is not assignable to 'USD'
// addUSD(usd, eur);

Breakdown

type Brand<K, T> = K & { __brand: T };

Creates an intersection type that combines the base type with a phantom property used only for type checking.

const usd = 10 as USD;

Type assertion is required to 'brand' the primitive value, as the __brand property doesn't exist on a raw number.

Previous snippet Next snippet

From your library

Nominal Typing via Branded Types

Related