Adaptadores

Los adaptadores son componentes responsables de gestionar procesos de E/S e integraciones externas. Sirven como puente entre tu lógica de negocio y sistemas externos como bases de datos, APIs, sistemas de archivos o almacenes de caché.

Propósito

Los adaptadores abstraen los detalles de implementación de las dependencias externas, permitiendo:

• Intercambiabilidad - Cambiar fácilmente las implementaciones (por ejemplo, PostgreSQL → MongoDB)

• Capacidad de prueba - Simular dependencias externas en las pruebas

• Aislamiento - Mantener la lógica de negocio independiente de las preocupaciones de la infraestructura

Ubicación

Todos los componentes del adaptador DEBEN colocarse en el src/adapters directorio del proyecto.

src/
└── adapters/
    ├── database/
    ├── storage/
    ├── cache/
    └── external-api/

Interfaces compartidas

Los adaptadores DEBERÍAN construirse pensando en la intercambiabilidad. Define interfaces compartidas en src/types.ts para que múltiples adaptadores puedan implementar el mismo contrato.

Ejemplo: interfaz de almacenamiento

// src/types.ts
export interface IStorage {
  set: (key: string, value: any) => Promise<void>
  get: (key: string) => Promise<any>
  delete: (key: string) => Promise<void>
}

Adaptador de almacenamiento en memoria

Aquí tienes una implementación simple de un adaptador de almacenamiento en memoria, útil para pruebas o desarrollo.

Estructura de directorios

src/adapters/memory-storage/
├── component.ts
├── types.ts
├── errors.ts
└── index.ts

Implementación: component.ts

import { IStorage } from '../../types'

export function createMemoryStorageAdapter(): IStorage {
  // Estado interno - limitado a esta instancia del componente
  const memory: Record<string, any> = {}

  async function set(key: string, value: any): Promise<void> {
    memory[key] = value
  }

  async function get(key: string): Promise<any> {
    return memory[key]
  }

  async function delete(key: string): Promise<void> {
    delete memory[key]
  }

  return {
    set,
    get,
    delete
  }
}

Adaptador de almacenamiento Redis

Aquí tienes un adaptador Redis listo para producción que demuestra la gestión del ciclo de vida.

Implementación: component.ts

import { createClient, RedisClientType } from 'redis'
import { IStorage } from '../../types'
import { RedisConnectionError } from './errors'

export function createRedisStorageAdapter(
  components: Pick<AppComponents, 'config' | 'logs'>
): IStorage {
  const { config, logs } = components
  const logger = logs.getLogger('redis-storage')
  
  const hostUrl = config.requireString('REDIS_URL')
  const client: RedisClientType = createClient({ url: hostUrl })

  // Método de ciclo de vida: se llama cuando el componente se inicia
  async function start(): Promise<void> {
    try {
      await client.connect()
      logger.info('Cliente Redis conectado correctamente')
    } catch (error) {
      logger.error('Error al conectar con Redis', error)
      throw new RedisConnectionError('No se pudo conectar con Redis')
    }
  }

  // Método de ciclo de vida: se llama cuando el componente se detiene
  async function stop(): Promise<void> {
    try {
      await client.quit()
      logger.info('Cliente Redis desconectado')
    } catch (error) {
      logger.error('Error al desconectar el cliente Redis', error)
    }
  }

  async function set(key: string, value: any): Promise<void> {
    const serialized = JSON.stringify(value)
    await client.set(key, serialized)
    logger.debug(`Clave establecida: ${key}`)
  }

  async function get(key: string): Promise<any> {
    const value = await client.get(key)
    logger.debug(`Clave obtenida: ${key}`)
    return value ? JSON.parse(value) : null
  }

  async function delete(key: string): Promise<void> {
    await client.del(key)
    logger.debug(`Clave eliminada: ${key}`)
  }

  return {
    [Lifecycle.ComponentStarted]: start,
    [Lifecycle.ComponentStopped]: stop,
    set,
    get,
    delete
  }
}

Manejo de errores: errors.ts

export class RedisConnectionError extends Error {
  constructor(message: string) {
    super(message)
    this.name = 'RedisConnectionError'
  }
}

Ejemplo de adaptador de base de datos

Aquí tienes un ejemplo de un adaptador de base de datos PostgreSQL.

import { Pool, QueryResult } from 'pg'
import { IDatabase } from '../../types'

export function createPostgresAdapter(
  components: Pick<AppComponents, 'config' | 'logs'>
): IDatabase {
  const { config, logs } = components
  const logger = logs.getLogger('postgres-adapter')

  const pool = new Pool({
    connectionString: config.requireString('DATABASE_URL'),
    max: config.getNumber('DATABASE_POOL_SIZE', 20)
  })

  async function start(): Promise<void> {
    // Probar la conexión
    const client = await pool.connect()
    logger.info('Pool de conexión a la base de datos inicializado')
    client.release()
  }

  async function stop(): Promise<void> {
    await pool.end()
    logger.info('Pool de conexión a la base de datos cerrado')
  }

  async function query<T = any>(
    sql: string,
    params?: any[]
  ): Promise<QueryResult<T>> {
    logger.debug('Ejecutando consulta', { sql, params })
    return pool.query<T>(sql, params)
  }

  return {
    [Lifecycle.ComponentStarted]: start,
    [Lifecycle.ComponentStopped]: stop,
    query
  }
}

Métodos de ciclo de vida

WKC proporciona métodos especiales de ciclo de vida que se llaman automáticamente:

• [Lifecycle.ComponentStarted] o [START_COMPONENT] - Se llama cuando el servicio se inicia

• [Lifecycle.ComponentStopped] o [STOP_COMPONENT] - Se llama cuando el servicio se cierra

Cuándo usar los métodos de ciclo de vida

Usa los métodos de ciclo de vida cuando tu adaptador necesite:

• Establecer conexiones (base de datos, caché, cola de mensajes)

• Inicializar pools o clientes

• Realizar comprobaciones de estado

• Limpiar recursos al cerrar

• Cerrar conexiones correctamente

Buenas prácticas

1. Manejo de errores

Maneja siempre los errores de conexión y lanza errores personalizados con significado:

try {
  await client.connect()
} catch (error) {
  logger.error('La conexión falló', error)
  throw new ConnectionError('No se pudo conectar con el servicio externo')
}

2. Configuración

Usa el componente config para gestionar los ajustes del adaptador:

const {
  host: config.requireString('DB_HOST'),
  port: config.getNumber('DB_PORT', 5432),
  timeout: config.getNumber('DB_TIMEOUT', 30000)
}

3. Registro

Registra las operaciones importantes para depuración y supervisión:

logger.info('Operación completada', { recordId, duration })
logger.warn('Se detectó una consulta lenta', { query, duration })
logger.error('La operación falló', { error, context })

4. Seguridad de tipos

Tipa siempre correctamente tus valores de retorno:

async function getUser(id: string): Promise<User | null> {
  const result = await query<User>('SELECT * FROM users WHERE id = $1', [id])
  return result.rows[0] || null
}

5. Gestión de recursos

Limpia siempre los recursos en el método de ciclo de vida stop:

async function stop(): Promise<void> {
  await pool.end()
  await client.disconnect()
  logger.info('Recursos limpiados')
}

Pruebas de adaptadores

Consulta la documentación de Testing Services (WKC) para obtener una guía detallada sobre cómo probar adaptadores.

Ejemplo rápido

describe('cuando se crea un adaptador de almacenamiento en memoria', () => {
  let storage: IStorage

  beforeEach(() => {
    storage = createMemoryStorageAdapter()
  })

  describe('cuando se establece un valor', () => {
    it('debería almacenar y recuperar el valor', async () => {
      await storage.set('key', 'value')
      const result = await storage.get('key')
      expect(result).toBe('value')
    })
  })
})