Combinando Literais em Uniões
Crie conjuntos finitos de valores unindo tipos literais.
Combinando Literais em Uniões é uma aula grátis de TypeScript Academy no CoddyKit. Esta é a aula 4 de 4. 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 4 aulas no total.
Uniões de tipos literais
Uma união de literais representa um valor que deve ser exatamente uma entre várias opções conhecidas. Ela é a base de máquinas de estados, enumerações e APIs bem tipadas.
type Status = 'idle' | 'loading' | 'success' | 'error';
let state: Status = 'idle';
state = 'loading';
console.log('State:', state);Usando switch em uma união literal
Um switch sobre uma união literal é claro, e o compilador sabe que cada caso corresponde a um dos valores permitidos. Isso combina perfeitamente com verificações de exaustividade.
type Status = 'idle' | 'loading' | 'done';
function label(s: Status): string {
switch (s) {
case 'idle': return 'Waiting';
case 'loading': return 'Working';
case 'done': return 'Finished';
}
}
console.log(label('loading'));Tratamento exaustivo
Tratar todos os membros de uma união é chamado de tratamento exaustivo. Quando você cobre todos os casos, o TypeScript pode provar que a função sempre retorna, sem nenhum ramo ausente.
type Dir = 'left' | 'right';
function step(d: Dir): number {
if (d === 'left') return -1;
return 1; // only 'right' remains
}
console.log(step('left'), step('right'));O truque de exaustividade com never
Atribuir o valor a um never no ramo padrão provoca um erro de compilação se você adicionar um novo membro à união e esquecer de tratá-lo. Isso funciona como uma rede de segurança para código em evolução.
type Shape = 'circle' | 'square';
function area(s: Shape): string {
switch (s) {
case 'circle': return 'pi r^2';
case 'square': return 'a^2';
default:
const _exhaustive: never = s;
return _exhaustive;
}
}
console.log(area('circle'));Derivando uniões de objetos const
Um padrão comum é manter os valores em um objeto const e derivar a união a partir deles usando typeof obj[keyof typeof obj]. Uma única fonte da verdade, duas saídas.
const Colors = { Red: 'red', Blue: 'blue' } as const;
type Color = typeof Colors[keyof typeof Colors];
// 'red' | 'blue'
const c: Color = Colors.Blue;
console.log(c);Derivando uniões de chaves
Você também pode derivar uma união das chaves com keyof typeof obj. Isso é útil quando as próprias chaves são os identificadores significativos.
const ICONS = { home: 0, search: 1, profile: 2 } as const;
type IconName = keyof typeof ICONS;
// 'home' | 'search' | 'profile'
const name: IconName = 'search';
console.log(name, ICONS[name]);Uniões discriminadas com etiquetas literais
Associe uma propriedade de etiqueta literal a cada variante de objeto, e o TypeScript poderá diferenciá-las. Verificar a etiqueta restringe o tipo à estrutura exata.
type Action =
| { type: 'add'; amount: number }
| { type: 'reset' };
function reduce(a: Action): number {
if (a.type === 'add') return a.amount;
return 0;
}
console.log(reduce({ type: 'add', amount: 5 }));Restringindo pelo discriminante
Depois que você testa o discriminante literal, o compilador sabe qual variante possui, então seus campos exclusivos ficam acessíveis com segurança, sem conversões de tipo.
type Event =
| { kind: 'click'; x: number; y: number }
| { kind: 'key'; code: string };
function handle(e: Event): string {
if (e.kind === 'key') return 'Key ' + e.code;
return 'Click ' + e.x + ',' + e.y;
}
console.log(handle({ kind: 'key', code: 'Esc' }));Combinando várias uniões
Você pode compor uniões maiores a partir de uniões nomeadas menores. Isso mantém as opções relacionadas agrupadas e reutilizáveis em todo o seu código.
type Primary = 'red' | 'blue' | 'yellow';
type Secondary = 'green' | 'orange';
type Color = Primary | Secondary;
const c: Color = 'green';
console.log(c);Uniões como restrições de funções
Passar uma união literal para uma função restringe os chamadores às opções válidas e oferece preenchimento automático no editor. A combinação de segurança e facilidade de descoberta é difícil de superar.
type Align = 'left' | 'center' | 'right';
function setAlign(a: Align): void {
console.log('Aligned', a);
}
setAlign('center');
// setAlign('top'); // ErrorPor que uniões literais são melhores que textos
Usar um parâmetro simples do tipo string aceita qualquer valor, inclusive erros de digitação. Uma união literal detecta os enganos em tempo de compilação e documenta as escolhas válidas — uma melhoria clara para código fácil de manter.
type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';
function request(m: Method, url: string): void {
console.log(m, url);
}
request('POST', '/api/users');Verificação rápida
Teste sua compreensão das uniões literais.
Recapitulação: combinando literais
Você aprendeu a:
- Construir uniões de literais para conjuntos finitos de opções.
- Tratá-las de forma exaustiva, usando o truque de
neverpara obter segurança. - Derivar uniões de objetos const por meio de
keyof typeofetypeof obj[keyof typeof obj]. - Diferenciar variantes com propriedades de etiqueta literal.
Próximo curso: os tipos especiais unknown, never e void.
const ROUTES = { home: '/', about: '/about' } as const;
type Route = typeof ROUTES[keyof typeof ROUTES];
const r: Route = '/about';
console.log(r);Perguntas Frequentes
A aula “Combinando Literais em Uniões” é grátis?
Sim — o texto completo de “Combinando Literais em Uniões” é 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 4 aulas no total.
O que vou aprender em “Combinando Literais em Uniões”?
Crie conjuntos finitos de valores unindo tipos literais. 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 4 de 4.
Quanto tempo leva a aula “Combinando Literais em Uniões”?
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 Literais de Texto e Números
- Literais Booleanos e Inferência de Literais
- Asserções const com as const
- Combinando Literais em Uniões