Decorators JavaScript: Metadados e Transformação

Os Decorators JavaScript, um recurso inspirado em linguagens como Python e Java, fornecem uma maneira poderosa e expressiva de adicionar metadados e transformar classes, métodos, propriedades e parâmetros. Eles oferecem uma sintaxe limpa e declarativa para aprimorar a funcionalidade do código e promover a separação de responsabilidades. Embora ainda sejam uma adição relativamente nova ao ecossistema JavaScript, os decorators estão ganhando popularidade, especialmente em frameworks como Angular e bibliotecas que utilizam metadados para injeção de dependência e outros recursos avançados. Este artigo explora os fundamentos dos decorators JavaScript, sua aplicação e seu potencial para criar bases de código mais fáceis de manter e extensíveis.

O que são Decorators JavaScript?

Em sua essência, decorators são tipos especiais de declarações que podem ser anexadas a classes, métodos, accessors, propriedades ou parâmetros. Eles usam a sintaxe @expression, onde expression deve avaliar para uma função que será chamada em tempo de execução com informações sobre a declaração decorada. Essencialmente, os decorators atuam como funções que modificam ou estendem o comportamento do elemento decorado.

Pense nos decorators como uma forma de envolver ou aumentar o código existente sem modificá-lo diretamente. Este princípio, conhecido como padrão Decorator no design de software, permite adicionar funcionalidade a um objeto dinamicamente.

Habilitando os Decorators

Embora os decorators façam parte do padrão ECMAScript, eles não estão habilitados por padrão na maioria dos ambientes JavaScript. Para usá-los, você normalmente precisará configurar suas ferramentas de compilação. Veja como habilitar decorators em alguns ambientes comuns:

• TypeScript: Os decorators são suportados nativamente no TypeScript. Certifique-se de que a opção do compilador experimentalDecorators esteja definida como true no seu arquivo tsconfig.json:

            {
  "compilerOptions": {
    "target": "esnext",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true, // Opcional, mas frequentemente útil
    "module": "commonjs", // Ou outro sistema de módulo como "es6" ou "esnext"
    "moduleResolution": "node"
  }
}
            

              
                Copy
              
            
          

• Babel: Se você estiver usando o Babel, precisará instalar e configurar o plugin @babel/plugin-proposal-decorators:

            npm install --save-dev @babel/plugin-proposal-decorators

            

              
                Copy
              
            
          

Em seguida, adicione o plugin à sua configuração do Babel (por exemplo, .babelrc ou babel.config.js):

            {
  "plugins": [["@babel/plugin-proposal-decorators", { "version": "2023-05" }]]
}
            

              
                Copy
              
            
          

A opção version é importante e deve corresponder à versão da proposta de decorators que você está alvejando. Consulte a documentação do plugin do Babel para a versão recomendada mais recente.

Tipos de Decorators

Existem vários tipos de decorators, cada um projetado para elementos específicos:

• Decorators de Classe: Aplicados a classes.
• Decorators de Método: Aplicados a métodos dentro de uma classe.
• Decorators de Acessor: Aplicados a acessores getter ou setter.
• Decorators de Propriedade: Aplicados a propriedades de uma classe.
• Decorators de Parâmetro: Aplicados a parâmetros de um método ou construtor.

Decorators de Classe

Decorators de classe são aplicados ao construtor de uma classe e podem ser usados para observar, modificar ou substituir uma definição de classe. Eles recebem o construtor da classe como seu único argumento.

Exemplo:

            function sealed(constructor: Function) {
  Object.seal(constructor);
  Object.seal(constructor.prototype);
}

@sealed
class Greeter {
  greeting: string;
  constructor(message: string) {
    this.greeting = message;
  }
  greet() {
    return "Hello, " + this.greeting;
  }
}

// Tentar adicionar propriedades à classe selada ou ao seu protótipo falhará

            

              
                Copy
              
            
          

Neste exemplo, o decorator @sealed impede modificações futuras na classe Greeter e em seu protótipo. Isso pode ser útil para garantir a imutabilidade ou evitar alterações acidentais.

Decorators de Método

Decorators de método são aplicados a métodos dentro de uma classe. Eles recebem três argumentos:

• target: O protótipo da classe (para métodos de instância) ou o construtor da classe (para métodos estáticos).
• propertyKey: O nome do método que está sendo decorado.
• descriptor: O descritor de propriedade para o método.

Exemplo:

            function log(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;

  descriptor.value = function (...args: any[]) {
    console.log(`Chamando ${propertyKey} com argumentos: ${JSON.stringify(args)}`);
    const result = originalMethod.apply(this, args);
    console.log(`Método ${propertyKey} retornou: ${result}`);
    return result;
  };

  return descriptor;
}

class Calculator {
  @log
  add(x: number, y: number) {
    return x + y;
  }
}

const calculator = new Calculator();
calculator.add(2, 3); // Saída: Chamando add com argumentos: [2,3]
                      //         Método add retornou: 5

            

              
                Copy
              
            
          

O decorator @log registra os argumentos e o valor de retorno do método add. Este é um exemplo simples de como decorators de método podem ser usados para logging, profiling ou outras preocupações transversais (cross-cutting concerns).

Decorators de Acessor

Decorators de acessor são semelhantes aos decorators de método, mas são aplicados a acessores getter ou setter. Eles também recebem os mesmos três argumentos: target, propertyKey e descriptor.

Exemplo:

            function configurable(value: boolean) {
  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    descriptor.configurable = value;
  };
}

class Point {
  private _x: number;
  private _y: number;

  constructor(x: number, y: number) {
    this._x = x;
    this._y = y;
  }

  @configurable(false)
  get x() {
    return this._x;
  }

  set x(value: number) {
      this._x = value;
  }
}

const point = new Point(1, 2);
// Object.defineProperty(point, 'x', { configurable: true }); // Lançaria um erro porque 'x' não é configurável

            

              
                Copy
              
            
          

O decorator @configurable(false) impede que o getter x seja reconfigurado, tornando-o não configurável.

Decorators de Propriedade

Decorators de propriedade são aplicados a propriedades de uma classe. Eles recebem dois argumentos:

• target: O protótipo da classe (para propriedades de instância) ou o construtor da classe (para propriedades estáticas).
• propertyKey: O nome da propriedade que está sendo decorada.

Exemplo:

            function readonly(target: any, propertyKey: string) {
  Object.defineProperty(target, propertyKey, {
    writable: false,
  });
}

class Person {
  @readonly
  name: string;

  constructor(name: string) {
    this.name = name;
  }
}

const person = new Person("Alice");
// person.name = "Bob"; // Isso causará um erro no modo estrito porque 'name' é somente leitura

            

              
                Copy
              
            
          

O decorator @readonly torna a propriedade name somente leitura, impedindo que ela seja modificada após a inicialização.

Decorators de Parâmetro

Decorators de parâmetro são aplicados a parâmetros de um método ou construtor. Eles recebem três argumentos:

• target: O protótipo da classe (para métodos de instância) ou o construtor da classe (para métodos estáticos ou construtores).
• propertyKey: O nome do método ou construtor.
• parameterIndex: O índice do parâmetro na lista de parâmetros.

Decorators de parâmetro são frequentemente usados com reflexão para armazenar metadados sobre os parâmetros de uma função. Esses metadados podem ser usados em tempo de execução para injeção de dependência ou outros fins. Para que isso funcione corretamente, você precisa habilitar a opção do compilador emitDecoratorMetadata em seu arquivo tsconfig.json.

Exemplo (usando reflect-metadata):

            import 'reflect-metadata';

function required(target: Object, propertyKey: string | symbol, parameterIndex: number) {
  let existingRequiredParameters: number[] = Reflect.getOwnMetadata("required", target, propertyKey) || [];
  existingRequiredParameters.push(parameterIndex);
  Reflect.defineMetadata("required", existingRequiredParameters, target, propertyKey);
}

function validate(target: any, propertyName: string, descriptor: TypedPropertyDescriptor) {
  let method = descriptor.value!;

  descriptor.value = function (...args: any[]) {
    let requiredParameters: number[] = Reflect.getOwnMetadata("required", target, propertyName);
    if (requiredParameters) {
      for (let parameterIndex of requiredParameters) {
        if (args[parameterIndex] === null || args[parameterIndex] === undefined) {
          throw new Error(`Argumento obrigatório ausente no índice ${parameterIndex}`);
        }
      }
    }
    return method.apply(this, args);
  };
}

class User {
  name: string;
  age: number;

  constructor(@required name: string, public surname: string, @required age: number) {
    this.name = name;
    this.age = age;
  }

  @validate
  greet(prefix: string, @required salutation: string): string {
    return `${prefix} ${salutation} ${this.name}`;
  }
}

// Uso

try {
  const user1 = new User("John", "Doe", 30);
  console.log(user1.greet("Mr.", "Hello"));

  const user2 = new User(undefined as any, "Doe", null as any);

} catch (error) {
  console.error(error.message);
}

try {
  const user = new User("John", "Doe", 30);
  console.log(user.greet("Mr.", undefined as any));
} catch (error) {
  console.error(error.message);
}


            

              
                Copy
              
            
          

Neste exemplo, o decorator @required marca os parâmetros como obrigatórios. O decorator @validate então usa reflexão (via reflect-metadata) para verificar se os parâmetros obrigatórios estão presentes antes de chamar o método. Este exemplo mostra o uso básico, e é recomendado criar uma validação de parâmetro robusta em um cenário de produção.

Para instalar o reflect-metadata:

            npm install reflect-metadata --save

            

              
                Copy
              
            
          

Usando Decorators para Metadados

Um dos usos primários dos decorators é anexar metadados a classes e seus membros. Esses metadados podem ser usados em tempo de execução para vários fins, como injeção de dependência, serialização e validação. A biblioteca reflect-metadata fornece uma maneira padrão de armazenar e recuperar metadados.

Exemplo:

            import 'reflect-metadata';

const TYPE_KEY = "design:type";
const PARAMTYPES_KEY = "design:paramtypes";
const RETURNTYPE_KEY = "design:returntype";

function Type(type: any) {
    return Reflect.metadata(TYPE_KEY, type);
}


function LogType(target: any, propertyKey: string) {
  const t = Reflect.getMetadata(TYPE_KEY, target, propertyKey);
  console.log(`${target.constructor.name}.${propertyKey} tipo: ${t.name}`);
}

class Demo {
    @LogType
    public name: string;
    constructor(name: string){
      this.name = name;
    }
}

            

              
                Copy
              
            
          

Fábricas de Decorator (Decorator Factories)

Fábricas de decorator (Decorator factories) são funções que retornam um decorator. Elas permitem que você passe argumentos para o decorator, tornando-o mais flexível e reutilizável.

Exemplo:

            function deprecated(deprecationReason: string) {
  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    const originalMethod = descriptor.value;

    descriptor.value = function (...args: any[]) {
      console.warn(`Método ${propertyKey} está obsoleto: ${deprecationReason}`);
      return originalMethod.apply(this, args);
    };

    return descriptor;
  };
}

class LegacyComponent {
  @deprecated("Use o newMethod em vez disso.")
  oldMethod() {
    console.log("Método antigo chamado");
  }

  newMethod() {
    console.log("Novo método chamado");
  }
}

const component = new LegacyComponent();
component.oldMethod(); // Saída: Método oldMethod está obsoleto: Use o newMethod em vez disso.
                       //         Método antigo chamado

            

              
                Copy
              
            
          

A fábrica de decorator @deprecated recebe uma mensagem de depreciação como argumento e registra um aviso quando o método decorado é chamado. Isso permite que você marque métodos como obsoletos e forneça orientação aos desenvolvedores sobre como migrar para alternativas mais recentes.

Casos de Uso do Mundo Real

Os decorators têm uma ampla gama de aplicações no desenvolvimento JavaScript moderno:

• Injeção de Dependência: Frameworks como o Angular dependem fortemente de decorators para injeção de dependência.
• Roteamento: Em aplicações web, decorators podem ser usados para definir rotas para controladores e métodos.
• Validação: Decorators podem ser usados para validar dados de entrada e garantir que eles atendam a certos critérios.
• Autorização: Decorators podem ser usados para impor políticas de segurança e restringir o acesso a certos métodos ou recursos.
• Logging e Profiling: Como mostrado nos exemplos acima, decorators podem ser usados para logging e profiling da execução do código.
• Gerenciamento de Estado: Decorators podem se integrar com bibliotecas de gerenciamento de estado para atualizar componentes automaticamente quando o estado muda.

Benefícios de Usar Decorators

• Legibilidade de Código Aprimorada: Decorators fornecem uma sintaxe declarativa para adicionar funcionalidade, tornando o código mais fácil de entender e manter.
• Separação de Responsabilidades: Decorators permitem separar preocupações transversais (por exemplo, logging, validação, autorização) da lógica de negócios principal.
• Reutilização: Decorators podem ser reutilizados em várias classes e métodos, reduzindo a duplicação de código.
• Extensibilidade: Decorators facilitam a extensão da funcionalidade do código existente sem modificá-lo diretamente.

Desafios e Considerações

• Curva de Aprendizagem: Decorators são um recurso relativamente novo, e pode levar algum tempo para aprender a usá-los de forma eficaz.
• Compatibilidade: Certifique-se de que seu ambiente de destino suporta decorators e que você configurou suas ferramentas de compilação corretamente.
• Depuração: Depurar código que usa decorators pode ser mais desafiador do que depurar código regular, especialmente se os decorators forem complexos.
• Uso Excessivo: Evite o uso excessivo de decorators, pois isso pode tornar seu código mais difícil de entender e manter. Use-os estrategicamente para fins específicos.
• Sobrecarga de Tempo de Execução: Decorators podem introduzir alguma sobrecarga de tempo de execução, especialmente se realizarem operações complexas. Considere as implicações de desempenho ao usar decorators em aplicações críticas de desempenho.

Conclusão

Os Decorators JavaScript são uma ferramenta poderosa para aprimorar a funcionalidade do código e promover a separação de responsabilidades. Ao fornecer uma sintaxe limpa e declarativa para adicionar metadados e transformar classes, métodos, propriedades e parâmetros, os decorators podem ajudá-lo a criar bases de código mais fáceis de manter, reutilizáveis e extensíveis. Embora venham com uma curva de aprendizado e alguns desafios potenciais, os benefícios de usar decorators no contexto certo podem ser significativos. À medida que o ecossistema JavaScript continua a evoluir, os decorators provavelmente se tornarão uma parte cada vez mais importante do desenvolvimento JavaScript moderno.

Considere explorar como os decorators podem simplificar seu código existente ou permitir que você escreva aplicações mais expressivas e fáceis de manter. Com um planejamento cuidadoso e uma compreensão sólida de suas capacidades, você pode aproveitar os decorators para criar soluções JavaScript mais robustas e escaláveis.