Awilix para TypeScript: Guía completa del contenedor DI

Awilix es un potente y flexible contenedor de inyección de dependencias (Dependency Injection, DI) para Node.js y navegadores, escrito en TypeScript. Proporciona una forma elegante de gestionar las dependencias en tu aplicación, haciendo que el código sea más modular, testeable y mantenible. En este artículo, analizaremos en detalle cómo usar Awilix en proyectos TypeScript, desde la instalación hasta técnicas avanzadas.

1. ¿Qué es y para qué sirve?

En el desarrollo de software moderno, el principio de inversión de control (IoC) y la inyección de dependencias (DI) se han convertido en el estándar de facto para crear aplicaciones escalables y testeables. Awilix es una implementación de un contenedor DI que se encarga de crear y gestionar el ciclo de vida de los objetos (servicios, repositorios, controladores, etc.). En lugar de crear manualmente instancias de clases dentro de otras clases (lo que genera un fuerte acoplamiento), registras tus dependencias en el contenedor y él las "inyecta" automáticamente donde se necesitan.

¿Para qué sirve? Primero, simplifica radicalmente las pruebas. Puedes reemplazar fácilmente una implementación real (por ejemplo, una base de datos) con un objeto mock durante las pruebas unitarias, simplemente registrando otra dependencia en el contenedor. Segundo, mejora la arquitectura de la aplicación, obligándote a seguir el principio de responsabilidad única (SRP) y a declarar explícitamente tus dependencias. Tercero, Awilix admite varios "estilos de vida" (lifetime) de objetos (singleton, transitorio, ámbito), lo que permite gestionar la memoria y el estado de forma flexible.

Awilix es especialmente bueno para TypeScript gracias a su tipado estricto. Proporciona tipos integrados para registrar y resolver dependencias, lo que permite detectar errores en tiempo de compilación, no en tiempo de ejecución. La biblioteca admite resolución asíncrona de dependencias, trabajo con clases, funciones de fábrica e instancias de objetos ya existentes.

2. Instalación

Para instalar Awilix en tu proyecto TypeScript, ejecuta el siguiente comando en la terminal:

npm install awilix

Awilix tiene soporte integrado para TypeScript, por lo que no necesitas instalar paquetes de tipos por separado (@types/awilix). Todos los tipos ya están incluidos en la biblioteca principal.

3. Inicio rápido — ejemplo mínimo funcional

Vamos a crear una aplicación muy simple que saluda al usuario. Tendremos una clase Greeter que depende de Logger.

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

// 1. Definimos las dependencias
class Logger {
  log(message: string): void {
    console.log(`[LOG]: ${message}`);
  }
}

class Greeter {
  private logger: Logger;

  // La dependencia se inyectará a través del constructor
  constructor({ logger }: { logger: Logger }) {
    this.logger = logger;
  }

  greet(name: string): void {
    this.logger.log(`¡Hola, ${name}!`);
  }
}

// 2. Creamos el contenedor
const container = createContainer();

// 3. Registramos las dependencias
container.register({
  logger: asClass(Logger, { lifetime: Lifetime.SINGLETON }),
  greeter: asClass(Greeter, { lifetime: Lifetime.TRANSIENT }),
});

// 4. Resolvemos (obtenemos) la instancia de Greeter
const greeter = container.resolve<Greeter>('greeter');

// 5. Usamos
greeter.greet('Mundo'); // Salida: [LOG]: ¡Hola, Mundo!

En este ejemplo, creamos un contenedor, registramos dos clases (Logger como singleton y Greeter como objeto transitorio), y luego resolvimos Greeter. Awilix creó automáticamente una instancia de Logger y la pasó al constructor de Greeter.