branded-types

TypeScript uses structural typing, so nominal typing requires branded types: intersect a primitive with a phantom property like string & { _brand: 'userId' }. Values can then only be created through type guards or factory functions, preventing accidental cross-assignment.

A branded type is an intersection of a primitive with a phantom property, such as type Meters = number & { _brand: 'meters' }. The brand exists only at compile time, so it adds no runtime overhead while making incompatible values unassignable.

No, brands are phantom types that exist only in the type system and are erased at runtime. The intersection property is never actually present on the value, so there is no memory or performance cost.

TypeScript's arithmetic operators return plain number, so operations like d * 2 strip the brand from a branded number. You must re-apply the brand with a cast or factory function after computation.

Use brands when primitives have different semantic meanings, such as UserId versus PostId or sanitized versus raw HTML. Plain type aliases like type UserId = string do not prevent cross-assignment, while brands make the compiler reject mixed values.