branded-types

SKILL.md

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:

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

Use a generic Brand utility with a single unique symbol:

Implement branded (nominal/opaque) types in TypeScript to prevent accidental mixing of structurally identical types. Use when writing type-safe IDs (UserId, PostId), validated strings (Email, URL), unit-specific numbers (Meters, Seconds), or any scenario requiring nominal typing in TypeScript's structural type system. Source: iaskshahram/branded-types.

View raw