Awilix para TypeScript: Guia Completo do Container de Injeção de Dependência

Awilix é um container de injeção de dependência (Dependency Injection, DI) poderoso e flexível para Node.js e navegadores, escrito em TypeScript. Ele oferece uma maneira elegante de gerenciar dependências na sua aplicação, tornando o código mais modular, testável e fácil de manter. Neste artigo, vamos detalhar como usar Awilix em projetos TypeScript, desde a instalação até técnicas avançadas.

1. O que é e por que usar

No desenvolvimento de software moderno, o princípio de inversão de controle (IoC) e a injeção de dependência (DI) se tornaram o padrão de fato para criar aplicações escaláveis e testáveis. Awilix é uma implementação de container DI que assume a criação e o gerenciamento do ciclo de vida dos objetos (serviços, repositórios, controladores, etc.). Em vez de criar manualmente instâncias de classes dentro de outras classes (o que gera alto acoplamento), você registra suas dependências no container, e ele as "injeta" automaticamente onde são necessárias.

Por que usar isso? Primeiro, simplifica drasticamente os testes. Você pode facilmente substituir uma implementação real (como um banco de dados) por um mock durante os testes de unidade, bastando registrar uma dependência diferente no container. Segundo, melhora a arquitetura da aplicação, forçando você a seguir o princípio da responsabilidade única (SRP) e declarar explicitamente suas dependências. Terceiro, Awilix suporta diferentes "estilos de vida" (lifetime) dos objetos (singleton, transitório, escopo), permitindo gerenciar memória e estado de forma flexível.

Awilix é especialmente bom para TypeScript devido à sua tipagem estrita. Ele fornece tipos nativos para registro e resolução de dependências, permitindo capturar erros em tempo de compilação, não em execução. A biblioteca suporta resolução assíncrona de dependências, trabalho com classes, funções factory e instâncias de objetos já existentes.

2. Instalação

Para instalar Awilix no seu projeto TypeScript, execute o seguinte comando no terminal:

npm install awilix

Awilix tem suporte nativo a TypeScript, então você não precisa instalar pacotes separados de tipos (@types/awilix). Todos os tipos já estão incluídos na biblioteca principal.

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

Vamos criar uma aplicação simples que saúda o usuário. Teremos uma classe Saudacao que depende de um Logger.

import { createContainer, asClass, Lifetime } from 'awilix';

// 1. Definindo as dependências
class Logger {
  log(mensagem: string): void {
    console.log(`[LOG]: ${mensagem}`);
  }
}

class Saudacao {
  private logger: Logger;

  // A dependência será injetada via construtor
  constructor({ logger }: { logger: Logger }) {
    this.logger = logger;
  }

  saudar(nome: string): void {
    this.logger.log(`Olá, ${nome}!`);
  }
}

// 2. Criando o container
const container = createContainer();

// 3. Registrando as dependências
container.register({
  logger: asClass(Logger, { lifetime: Lifetime.SINGLETON }),
  saudacao: asClass(Saudacao, { lifetime: Lifetime.TRANSIENT }),
});

// 4. Resolvendo (obtendo) a instância de Saudacao
const saudacao = container.resolve<Saudacao>('saudacao');

// 5. Usando
saudacao.saudar('Mundo'); // Saída: [LOG]: Olá, Mundo!

Neste exemplo, criamos um container, registramos duas classes (Logger como singleton e Saudacao como objeto transitório) e então resolvemos Saudacao. Awilix criou automaticamente uma instância de Logger e a passou para o construtor de Saudacao.