O que são Decorators: A Nova Era da Metaprogramação no TypeScript 5.0 (Padrão TC39 Stage 3)
O que são Decorators: A Nova Era da Metaprogramação no TypeScript 5.0 (Padrão TC39 Stage 3)
@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.
📑 Índice do Conteúdo
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:
@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:
target(ouvalue): O elemento que está sendo decorado (a função do método, o construtor da classe ouundefinedpara campos).context: Um objeto rico fornecido pelo compilador com metadados cruciais sobre onde o decorator foi aplicado.
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:
// 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:
// 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:
// 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);
7. Armadilhas Comuns e Cuidados de Engenharia
- Conflito com
experimentalDecorators: Se o seu arquivotsconfig.jsoncontiver"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 (AdepoisB), mas a execução dos wrappers decorados ocorre de baixo para cima (BdepoisA, 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 dothisda 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
contextfornece metadados estáticos (nome, se é estático, tipo de membro) e o ganchoaddInitializer. - 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.
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