Union Types (|) e Intersection Types (&) no TypeScript: Guia Completo
Eleve a flexibilidade e a expressividade da sua arquitetura de tipos: domine os operadores de União (|) para modelar variáveis polimórficas com afunilamento seguro e de Interseção (&) para compor contratos complexos através de pequenos blocos atômicos reutilizáveis.
📑 Índice do Conteúdo
1. A Lógica de Conjuntos no TypeScript: União vs. Interseção
O sistema de tipos do TypeScript é fundamentado na Teoria de Conjuntos (Set Theory). Em vez de tratar tipos como classes rígidas e imutáveis, o compilador compreende tipos como conjuntos de valores possíveis:
- Operador de União (
|— OU Lógico): Modela um tipo que aceita valores do Tipo A OU do Tipo B. É inclusivo e amplia as possibilidades de entrada aceitas por uma variável ou função. - Operador de Interseção (
&— E Lógico): Modela um tipo que exige simultaneamente todas as características do Tipo A E do Tipo B. É cumulativo e restritivo, combinando múltiplos contratos em uma única entidade.
2. Union Types (|): Flexibilidade e a Regra das Propriedades Comuns
Declarar uma união é intuitivo: basta separar dois ou mais tipos com o caractere barra vertical (|):
TypeScript
// A chave primária pode ser numérica (banco SQL) ou string (UUID v4):
let identificador: string | number;
identificador = "c3f1b4a0-9941"; // Válido
identificador = 1042; // Válido
A | B, o TypeScript só permite acessar propriedades que existam tanto em A quanto em B antes de qualquer validação.
Observe o comportamento abaixo:
TypeScript
function formatarId(id: string | number) {
// ❌ ERRO TS2339:
// Property 'toUpperCase' does not exist on type 'number'.
// return id.toUpperCase();
// ❌ ERRO TS2339:
// Property 'toFixed' does not exist on type 'string'.
// return id.toFixed(2);
// ✅ VÁLIDO: O método toString() existe tanto em string quanto em number:
return `ID: ${id.toString()}`;
}
3. Estreitamento de Uniões (Type Narrowing)
Para invocar métodos específicos de um dos ramos da união, utilizamos o conceito de Type Narrowing (Afunilamento de Tipo) com guardas condicionais:
TypeScript
function normalizarChave(chave: string | number): string {
if (typeof chave === "string") {
// Dentro deste bloco if, o TypeScript SABE que chave é estritamente string:
return chave.trim().toUpperCase();
} else {
// No bloco else, por eliminação lógica, chave é estritamente number:
return chave.toFixed(0).padStart(8, "0");
}
}
4. Intersection Types (&): Composição sobre Herança
Enquanto a orientação a objetos clássica incentiva a herança hierárquica profunda com extends (o que muitas vezes gera acoplamento excessivo e classes inchadas), o TypeScript promove a Composição de Tipos através do operador de interseção (&).
Com a interseção, podemos fatiar nosso modelo de dados em pequenos pedaços atômicos e reutilizáveis:
TypeScript
// 1. Blocos atômicos reutilizáveis (Mixins/Traits de tipos)
type EntidadeBase = {
id: string;
};
type MetadadosAuditoria = {
criadoEm: Date;
atualizadoEm: Date;
versao: number;
};
type PermissoesAcesso = {
isAdmin: boolean;
modulosAutorizados: string[];
};
// 2. Composição elegante via Interseção (&):
type UsuarioCorporativo = EntidadeBase & MetadadosAuditoria & PermissoesAcesso & {
nome: string;
email: string;
};
// Um objeto do tipo UsuarioCorporativo é OBRIGADO a satisfazer TODOS os contratos combinados:
const novoUsuario: UsuarioCorporativo = {
id: "USR-9941",
nome: "Carolina Prado",
email: "[email protected]",
criadoEm: new Date(),
atualizadoEm: new Date(),
versao: 1,
isAdmin: true,
modulosAutorizados: ["financeiro", "relatorios", "suporte"]
};
5. O Perigo de Conflito em Interseções: O Colapso para never
Ao compor tipos com interseção, é vital garantir que as propriedades homônimas não possuam tipos conflitantes. Se dois tipos declararem a mesma chave com tipos incompatíveis, essa propriedade sofrerá um colapso para never:
TypeScript
type ContratoA = { status: string };
type ContratoB = { status: number };
// A propriedade "status" vira (string & number).
// Como não existe nenhum valor no universo que seja simultaneamente string e number:
type ContratoConflitante = ContratoA & ContratoB;
// ❌ ERRO TS2322: Type 'string' is not assignable to type 'never'.
// É impossível instanciar qualquer objeto desse tipo!
/*
const erro: ContratoConflitante = {
status: "ok" // Falha: espera o tipo never!
};
*/
6. Exemplo Prático Integrado: Plataforma de Checkout Multi-Gateway
Veja como combinar Union Types (para múltiplos métodos de pagamento) com Intersection Types (para registro de auditoria e recibo) em um checkout de e-commerce:
TypeScript
// 1. Contratos individuais para cada modalidade de pagamento
type PagamentoPix = {
metodo: "pix";
chavePix: string;
expiraEmSegundos: number;
};
type PagamentoCartao = {
metodo: "cartao";
numeroCartaoMascarado: string;
parcelas: number;
};
type PagamentoBoleto = {
metodo: "boleto";
codigoBarras: string;
vencimento: Date;
};
// 2. UNION TYPE: O cliente escolhe exatamente UMA modalidade
type ModalidadePagamento = PagamentoPix | PagamentoCartao | PagamentoBoleto;
// 3. Tipos para metadados de auditoria transacional
type ReciboTransacao = {
transacaoId: string;
timestamp: number;
valorTotal: number;
};
// 4. INTERSECTION TYPE: Recibo final auditado combinando os dados
type TransacaoConcluida = ReciboTransacao & {
pagamento: ModalidadePagamento;
};
// 5. Função de processamento com estreitamento seguro
function processarCobranca(dados: ModalidadePagamento, valor: number): TransacaoConcluida {
console.log(`[GATEWAY] Processando cobrança de R$ ${valor.toFixed(2)} via modalidade: ${dados.metodo}.`);
if (dados.metodo === "pix") {
console.log(`[PIX] QR Code gerado para a chave: ${dados.chavePix}`);
} else if (dados.metodo === "cartao") {
console.log(`[CARTÃO] Transação em ${dados.parcelas}x no cartão final ${dados.numeroCartaoMascarado}`);
} else {
console.log(`[BOLETO] Linha digitável gerada: ${dados.codigoBarras}`);
}
return {
transacaoId: "TX-" + Math.floor(Math.random() * 1000000),
timestamp: Date.now(),
valorTotal: valor,
pagamento: dados
};
}
const pedidoPix: PagamentoPix = {
metodo: "pix",
chavePix: "[email protected]",
expiraEmSegundos: 300
};
const reciboFinal = processarCobranca(pedidoPix, 450.00);
console.log(`[SUCESSO] Pedido aprovado! Recibo #${reciboFinal.transacaoId} gravado.`);
7. Tabela Comparativa: União (|) vs. Interseção (&)
| Característica | Operador de União (|) |
Operador de Interseção (&) |
|---|---|---|
| Lógica Matemática | OU Lógico (Disjunção de conjuntos). | E Lógico (Conjunção de conjuntos). |
| Requisito de Satisfação | Basta satisfazer pelo menos um dos tipos. | Obrigatório satisfazer todos os tipos. |
| Acesso a Propriedades | Apenas propriedades comuns (sem narrowing). | Acesso direto a todas as propriedades. |
| Conflito de Tipos | Permitido e comum (ex: string | number). |
Colapsa para never em tipos incompatíveis. |
| Melhor Aplicação | Parâmetros polimórficos, status e payloads alternativos. | Composição de entidades de banco de dados e mixins. |
type ComId = { id: string }, type ComTimestamps = { criadoEm: Date }) e monte suas entidades corporativas combinando-os com o operador &. Isso torna seus testes e refatorações incrivelmente simples.
Aplique o que você aprendeu nesta lição
Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.
Editor de Códigos Web Online
Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.
Abrir Ferramenta OnlinePlayground Web Online
Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.
⚡ Codificar no Playground IDE