Union Types e Intersection Types no TypeScript Guia
⚡ Curso de TypeScript • Web-ZoneWare

Union Types (|) e Intersection Types (&) no TypeScript: Guia Completo

Lição 8 de 50

Union Types (|) e Intersection Types (&) no TypeScript: Guia Completo

⚡ Módulo 1 • Aula 08 de 50

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.

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 (|):

unioes-basicas.ts
TypeScript
TypeScript 5 linhas
// 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 Regra Fundamental das Propriedades Comuns: Quando você possui uma variável do tipo 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:

dilema-propriedades.ts
TypeScript
TypeScript 12 linhas
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:

narrowing-unioes.ts
TypeScript
TypeScript 9 linhas
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:

intersecoes-composicao.ts
TypeScript
TypeScript 33 linhas
// 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:

colapso-never.ts
TypeScript
TypeScript 14 linhas
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:

checkout-multigateway.ts
TypeScript
TypeScript 62 linhas
// 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.`);
Execute e teste códigos interativos na ferramenta oficial do portal:
Abrir no Playground IDE →

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.
💡

Dica Pro de Engenharia Web-ZoneWare: Adote o princípio da composição modular. Em vez de criar um tipo gigante monolítico, divida seu domínio em pequenos pedaços (ex: 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.

🚀

Próximo Passo Prático: Com os operadores de conjuntos dominados, na Lição 09 vamos aprofundar em Literal Types e Type Aliases (type), compreendendo como criar tipos com valores fixos e estruturar apelidos de tipos profissionais.

🛠️ Laboratório Prático & Prática Imediata

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.

💻 Desenvolvedor & Código

Editor de Códigos Web Online

Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.

Abrir Ferramenta Online
⚡ Live Code Studio

Playground 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
Foto de Web-Zoneware
✓ Verificado
🎓 Tutor & Coordenador da Web Academy

Web-Zoneware

Tutor Técnico & Desenvolvedor Full-Stack

Desenvolvedor web e instrutor focado na formação prática de novos programadores. Defensor ferrenho de código semântico, arquitetura limpa e acessibilidade W3C/WCAG, dedicando-se a construir cursos estruturados em metodologia passo a passo com execução ao vivo no Playground IDE.

Especialidades: HTML5 Semântico CSS3 & Flexbox/Grid JavaScript Moderno Acessibilidade WCAG 2.2 Didática Prática
Rolar para cima