Decorators no TypeScript 5.0: Guia de Metaprogramação
⚡ Curso de TypeScript • Web-ZoneWare

O que são Decorators: A Nova Era da Metaprogramação no TypeScript 5.0 (Padrão TC39 Stage 3)

Lição 37 de 50

O que são Decorators: A Nova Era da Metaprogramação no TypeScript 5.0 (Padrão TC39 Stage 3)

Módulo 5: Utility Types, Decorators & Metaprogramação
Lição 37 de 50
Nível: Avançado
⏱ Tempo de Leitura e Prática: 30 minutos

O que são Decorators: A Nova Era da Metaprogramação no TypeScript 5.0 (Padrão TC39 Stage 3)

💡
O Que Você Vai Aprender Hoje: Se você já desenvolveu com frameworks consagrados como NestJS, Angular ou TypeORM, certamente já utilizou anotações como @Controller(), @Component() ou @Entity(). Esses são os Decorators! No TypeScript 5.0, os decorators passaram pela maior revolução da sua história: tornaram-se parte do padrão nativo da linguagem JavaScript (TC39 Stage 3). Hoje você entenderá como eles funcionam, o fim do legado experimentalDecorators e a nova API com ClassMemberDecoratorContext.

1. O Conceito de Metaprogramação e o Papel dos Decorators

Na programação convencional, seu código manipula dados: você lê parâmetros, faz cálculos e salva registros em um banco de dados. Na Metaprogramação, seu código manipula o próprio código: você inspeciona, intercepta, anota ou modifica o comportamento de classes, métodos e propriedades sem alterar a lógica interna deles.

Um Decorator é uma função especial precedida pelo símbolo @ (arroba) que é acoplada imediatamente antes da declaração de uma classe, método, acessor ou campo:

TypeScript: Sintaxe Declarativa de um Decorator

TypeScript 10 linhas
@ServicoCorporativo({ modulo: "Vendas" })
class GerenciadorPedidos {
    @RegistrarAuditoria
    @MedirTempoExecucao
    public processarPagamento(faturaId: string): boolean {
        // Apenas a regra de negócio vive aqui!
        // Auditoria, logs e medição de tempo são injetados externamente pelos decorators.
        return true;
    }
}

2. A Grande Ruptura: Decorators Legados (Stage 2) vs Novos Decorators (TS 5.0+)

Durante quase uma década, o ecossistema TypeScript dependeu da flag "experimentalDecorators": true no tsconfig.json. Esses eram os Legacy Decorators, baseados em uma proposta preliminar de 2014 do comitê TC39.

Com o lançamento do TypeScript 5.0 em 2023, o TypeScript implementou formalmente a especificação oficial padrão do JavaScript (TC39 Stage 3 Decorators). Veja o que mudou fundamentalmente:

Característica Legacy Decorators (TS 1.x – 4.x) Novos Decorators Padrão (TS 5.0+)
Configuração no tsconfig.json Exigia "experimentalDecorators": true. Habilitado nativamente sem flags experimentais.
Assinatura de Parâmetros (target, propertyKey, descriptor) (value, context: ClassMethodDecoratorContext)
Tipagem Estática Fraca (muitos tipos any soltos). Fortemente tipada com contextos específicos.
Inicializadores de Instância Gambiarra com reflexão manual. Nativo via método context.addInitializer().

3. A Nova Assinatura Universal e o Objeto Context

No padrão moderno do TypeScript 5.0+, todo decorator recebe exatamente dois argumentos fortemente tipados:

  1. target (ou value): O elemento que está sendo decorado (a função do método, o construtor da classe ou undefined para campos).
  2. context: Um objeto rico fornecido pelo compilador com metadados cruciais sobre onde o decorator foi aplicado.
TypeScript: Propriedades do Objeto Context

TypeScript 12 linhas
interface ClassMemberDecoratorContext {
    kind: "class" | "method" | "getter" | "setter" | "field" | "accessor";
    name: string | symbol;
    static: boolean;
    private: boolean;
    access: {
        has: (object: unknown) => boolean;
        get?: (object: unknown) => unknown;
        set?: (object: unknown, value: unknown) => void;
    };
    addInitializer: (initializer: () => void) => void;
}

4. Construindo Seu Primeiro Decorator Moderno de Método

Vamos construir um decorator funcional que intercepta chamadas de método, exibe os argumentos recebidos e mede o tempo de resposta em milissegundos:

TypeScript: Implementação do Decorator @Monitorar

TypeScript 39 linhas
// Assinatura do decorator para métodos de classe no TS 5.0+:
function Monitorar<This, Args extends any[], Return>(
    metodoOriginal: (this: This, ...args: Args) => Return,
    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>
) {
    const nomeMetodo = String(context.name);
 
    // Retornamos uma nova função que substitui o método original na classe
    return function (this: This, ...args: Args): Return {
        console.log(`[INÍCIO] Executando ${nomeMetodo} com args:`, args);
        const inicio = performance.now();
 
        try {
            // Executamos o método original preservando o contexto "this"
            const resultado = metodoOriginal.call(this, ...args);
            const fim = performance.now();
            console.log(`[SUCESSO] ${nomeMetodo} finalizado em ${(fim - inicio).toFixed(2)}ms`);
            return resultado;
        } catch (erro) {
            console.error(`[FALHA] Erro disparado em ${nomeMetodo}:`, erro);
            throw erro;
        }
    };
}
 
// Consumo elegante:
class ServicoFaturamento {
    @Monitorar
    public emitirNotaFiscal(cliente: string, valorCentavos: number): string {
        // Simula processamento
        let soma = 0;
        for (let i = 0; i < 1000000; i++) soma += i;
        return `NF-2026-${cliente.toUpperCase()}-${valorCentavos}`;
    }
}
 
const faturamento = new ServicoFaturamento();
const nota = faturamento.emitirNotaFiscal("Empresa Alpha", 450000);
console.log("Nota gerada:", nota);

5. Decorator Factories (Fábricas de Decorators com Parâmetros)

Muitas vezes você deseja passar parâmetros adicionais para configurar o comportamento do decorator (como níveis de severidade, rotas ou tempos de expiração). Uma Decorator Factory é simplesmente uma função que retorna a função de decorator real:

TypeScript: Decorator Factory com Argumentos

TypeScript 28 linhas
// Fábrica de decorator: aceita parâmetros de configuração
function LimiteTentativas(maxTentativas: number) {
    return function <This, Args extends any[], Return>(
        metodoOriginal: (this: This, ...args: Args) => Return,
        context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>
    ) {
        return function (this: This, ...args: Args): Return {
            let tentativas = 0;
            while (tentativas < maxTentativas) {
                try {
                    tentativas++;
                    return metodoOriginal.call(this, ...args);
                } catch (erro) {
                    console.warn(`Tentativa ${tentativas}/${maxTentativas} falhou.`);
                    if (tentativas >= maxTentativas) throw erro;
                }
            }
            throw new Error("Limite de tentativas excedido.");
        };
    };
}
 
class ClienteHttp {
    @LimiteTentativas(3)
    public conectarGateway(): void {
        console.log("Conectando ao gateway...");
    }
}

6. Exemplo Enterprise: Telemetria e Auditoria de Segurança

Vejamos como uma arquitetura corporativa moderna utiliza o recurso context.addInitializer() para registrar ganchos automáticos de inicialização quando instâncias são criadas:

TypeScript: Sistema Enterprise de Telemetria com TS 5.0

TypeScript 31 linhas
// Decorator que registra a existência de métodos auditáveis na inicialização da classe
function OperacaoSegura(
    metodoOriginal: Function,
    context: ClassMethodDecoratorContext
) {
    const nomeOperacao = String(context.name);
 
    // O método addInitializer executa no momento da instanciação da classe (constructor)
    context.addInitializer(function () {
        console.log(`[SEGURANÇA REGISTRADA] Método "${nomeOperacao}" vinculado para auditoria.`);
    });
 
    return function (this: any, ...args: any[]) {
        console.log(`[AUDITORIA LGPD] Acesso a ${nomeOperacao} às ${new Date().toISOString()}`);
        return metodoOriginal.call(this, ...args);
    };
}
 
class GestaoContasBancarias {
    @OperacaoSegura
    public transferirFundos(contaOrigem: string, contaDestino: string, valor: number): void {
        console.log(`Transferindo R$ ${valor} de ${contaOrigem} para ${contaDestino}`);
    }
}
 
// Ao instanciar a classe, o addInitializer dispara imediatamente:
const banco = new GestaoContasBancarias();
// Log: [SEGURANÇA REGISTRADA] Método "transferirFundos" vinculado para auditoria.
 
// Ao invocar o método, o wrapper de segurança intercepta:
banco.transferirFundos("AG-101", "AG-202", 5000);
⚗️ Teste no Playground IDE Web-ZoneWare
Experimente Decorators modernos do TypeScript 5.0, inspecione o objeto context e crie fábricas de decorators.

Abrir Playground TypeScript →

7. Armadilhas Comuns e Cuidados de Engenharia

  • Conflito com experimentalDecorators: Se o seu arquivo tsconfig.json contiver "experimentalDecorators": true, o compilador ignorará o novo padrão TC39 e forçará a sintaxe legada. Para utilizar decorators modernos do TypeScript 5.0+, remova ou desative essa flag.
  • Ordem de Execução dos Decorators: Quando múltiplos decorators são empilhados sobre o mesmo método (ex: @A @B public metodo()), as fábricas de decorators são avaliadas de cima para baixo (A depois B), mas a execução dos wrappers decorados ocorre de baixo para cima (B depois A, similar à composição matemática de funções).
  • Preservação de Propriedades de Instância: Ao retornar uma nova função para substituir um método, nunca esqueça de utilizar metodoOriginal.call(this, ...args) para manter a referência correta do this da instância da classe.

Resumo da Lição 37

  • Decorators permitem metaprogramação declarativa (inspecionar, anotar e modificar classes e métodos).
  • O TypeScript 5.0 adotou a especificação padrão oficial do JavaScript (TC39 Stage 3), aposentando o antigo modelo legado.
  • Todo decorator moderno recebe o elemento decorado e o objeto ClassMemberDecoratorContext.
  • O objeto context fornece metadados estáticos (nome, se é estático, tipo de membro) e o gancho addInitializer.
  • Decorator Factories são funções que retornam decorators, permitindo a passagem de parâmetros dinâmicos de configuração.

📝 Exercício Prático Desafiador da Lição 37

1. Crie uma Decorator Factory chamada @Depreciado(mensagemAviso?: string) para métodos de classe. Sempre que o método decorado for executado, ele deve emitir um aviso no console (console.warn) alertando o desenvolvedor que o método está obsoleto, incluindo o nome do método capturado via context.name.

2. Aplique seu decorator em uma classe de serviço de pagamentos simulando a substituição de uma API antiga por uma nova.

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