Aula 18 - Decoradores e Metadados em TypeScript 🏷️

📑 1. Fundamentos Teóricos & Análise Técnica

Os Decoradores (Decorators) fornecem um mecanismo declarativo para inspecionar, modificar ou substituir a definição de classes, métodos, acessores e campos em TypeScript. Tradicionalmente utilizados em frameworks corporativos como Angular e NestJS através da flag experimental experimentalDecorators, os decoradores foram padronizados pela especificação do ECMAScript Stage 3, passando a ser suportados nativamente pelo TypeScript 5+.

A especificação Stage 3 adota uma assinatura limpa baseada em funções que recebem o valor alvo e um objeto de contexto (ClassMethodDecoratorContext, ClassFieldDecoratorContext), permitindo: 1. Auditoria e Profiling de Performance: Medição transparente do tempo de execução de métodos sem alterar sua lógica interna. 2. Anotação Declarativa de Rotas: Registro de metadados como @Get('/usuarios') ou @Post('/pedidos') em classes controladoras. 3. Reflexão com reflect-metadata: Associação de metadados invisíveis às classes para resolução automatizada em contêineres de Inversão de Controle (IoC).

📐 Arquitetura Conceitual & Diagrama de Fluxo

sequenceDiagram
    autonumber
    actor Client as Chamada do Método
    participant Decorator as Decorador @LogExecutionTime
    participant Method as Método Original da Classe
    participant Timer as Sistema de Telemetria

    Client->>Decorator: Dispara Execução
    Decorator->>Timer: Marca performance.now() Inicial
    Decorator->>Method: Invoca Método com Argumentos
    Method-->>Decorator: Retorna Resultado
    Decorator->>Timer: Calcula Duração Decorrida
    Decorator->>Client: Retorna Resultado e Registra Log de Telemetria

🔍 Pilares e Diretrizes Técnicas

Nesta unidade, aprofundamos os seguintes conceitos fundamentais: - Padrão ECMAScript Stage 3: Compatibilidade futura total com a plataforma web nativa sem dependência de flags legadas. - Separação de Preocupações Transversais (Cross-Cutting Concerns): Logging, segurança e cache isolados em decoradores reutilizáveis. - Objeto Contextual Padronizado: Acesso seguro ao nome do membro, tipo de elemento e ganchos de inicialização (addInitializer). - Imutabilidade de Estrutura: Modificação transparente de comportamento sem reescrever o código do desenvolvedor.

🛠️ 2. Implementação Prática em TypeScript Decorators e Reflect Metadata

Abaixo está a implementação técnica de referência, estruturada com padrões de engenharia de software e foco em robustez:

// log-decorator.ts (Decorador de Método Stage 3)
// Decorador de Método em Conformidade com ECMAScript Stage 3
export function LogExecutionTime() {
  return function <This, Args extends any[], Return>(
    target: (this: This, ...args: Args) => Return,
    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>
  ) {
    const methodName = String(context.name);

    return function (this: This, ...args: Args): Return {
      const start = performance.now();
      const result = target.apply(this, args);
      const duration = (performance.now() - start).toFixed(2);
      console.log(`[Telemetria] ${methodName} executado em ${duration}ms`);
      return result;
    };
  };
}

// Exemplo de Aplicação
export class BillingService {
  @LogExecutionTime()
  processInvoice(amount: number): boolean {
    // Simula processamento pesado
    for (let i = 0; i < 1_000_000; i++) {}
    return amount > 0;
  }
}

💡 Análise Passo a Passo do Código

1. Assinatura Tipada: O decorador preserva os tipos de argumentos (Args) e retorno (Return) da função original.
2. Captura de Contexto: context.name fornece o nome exato do método sem necessidade de reflexão manual.
3. Execução Transparente: target.apply(this, args) garante que o escopo da instância da classe (this) permaneça intacto.

🎯 3. Próximos Passos & Sequência Didática