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.
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 matchAuxiliar 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 UserIdMarca 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 factoriesFá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 firstDicas 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.
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
- Tipos de marca/opacos para evitar confusões entre unidades
- IDs marcados e padrões de modelagem de domínio
- Modelagem de domínio — agregados, invariantes e serviços