reflect-metadata para TypeScript: guia completo com exemplos

Bem-vindo ao guia detalhado sobre a biblioteca reflect-metadata para TypeScript. Esta biblioteca é a base de muitos frameworks modernos, como Angular, NestJS e TypeORM. Ela permite adicionar e ler metadados (dados sobre dados) de classes, métodos, propriedades e parâmetros durante a execução do programa. Se você quer entender como funcionam os decorators e a Injeção de Dependência (DI) em TypeScript, dominar o reflect-metadata é essencial.

1. O que é e para que serve?

reflect-metadata é um polyfill (implementação) para o objeto nativo Reflect, que faz parte da especificação ES2016 (ES7). O principal objetivo da biblioteca é fornecer uma API para trabalhar com metadados que podem ser associados a diversos elementos do código (classes, métodos, propriedades). No JavaScript padrão, essa funcionalidade não existe, por isso o TypeScript requer a instalação de um pacote separado.

Para que serve? Imagine que você está criando um framework. Você precisa saber quais dependências são necessárias para uma classe, quais rotas estão vinculadas aos métodos de um controller, ou quais campos de uma entidade devem ser serializados em JSON. Sem metadados, você teria que armazenar essas informações em arquivos de configuração separados ou usar padrões complexos. O reflect-metadata permite armazenar essas informações diretamente no código, tornando-o mais autodocumentado e fácil de analisar.

A biblioteca está intimamente ligada aos decorators. Um decorator é uma função que é aplicada a uma classe, método ou propriedade. Dentro do decorator, você pode chamar Reflect.defineMetadata para salvar alguma informação e, em outro ponto do programa, usar Reflect.getMetadata para recuperá-la. Essa é a base para implementar Injeção de Dependência, ORM (Object-Relational Mapping), validação e muitos outros padrões.

2. Instalação

A instalação da biblioteca é feita via npm (Node Package Manager). Certifique-se de ter o Node.js instalado (versão 12 ou superior).

npm install reflect-metadata --save

Após a instalação, a biblioteca deve ser importada no início do seu arquivo de entrada (geralmente main.ts ou index.ts) para ficar disponível globalmente.

import "reflect-metadata";

Importante: A importação deve ser feita antes de qualquer outro código que use o Reflect. Se você estiver usando um framework (como Angular), ele fará isso automaticamente. Caso contrário, adicione esta linha no início do arquivo.

Também é necessário ativar o suporte a decorators e metadados no arquivo tsconfig.json:

{
  "compilerOptions": {
    "target": "ES6",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

A flag emitDecoratorMetadata faz com que o compilador TypeScript gere metadados de tipo para elementos decorados. Isso é necessário para o funcionamento de muitos frameworks.

3. Início rápido — exemplo mínimo funcional

Vamos criar um exemplo simples que demonstra como adicionar metadados a uma classe e lê-los.

import "reflect-metadata";

// 1. Define a chave para os metadados
const METADATA_KEY = "minha_chave_personalizada";

// 2. Cria um decorator que adiciona metadados
function MeuDecorator(valor: string) {
    return function (target: any) {
        // target é o construtor da classe
        Reflect.defineMetadata(METADATA_KEY, valor, target);
    };
}

// 3. Aplica o decorator à classe
@MeuDecorator("Esta é minha classe")
class MinhaClasse {
    saudacao() {
        console.l