Enums no TypeScript: Numéricos, String e const enum
⚡ Curso de TypeScript • Web-ZoneWare

Enums no TypeScript: Numéricos, String Enums e const enum

Lição 7 de 50

Enums no TypeScript: Numéricos, String Enums e const enum

⚡ Módulo 1 • Aula 07 de 50

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.

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:

enums-numericos.ts
TypeScript
TypeScript 10 linhas
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:

enums-customizados.ts
TypeScript
TypeScript 8 linhas
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:

mapeamento-reverso.ts
TypeScript
TypeScript 12 linhas
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}`);
🔍

Como o JavaScript Compilado Faz Isso: O compilador tsc gera a seguinte instrução: 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:

string-enums.ts
TypeScript
TypeScript 10 linhas
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:

const-enum.ts
TypeScript
TypeScript 8 linhas
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:

dist/const-enum.js (Transpilado)
JavaScript Puro
JavaScript 3 linhas
"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:

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

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

Dica Pro de Engenharia Web-ZoneWare: Se o seu projeto utiliza empacotadores como Vite, Babel ou esbuild com a flag 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.

🚀

Próximo Passo Prático: Com os Enums dominados, na Lição 08 vamos explorar dois dos operadores mais poderosos e versáteis do TypeScript: Union Types (|) e Intersection Types (&).

🛠️ 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