@nest-js/http-request-manager

Axios HTTP Request Manager

@nest-js/http-request-manager

Axios HTTP Manager es un módulo avanzado para NestJS que proporciona una capa de abstracción sobre Axios con características adicionales como reintentos automáticos, caché configurable, y sistema de middlewares para procesar solicitudes y respuestas HTTP.

Características Principales

• Sistema de reintentos automáticos: Configura políticas de reintento para solicitudes fallidas
• Caché integrada: Múltiples estrategias de caché con soporte para Redis
• Middlewares: Procesa solicitudes, respuestas y errores con middlewares personalizables
• Configuración flexible: Opciones estáticas o asíncronas para adaptarse a cualquier proyecto
• Integración con NestJS: Diseñado específicamente para trabajar con el ecosistema NestJS

Uso Básico

Configuración del Módulo

import { Module } from '@nestjs/common';
import { HttpModule } from 'http-request-manager';

@Module({
  imports: [
    HttpModule.register({
      // Opciones básicas de Axios
      baseURL: 'https://api.example.com',
      timeout: 5000,
      headers: {
        'Content-Type': 'application/json',
      },
      
      // Configuración de reintentos
      retry: {
        retries: 3,
        retryDelay: (retryCount) => retryCount * 1000, // Retraso exponencial
        statusCodesToRetry: [408, 429, 500, 502, 503, 504], // Códigos de estado HTTP a reintentar
        methodsToRetry: ['get', 'head', 'options', 'delete', 'put'], // Métodos HTTP a reintentar
        retryCondition: (error) => error.code === 'ECONNABORTED', // Condición personalizada
      },
      
      // Configuración de caché
      cache: {
        ttl: 60000, // 1 minuto en milisegundos
        strategy: 'cache-first', // Estrategia de caché
        max: 100, // Número máximo de elementos en caché
        methods: ['get'], // Métodos HTTP a cachear
        shouldCache: (response) => response.status === 200, // Condición para cachear
      },
    }),
  ],
  controllers: [],
  providers: [],
})
export class AppModule {}

Uso en Servicios

import { Injectable } from '@nestjs/common';
import { HttpService } from 'http-request-manager';

@Injectable()
export class ApiService {
  constructor(private readonly httpService: HttpService) {}

  async getData() {
    try {
      const response = await this.httpService.get('/data');
      return response.data;
    } catch (error) {
      // El error ya ha pasado por los middlewares de error
      throw error;
    }
  }

  async postData(data: any) {
    const response = await this.httpService.post('/data', data);
    return response.data;
  }
}

Configuración Avanzada

Configuración Asíncrona

import { Module } from '@nestjs/common';
import { HttpModule } from 'http-request-manager';
import { ConfigModule, ConfigService } from '@nestjs/config';

@Module({
  imports: [
    ConfigModule.forRoot(),
    HttpModule.registerAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (configService: ConfigService) => ({
        baseURL: configService.get('API_BASE_URL'),
        timeout: configService.get('API_TIMEOUT'),
        headers: {
          'Authorization': `Bearer ${configService.get('API_TOKEN')}`,
        },
        retry: {
          retries: configService.get('API_RETRY_COUNT'),
        },
        cache: {
          ttl: configService.get('API_CACHE_TTL'),
          strategy: configService.get('API_CACHE_STRATEGY'),
        },
      }),
    }),
  ],
  // ...
})
export class AppModule {}

Configuración de Caché con Redis

import { Module } from '@nestjs/common';
import { HttpModule } from 'http-request-manager';
import { CacheStrategy } from 'http-request-manager';

@Module({
  imports: [
    HttpModule.register({
      baseURL: 'https://api.example.com',
      cache: {
        ttl: 300000, // 5 minutos
        strategy: CacheStrategy.CACHE_FIRST,
        redis: {
          host: 'localhost',
          port: 6379,
          password: 'password',
          db: 0,
        },
        routes: [
          {
            pattern: '/users/.*', // Expresión regular para rutas
            strategy: CacheStrategy.SIDE_CACHE,
            ttl: 600000, // 10 minutos para rutas específicas
            methods: ['get', 'post'], // Métodos específicos para esta ruta
          },
          {
            pattern: '/products',
            strategy: CacheStrategy.NO_CACHE, // No cachear productos
          },
        ],
      },
    }),
  ],
  // ...
})
export class AppModule {}

Opciones de Configuración

Opciones de Reintentos (RetryOptions)

Opción	Tipo	Descripción	Valor por defecto
retries	number	Número máximo de reintentos	3
retryDelay	number o Function	Tiempo de espera entre reintentos en ms o función que lo calcula	exponentialDelay
statusCodesToRetry	number[]	Códigos de estado HTTP que provocarán un reintento	[408, 429, 500, 502, 503, 504]
methodsToRetry	string[]	Métodos HTTP que se reintentarán	['get', 'head', 'options', 'delete', 'put']
retryCondition	Function	Función personalizada para determinar si se debe reintentar	axiosRetry.isNetworkError

Opciones de Caché (CacheOptions)

Opción	Tipo	Descripción	Valor por defecto
ttl	number	Tiempo de vida en milisegundos	60000 (1 minuto)
max	number	Número máximo de elementos en caché	Sin límite
methods	string[]	Métodos HTTP a cachear	['get']
strategy	CacheStrategy	Estrategia de caché a utilizar	CACHE_FIRST
redis	RedisConfig	Configuración de Redis	undefined (memoria local)
routes	CacheRouteConfig[]	Configuraciones específicas por ruta	[]
shouldCache	Function	Función para determinar si una respuesta debe ser cacheada	undefined
cacheKey	string o Function	Clave de caché personalizada o función para generarla	Generada automáticamente

Configuración de Redis (RedisConfig)

Opción	Tipo	Descripción	Valor por defecto
host	string	Host del servidor Redis	'localhost'
port	number	Puerto del servidor Redis	6379
password	string	Contraseña del servidor Redis	undefined
db	number	Base de datos Redis a utilizar	0

Estrategias de Caché

El módulo soporta cuatro estrategias de caché:

• CACHE_FIRST: Primero intenta obtener datos de la caché, si no están disponibles, realiza la solicitud
• SIDE_CACHE: Realiza la solicitud y actualiza la caché, pero devuelve los datos de la caché si están disponibles
• ONLY_CACHE: Solo usa la caché, no realiza solicitudes si los datos están en caché
• NO_CACHE: No utiliza caché, siempre realiza la solicitud

Sistema de Middlewares

Los middlewares permiten procesar solicitudes, respuestas y errores en diferentes etapas del ciclo de vida de una solicitud HTTP.

Middlewares de Solicitud

httpService.registerRequestMiddleware({
  priority: 10, // Mayor prioridad se ejecuta primero
  process: (config) => {
    // Añadir encabezados de autenticación
    config.headers = config.headers || {};
    config.headers['Authorization'] = `Bearer ${getToken()}`;
    return config;
  },
});

Middlewares de Respuesta

httpService.registerResponseMiddleware({
  priority: 10,
  process: (response) => {
    // Transformar o validar la respuesta
    if (response.data && response.data.status === 'error') {
      throw new Error('API returned error status');
    }
    return response;
  },
});

Middlewares de Error

httpService.registerErrorMiddleware({
  priority: 10,
  process: (error) => {
    // Manejar errores específicos
    if (error.response?.status === 401) {
      // Renovar token y reintentar
      return refreshTokenAndRetry(error);
    }
    return Promise.reject(error);
  },
});

Opciones de Middleware

Opción	Tipo	Descripción	Valor por defecto
priority	number	Prioridad del middleware (menor número = mayor prioridad)	0
process	Function	Función que procesa la solicitud, respuesta o error	Requerido

Ejemplos de Uso

Solicitud GET con Caché

// Solicitud GET con configuración específica de caché
const response = await httpService.get('/users', {
  cache: {
    ttl: 120000, // 2 minutos
    strategy: CacheStrategy.CACHE_FIRST,
  },
});

Solicitud POST con Reintentos Personalizados

// Solicitud POST con configuración específica de reintentos
const response = await httpService.post('/orders', orderData, {
  retry: {
    retries: 5,
    retryDelay: (retryCount) => retryCount * 2000, // Retraso exponencial personalizado
    statusCodesToRetry: [408, 429, 500, 502, 503, 504],
  },
});

Cancelación de Solicitudes

// Crear un token de cancelación
const source = httpService.createCancelToken();

// Realizar solicitud con token de cancelación
const fetchData = httpService.get('/data', {
  cancelToken: source.token,
});

// Cancelar la solicitud si es necesario
source.cancel('Operación cancelada por el usuario');

Configuración por Solicitud

// Configuración específica para una solicitud
const response = await httpService.get('/data', {
  // Opciones estándar de Axios
  headers: {
    'X-Custom-Header': 'value',
  },
  timeout: 3000,
  
  // Opciones específicas del módulo
  retry: {
    retries: 2,
  },
  cache: {
    ttl: 30000, // 30 segundos
    strategy: CacheStrategy.SIDE_CACHE,
  },
});

Manejo de Errores

El servicio HttpService proporciona métodos para manejar errores de manera efectiva:

try {
  const response = await httpService.get('/data');
  return response.data;
} catch (error) {
  if (httpService.isAxiosError(error)) {
    // Error específico de Axios
    if (error.response) {
      // El servidor respondió con un código de estado fuera del rango 2xx
      console.error('Error de respuesta:', error.response.status, error.response.data);
    } else if (error.request) {
      // La solicitud se realizó pero no se recibió respuesta
      console.error('Error de solicitud:', error.request);
    } else {
      // Error al configurar la solicitud
      console.error('Error:', error.message);
    }
  } else {
    // Error no relacionado con Axios
    console.error('Error inesperado:', error);
  }
  throw error;
}

Métodos Disponibles

Métodos HTTP

• get(url, config?): Realiza una solicitud GET
• post(url, data?, config?): Realiza una solicitud POST
• put(url, data?, config?): Realiza una solicitud PUT
• patch(url, data?, config?): Realiza una solicitud PATCH
• delete(url, config?): Realiza una solicitud DELETE
• head(url, config?): Realiza una solicitud HEAD
• options(url, config?): Realiza una solicitud OPTIONS
• request(config): Realiza una solicitud personalizada

Métodos de Utilidad

• getAxiosInstance(): Obtiene la instancia de Axios subyacente
• createCancelToken(): Crea un token para cancelar solicitudes
• isAxiosError(error): Verifica si un error es específico de Axios
• registerRequestMiddleware(middleware): Registra un middleware de solicitud
• registerResponseMiddleware(middleware): Registra un middleware de respuesta
• registerErrorMiddleware(middleware): Registra un middleware de error

Licencia

MIT