branded-types

TypeScript mixes structurally identical IDs because its structural type system treats them as interchangeable. Branded types solve this by adding compile-time nominal safety with zero runtime overhead, making distinct ID types impossible to mix up.

Validated string types are best created using branded types with constructor functions. This confines unsafe type assertions to a single validation point, ensuring invalid strings fail at the constructor level before reaching your application logic.

Branded nominal typing integrates directly with Zod and Drizzle. You can apply brand assertions within Zod schemas and map branded IDs to Drizzle columns, ensuring end-to-end type safety from database queries to API responses.

You should avoid branded types when over-branding simple values, using runtime brand checks instead of compile-time assertions, or creating duplicate brand names. Over-branding adds unnecessary complexity without meaningful safety benefits.

Branded types support advanced composition by combining multiple brands and unwrapping branded base types. This allows you to layer different safety constraints, such as marking a value as both validated and unit-specific.

Convert plain TypeScript aliases by defining a shared Brand utility with a unique symbol, applying it to your base types, and creating validated constructor functions to enforce safe instantiation. This provides compile-time nominal typing and prevents accidental mixing.