Soprano

El Cliente HTTP Definitivo para Entornos Modernos.

Soprano no es solo otro cliente HTTP; es un Motor de Solicitudes (Request Engine) diseñado para desarrolladores que exigen perfección, robustez y control total sobre sus interacciones de red. Construido desde cero para superar las limitaciones de herramientas tradicionales, Soprano ofrece un sistema elegante y potente que se siente nativo y futurista.

¿Por qué Soprano?

Mientras que otros clientes simplemente "hacen peticiones", Soprano orquesta todo un ciclo de vida de comunicación.

• Motor Avanzado: Utiliza su propio 1.1.0-SOPRANO-ULTRA engine para gestionar el ciclo de vida de cada byte.
• Intercepción Inteligente: Un sistema de middleware (interceptores) que permite manipular solicitudes y respuestas con precisión quirúrgica.
• Smart Caching: Sistema de caché en memoria con TTL (Time-To-Live) para respuestas instantáneas.
• Control de Concurrencia: Cola de peticiones integrada para evitar saturación de red.
• Resiliencia Automática: Sistema de reintentos (Retries) inteligente integrado en el núcleo.
• Tipado Dinámico: Parsea automáticamente JSON, Blobs, Texto o ArrayBuffers.
• Cero Dependencias Pesadas: Ligero, rápido y construido sobre estándares modernos (fetch API).

Instalación

npm install @ondarion/soprano

Uso Básico

Soprano está diseñado para ser intuitivo pero poderoso.

const soprano = require('@ondarion/soprano');

// Una simple petición GET que se siente mágica
async function obtenerDatos() {
    try {
        const respuesta = await soprano.get('https://jsonplaceholder.typicode.com/posts/1');
        console.log('Datos:', respuesta.data);
        console.log('Estado:', respuesta.status);
    } catch (error) {
        console.error('Error:', error.message);
    }
}

obtenerDatos();

Características Avanzadas

1. El Sistema de Interceptores

Manipula cada paquete antes de que salga o antes de que llegue a tu código.

// Interceptor de Solicitud (Request) - Añade tokens o logs
soprano.interceptors.request.use((config) => {
    console.log(`[Soprano] Iniciando petición a: ${config.url}`);
    config.headers['Authorization'] = 'Bearer MI_TOKEN_SECRETO';
    return config;
});

// Interceptor de Respuesta (Response) - Limpia datos
soprano.interceptors.response.use((respuesta) => {
    // Si la API devuelve { status: 'ok', result: [...] }, podemos devolver directo el result
    if (respuesta.data && respuesta.data.result) {
        respuesta.data = respuesta.data.result;
    }
    return respuesta;
});

2. Resiliencia y Reintentos (Auto-Retry)

Soprano brilla cuando las cosas van mal. Configura reintentos automáticos para conexiones inestables. Esta es una característica nativa del motor, no un plugin externo.

// Si la petición falla, Soprano reintentará automáticamente
await soprano.post('https://api.pagos.com/transaccion', { id: 123 }, {
    retries: 3,        // Intentará 3 veces más si falla (4 intentos total)
    retryDelay: 2000,  // Esperará 2 segundos entre intentos (backoff simple)
    timeout: 5000      // Cancelará si tarda más de 5s por intento
});

3. Smart Caching (TTL)

Acelera tu aplicación almacenando respuestas automáticamente.

// La primera petición va a la red. La segunda (si es < 5s) viene de la caché.
await soprano.get('/api/config', { 
    cache: true, 
    ttl: 5000 
});

4. Control de Concurrencia y Progreso

Maneja cargas masivas y feedback visual de forma nativa.

const downloader = soprano.create({
    concurrency: 2, // Solo 2 descargas simultáneas
    timeout: 30000
});

downloader.get('/archivo-grande.pdf', {
    onDownloadProgress: (progress) => {
        console.log(`Descargado: ${Math.round(progress.progress * 100)}%`);
    }
});

5. Instancias Personalizadas

Crea "clientes" especializados para diferentes partes de tu API, cada uno con su propia configuración aislada.

const clientePagos = soprano.create({
    timeout: 10000,
    headers: { 
        'X-Service-Name': 'ServicioPagos',
        'Content-Type': 'application/json'
    }
});

// Este cliente hereda todo el poder de Soprano pero mantiene su configuración única
await clientePagos.get('https://api.pagos.com/estado');

API de Referencia

soprano.request(config)

El método núcleo. Todos los alias (get, post, etc.) utilizan esto internamente.

Alias de Métodos

• soprano.get(url, [config])
• soprano.delete(url, [config])
• soprano.head(url, [config])
• soprano.options(url, [config])
• soprano.post(url, data, [config])
• soprano.put(url, data, [config])
• soprano.patch(url, data, [config])

Configuración y Rendimiento

El objeto de configuración de Soprano es extensible:

{
  timeout: 0, // 0 = Sin límite de tiempo
  headers: { 'Accept': 'application/json, text/plain, */*' },
  retries: 0,
  retryDelay: 1000,
  cache: false, // Smart Cache desactivado por defecto
  ttl: 60000, // 1 minuto de vida para caché
  concurrency: Infinity, // Sin límite de peticiones simultáneas
  responseType: 'json'
}

Cada respuesta incluye metadatos de rendimiento (perf) para que puedas monitorear la latencia de tu red con precisión.