dev-typescript-patterns

TypeScript Patterns — Software Complexo

Types vs Interfaces

// Interface: para objetos públicos e extensíveis (podem ser merged via declaration merging)
interface User {
  id: string
  email: string
  name: string
}

// Type: para unions, intersections, mapped types, e aliases
type UserRole = 'admin' | 'member' | 'viewer'
type UserWithRole = User & { role: UserRole }
type PartialUser = Partial<User>

Regra geral: Interface para contratos de API e objetos de domínio. Type para unions, aliases e tipos compostos.

Discriminated Unions

// ✅ Modelar resultados com discriminated union
type Result<T, E = Error> =
  | { success: true; data: T }
  | { success: false; error: E }

// Uso
function parseUser(raw: unknown): Result<User> {
  const parsed = userSchema.safeParse(raw)
  if (!parsed.success) return { success: false, error: parsed.error }
  return { success: true, data: parsed.data }
}

// Type narrowing automático
const result = parseUser(rawData)
if (result.success) {
  console.log(result.data.email)   // TypeScript sabe que data existe
} else {
  console.log(result.error.message) // TypeScript sabe que error existe
}

Branded Types (IDs seguros)

// Evitar confundir UserId com OrderId
type UserId = string & { readonly _brand: 'UserId' }
type OrderId = string & { readonly _brand: 'OrderId' }

function createUserId(id: string): UserId {
  return id as UserId
}

// Agora TypeScript recusa UserId onde OrderId é esperado
function getOrder(id: OrderId) { ... }
getOrder(userId)  // ✅ Erro de compilação — catching bug em compile time

Generics com Constraints

// Generic para Repository pattern
interface Repository<T extends { id: string }> {
  findById(id: string): Promise<T | null>
  findAll(filters?: Partial<T>): Promise<T[]>
  create(data: Omit<T, 'id' | 'createdAt'>): Promise<T>
  update(id: string, data: Partial<Omit<T, 'id'>>): Promise<T>
  delete(id: string): Promise<void>
}

// Generic utilitário
type PaginatedResult<T> = {
  data: T[]
  pagination: { page: number; perPage: number; total: number; hasNext: boolean }
}