TypeScript Academy · Aula

Tipos de marca/opacos para evitar confusões entre unidades

Evite confusões entre unidades e marcas intersectando tipos base com propriedades de marca fantasma; construa-os somente por meio de funções de fábrica.

Aula 1 de 38 etapas

Tipos de marca/opacos para evitar confusões entre unidades é uma aula grátis de TypeScript Academy no CoddyKit. Esta é a aula 1 de 3. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de TypeScript Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de TypeScript Academy inclui 3 aulas no total.

Introdução

Objetivo: separar valores semelhantes no nível dos tipos. Um simples number não distingue metros de segundos; um marcador de marca pode fazer isso.

  • Custo de execução zero
  • APIs e refatorações mais seguras
  • Criar somente por meio de fábricas

Marcar unidades primitivas

Marcadores de marca mantêm as unidades separadas durante a compilação; a ordem incorreta dos argumentos falha na verificação de tipos.

type Meter = number & { readonly __brand: "meter" }
type Second = number & { readonly __brand: "second" }

function meter(n: number): Meter { return n as Meter }
function second(n: number): Second { return n as Second }

const d = meter(100)
const t = second(9)

function speed(dist: Meter, time: Second) { return (dist as number) / (time as number) }

// speed(t, d)  // compile error: brands do not match

Auxiliar genérico de marca

Use um auxiliar genérico Brand em vários domínios: IDs tipados, tokens, cursores e outros.

type Brand<Tag extends string, T> = T & { readonly __brand: Tag }

type UserId = Brand<"UserId", string>
type OrderId = Brand<"OrderId", string>

function userId(x: string): UserId { return x as UserId }
function orderId(x: string): OrderId { return x as OrderId }

function findUser(id: UserId) { /* ... */ }

const u = userId("u_123")
const o = orderId("o_456")
// findUser(o) // error: OrderId not assignable to UserId

Marca de símbolo único

A marca de símbolo único evita colisões de nomes e o vazamento para espaços de nomes globais.

declare const MeterSym: unique symbol

type Meter2 = number & { readonly [MeterSym]: "meter" }

function asMeter2(n: number): Meter2 { return n as Meter2 }

const m2 = asMeter2(5)
// const wrong: Meter2 = 5  // discourage raw assignment; prefer factories

Fábricas e validação

Coloque a marca dentro de uma fábrica: valide primeiro, depois marque e, por fim, consuma. Evite usar as de forma improvisada nos pontos de chamada.

type NonEmptyString = string & { readonly __brand: "NonEmpty" }

function nonEmpty(s: string): NonEmptyString | null {
  return s.trim().length > 0 ? (s as NonEmptyString) : null
}

function makeSlug(s: NonEmptyString) {
  return (s as string).toLowerCase().replace(/\s+/g, "-")
}

const ok = nonEmpty(" Hello ")
if (ok) { makeSlug(ok) }  // safe: validated & branded first

Dicas e armadilhas

Boas práticas:

  • Mantenha os nomes das marcas curtos e significativos.
  • Exponha as fábricas como a única forma de obter valores marcados.
  • Não exponha marcas nos tipos da API pública, a menos que seja necessário.
  • As marcas existem apenas no nível dos tipos: não geram custo em tempo de execução.

Verificação de marca

Verificação rápida: qual padrão evita confusões entre unidades e identificadores?

Recapitulação

Recapitulação: os tipos marcados/opacos separam valores semelhantes (metros e segundos, UserId e OrderId). Produza-os por meio de fábricas, use-os nas interfaces de programação e elimine confusões acidentais.

Grátis para começar

Aprenda TypeScript com um tutor de IA — grátis

Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.

Cursos
101
Aulas
352

Perguntas Frequentes

A aula “Tipos de marca/opacos para evitar confusões entre unidades” é grátis?

Sim — o texto completo de “Tipos de marca/opacos para evitar confusões entre unidades” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de TypeScript Academy, atualize para CoddyKit PRO. O curso de TypeScript Academy inclui 3 aulas no total.

O que vou aprender em “Tipos de marca/opacos para evitar confusões entre unidades”?

Evite confusões entre unidades e marcas intersectando tipos base com propriedades de marca fantasma; construa-os somente por meio de funções de fábrica. Você pratica TypeScript Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar TypeScript Academy?

Nenhuma experiência prévia é necessária. TypeScript Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 3.

Quanto tempo leva a aula “Tipos de marca/opacos para evitar confusões entre unidades”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de TypeScript Academy?

Sim. Cada aula de TypeScript Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Tipos de marca/opacos para evitar confusões entre unidades
  2. IDs marcados e padrões de modelagem de domínio
  3. Modelagem de domínio — agregados, invariantes e serviços
← Voltar para TypeScript Academy