Enums no TypeScript: Numéricos, String Enums e const enum
Organize constantes de domínio e elimine valores mágicos: domine a criação de Enums numéricos com auto-incremento, String Enums auto-documentados, compreenda a anatomia do mapeamento reverso e otimize seu código em produção com const enum.
📑 Índice do Conteúdo
1. O que são Enums no TypeScript?
Os Enums (Enumerações) são um dos raros recursos do TypeScript que não são apenas tipos em tempo de compilação. Diferente de interfaces e types (que sofrem Type Erasure e desaparecem no build), os Enums tradicionais geram um objeto JavaScript real em tempo de execução.
O propósito principal de um Enum é fornecer um conjunto de constantes nomeadas com significados claros, eliminando números mágicos (como status === 1) e strings soltas propensas a erros de digitação (como status === "pendente").
2. Enums Numéricos e Auto-Incremento
Por padrão, quando você declara um Enum sem atribuir valores explícitos, o TypeScript cria um Enum Numérico indexado a partir de zero (zero-based), auto-incrementando cada membro subsequente em 1:
TypeScript
enum StatusPedido {
Pendente, // 0
Processando,// 1
Enviado, // 2
Entregue, // 3
Cancelado // 4
}
let statusAtual: StatusPedido = StatusPedido.Processando;
console.log(statusAtual); // Imprime: 1
Você também pode definir um inicializador inicial customizado. Os próximos membros continuarão o incremento a partir daquele valor:
TypeScript
enum CodigoResposta {
Sucesso = 200,
Criado, // 201
Aceito, // 202
NaoAutorizado = 401,
Proibido, // 402
NaoEncontrado // 403
}
3. O Fenômeno do Mapeamento Reverso (Reverse Mapping)
Uma particularidade fascinante dos Enums numéricos é que o TypeScript gera um objeto bidirecional. Isso significa que você pode acessar o valor através do nome, ou o nome do membro através do seu valor numérico:
TypeScript
enum NivelLog {
Info = 1,
Aviso = 2,
Erro = 3
}
// 1. Acesso direto (Nome -> Valor):
const codigoErro: number = NivelLog.Erro; // 3
// 2. Mapeamento Reverso (Valor -> Nome do Membro):
const nomeMembro: string = NivelLog[3]; // ___WZW_STR_0___
console.log(`O nível correspondente ao código 3 é: ${nomeMembro}`);
NivelLog[NivelLog["Erro"] = 3] = "Erro";. Isso cria duas chaves no mesmo objeto JS: { "Erro": 3, "3": "Erro" }.
4. String Enums: Clareza em Logs e Banco de Dados
Em sistemas web modernos e APIs RESTful, os String Enums são preferidos em relação aos numéricos. Em um String Enum, cada membro deve ser inicializado explicitamente com uma string literal:
TypeScript
enum PapelUsuario {
SuperAdmin = "SUPER_ADMIN",
Gestor = "GESTOR",
Analista = "ANALISTA",
Visitante = "VISITANTE"
}
// Em tempo de execução, o valor é uma string expressiva:
const papel = PapelUsuario.Gestor;
console.log(papel); // Imprime: ___WZW_STR_0___ (muito mais legível em logs que o número 1)
Nota Importante: String Enums não possuem mapeamento reverso, o que resulta em objetos JavaScript transpilados menores e mais enxutos.
5. Otimização de Performance com const enum (Inlining)
Se você deseja os benefícios semânticos de um Enum, mas quer evitar a geração de funções utilitárias e objetos na memória do JavaScript em produção, utilize o modificador const enum:
TypeScript
const enum Direcao {
Norte = "N",
Sul = "S",
Leste = "L",
Oeste = "O"
}
const rumoNavio: Direcao = Direcao.Norte;
Veja como o código acima é compilado para JavaScript puro:
JavaScript Puro
"use strict";
// Observe: Nenhum objeto "Direcao" foi criado! O valor "N" foi embutido diretamente (Inlining):
const rumoNavio = "N";
6. Enums vs. Union Types de Literais
Na comunidade TypeScript, existe um debate permanente sobre quando utilizar Enums versus Union Types de Literais de String (ex: type Status = "pendente" | "pago" | "cancelado"):
- Use Enums quando: Você precisa de um namespace semântico formal, deseja iterar sobre os valores em tempo de execução via
Object.values(MeuEnum), ou trabalha em projetos corporativos com interoperabilidade de modelos de dados C#/Java. - Use Union Types quando: Você busca máxima simplicidade, compatibilidade direta com payloads JSON sem etapas de conversão e zero bytes extras no bundle JS.
7. Exemplo Prático Integrado: Controle de Acesso e Erros de API
Veja como integrar Enums numéricos, String Enums e const enum em um módulo de autenticação empresarial:
TypeScript
// 1. String Enum para papéis de segurança no sistema
enum NivelAcesso {
Admin = "ADMIN",
Moderador = "MODERADOR",
Usuario = "USUARIO"
}
// 2. const enum para códigos de status HTTP internos (zero overhead)
const enum HttpCode {
Ok = 200,
BadRequest = 400,
Forbidden = 403,
InternalError = 500
}
// 3. Interface do usuário utilizando o Enum
interface UsuarioAutenticado {
id: number;
nome: string;
papel: NivelAcesso;
}
// 4. Função de autorização
function validarAcessoRecurso(usuario: UsuarioAutenticado, nivelMinimo: NivelAcesso): [codigo: HttpCode, autorizacao: boolean] {
if (usuario.papel === NivelAcesso.Admin) {
return [HttpCode.Ok, true];
}
if (usuario.papel === nivelMinimo) {
return [HttpCode.Ok, true];
}
return [HttpCode.Forbidden, false];
}
const usuarioAtivo: UsuarioAutenticado = {
id: 1042,
nome: "Juliana Mendes",
papel: NivelAcesso.Moderador
};
const [statusResposta, autorizado] = validarAcessoRecurso(usuarioAtivo, NivelAcesso.Admin);
console.log(`[AUTORIZAÇÃO] Status HTTP: ${statusResposta} | Acesso Permitido: ${autorizado}`);
8. Tabela Didática Comparativa: Tipos de Enums
| Categoria de Enum | Gera Objeto no JS? | Suporta Mapeamento Reverso? | Inlining no Build? | Cenário Recomendado |
|---|---|---|---|---|
| Enum Numérico | Sim | Sim (Nome <-> Valor) | Não | Flags, contadores internos e índices ordinais. |
| String Enum | Sim | Não | Não | Logs claros, depuração de rede e persistência em banco. |
| const enum | Não (Apagado) | Não | Sim | Constantes críticas onde cada byte e ciclo de CPU contam. |
isolatedModules: true no tsconfig.json, prefira String Enums comuns ou Union Types de strings. O const enum pode exigir compilação de projeto completo para realizar o inlining com segurança entre múltiplos arquivos.
|) e Intersection Types (&).
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