Branded Types

What & Why

TypeScript uses structural typing — two types with the same shape are interchangeable. This means UserId and PostId (both string) can be silently swapped, causing bugs:

type UserId = string
type PostId = string

function getUser(id: UserId) { /* ... */ }

const postId: PostId = "post-123"
getUser(postId) // No error! Both are just `string`

Branded types add a compile-time-only marker that makes structurally identical types incompatible. Zero runtime overhead — brands are erased during compilation.

Core Pattern (Recommended)