TypeScript: Branded Types

Original Article ↗ Hacker News Discussion ↗

TypeScript developers are debating the value of “branded” (nominal-style) types layered on top of the language’s structural type system, especially for primitives like strings and numbers used as IDs, units, or currency. Proponents say these patterns make invalid states unrepresentable, prevent subtle bugs (e.g., mixing user IDs with org IDs or meters with feet) and add safety without runtime cost, while critics see them as over-engineered, hard to read, and easily bypassed with casts. The exchange highlights broader trade-offs in TypeScript: structural vs nominal typing, static guarantees vs runtime checks, and when complex type machinery meaningfully improves real-world codebases.

Perceived Benefits and Use Cases

  • Branded types emulate nominal typing in TypeScript’s structural system.
  • Common use cases:
    • Distinguishing IDs of different entities (UserId vs OrgId vs AccountId).
    • Units and dimensions (nanoseconds vs seconds, inches vs meters, currencies).
    • DDD-style value objects (Email, String100, SafeString, LoggedUser, verified cookies).
    • Separating “raw” vs “validated/parsed” data at system boundaries; helpful with hexagonal architectures.
  • Helps prevent argument-order bugs when several parameters share the same primitive type.
  • In medium/large codebases and type-heavy libraries (validation, DB access, FP utilities), advanced typing allows more expressive, safer APIs.

Concerns About Complexity and Safety

  • Some find this pattern overengineered, ugly, or not worth it for typical apps that use simple types.
  • Fear that advanced type tricks encourage unreadable “type spaghetti” and slow compilation.
  • Branding can be bypassed with casts (as), so it is not a security feature and can hide misuse.
  • Library consumers may get confusing error messages when branded types are used heavily.

Implementation Techniques Discussed

  • Core trick: intersect a base type with a unique “brand” property, often:
    • type X = T & { readonly __X_brand: never }
    • or using unique symbol fields or helper generics like Brand<T, "Tag">.
  • Typically requires a constructor function or explicit cast to apply the brand.
  • Works especially well for primitives; for objects, meaningful field names or classes may already suffice.
  • Classes with private fields give nominal behavior and allow instanceof checks, but introduce runtime overhead.

Type System Philosophy and Alternatives

  • Debate over structural vs nominal typing; some see branding as fighting the language design, others as a pragmatic zero-cost escape hatch.
  • Desire for first-class nominal/refinement/newtype support in TypeScript; related work and internal branded types exist.
  • Comparisons made to Flow’s opaque types, Go’s distinct types, Haskell newtypes, Rust wrappers, and Odin’s distinct.

Runtime Validation vs Static Guarantees

  • Branding is often paired with parsing/validation functions so that once a value is branded, callers can rely on invariants statically.
  • Some argue runtime checks and tests are sufficient; others prefer shifting as many invariants as possible into the type system.