TypeScript generics that make your APIs self-documenting

A comment saying 'id must be a valid UUID' is a suggestion. A branded type is a guarantee. On every TypeScript codebase I ship now, primitive-obsessed fields — user IDs, email addresses, currency amounts — get wrapped in branded types so the compiler rejects a raw string where a validated one is required.

This single change eliminates an entire category of bugs: passing an order ID where a customer ID was expected, or a dollar amount where cents were expected. The type system becomes the documentation, and it's impossible for it to go out of sync with the code.

A response shape with five optional fields that 'depend on status' is a runtime bug waiting to happen. I model API responses as discriminated unions keyed on a `status` or `type` literal, so TypeScript narrows the shape automatically inside every `if` or `switch` branch.

• Every union member has only the fields that are actually valid for that state
• Exhaustiveness checks (`never` in the default case) catch missing branches at compile time
• Frontend and backend can share the same union types via a shared package
• This turns 'what fields exist when status is pending?' into a question the compiler answers for you

Instead of writing a near-identical CRUD service for every Mongoose or Prisma model, I write one generic `Repository<T>` with typed `find`, `create`, and `update` methods. Model-specific services extend it and add only the domain logic that's actually unique.

The payoff compounds: adding a new entity to the system means writing a schema and a thin service, not 200 lines of boilerplate. Refactors that touch every repository become one generic-type change instead of a search-and-replace across dozens of files.

Generics are only useful if callers never have to write them out by hand. I design functions so TypeScript infers the generic parameter from the arguments — a validation function that takes a Zod schema, for example, infers its return type from that schema automatically.

The test I apply to every exported function: can someone call it with sensible arguments and get full autocomplete on the result, without ever typing an angle bracket? If not, the generic is designed wrong.

Not everything needs a branded type or a five-level generic. Internal one-off scripts, quick prototypes, and glue code between well-typed layers are fine as plain types. Over-engineering the type layer slows down iteration without preventing any bugs that would actually occur.

The rule I follow: invest in types at trust boundaries — API inputs, database reads, third-party responses — where invalid data actually enters the system. Everywhere else, keep it simple.