@bereasoftware/nexa 1.1.0 → 1.3.0

package/README.md

@@ -1,4 +1,5 @@
 <p align="center">
+  <img src="src/assets/Logo.png" alt="Nexa Logo" />
   <h1 align="center">@bereasoftware/nexa</h1>
   <p align="center">
     Un cliente HTTP moderno y type-safe que combina el poder de <code>fetch</code> con la comodidad de <code>axios</code> — construido sobre principios SOLID.
@@ -6,15 +7,16 @@
 </p>
 
 <p align="center">
-  <a href="#tests"><img src="https://img.shields.io/badge/Tests-233_pasando-brightgreen?style=for-the-badge" alt="Tests" /></a>
-  <a href="#test-coverage"><img src="https://img.shields.io/badge/Coverage-72%25-orange?style=for-the-badge" alt="Coverage" /></a>
+  <a href="#tests"><img src="https://img.shields.io/badge/Tests-213_pasando-brightgreen?style=for-the-badge" alt="Tests" /></a>
+  <a href="#test-coverage"><img src="https://img.shields.io/badge/Coverage-Ver_reporte-orange?style=for-the-badge" alt="Coverage" /></a>
   <a href="https://www.npmjs.com/package/@bereasoftware/nexa"><img src="https://img.shields.io/npm/v/@bereasoftware/nexa?style=for-the-badge" alt="NPM Version" /></a>
   <a href="https://bundlephobia.com/package/@bereasoftware/nexa"><img src="https://img.shields.io/bundlephobia/minzip/@bereasoftware/nexa?label=Bundle&style=for-the-badge" alt="Bundle Size" /></a>
   <a href="https://www.npmjs.com/package/@bereasoftware/nexa"><img src="https://img.shields.io/npm/dm/@bereasoftware/nexa?style=for-the-badge" alt="NPM Downloads" /></a>
   <img src="https://img.shields.io/badge/Node-20%2B-success?style=for-the-badge" alt="Node" />
-  <img src="https://img.shields.io/badge/TypeScript-5.x-3178C6?style=for-the-badge" alt="TypeScript" />
+  <img src="https://img.shields.io/badge/TypeScript-6.x-3178C6?style=for-the-badge" alt="TypeScript" />
   <img src="https://img.shields.io/badge/Dependencias-Cero-brightgreen?style=for-the-badge" alt="Dependencies" />
   <a href="LICENSE"><img src="https://img.shields.io/badge/Licencia-MIT-yellow?style=for-the-badge" alt="License" /></a>
+  <img src="https://img.shields.io/badge/Mantenimiento-Activo-success?style=for-the-badge" alt="Maintenance" />
   <a href="https://github.com/Berea-Soft/nexa"><img src="https://img.shields.io/badge/github-Repositorio-blue?logo=github&style=for-the-badge" alt="Repository" /></a>
 </p>
 
@@ -23,6 +25,16 @@
 > - 🇪🇸 **Español** (este archivo - README.md)
 > - 🇬🇧 **English** (README.en.md)
 
+> 📖 **Documentación adicional:**
+>
+> - [Arquitectura](ARCHITECTURE.md) — Diseño del sistema
+> - [Diseño](DESIGN.md) — Filosofía y decisiones de diseño
+> - [Seguridad](SECURITY.md) — Política de seguridad
+> - [Contribuir](CONTRIBUTING.md) — Guía para colaboradores
+> - [Migración](MIGRATION.md) — Desde axios/fetch
+> - [Soporte](SUPPORT.md) — Cómo obtener ayuda
+> - [Skills](SKILLS.md) — Competencias del proyecto
+
 ---
 
 ## ¿Por qué Nexa?
@@ -48,18 +60,11 @@
 | Validadores y transformadores              |   ❌    |   ❌    |    ✅    |
 | Tracking de duración de respuesta          |   ❌    |   ❌    |    ✅    |
 | Detección inteligente de tipo de respuesta |   ❌    |   ✅    |    ✅    |
-| Transformación de requests (transformRequest)   |   ❌    |   ✅    |    ✅    |
-| Política de credenciales   |   ✅    |   ✅    |    ✅    |
-| Patrón adapter (mocking/testing)   |   ❌    |   ✅    |    ✅    |
-| Conversión automática a FormData   |   ❌    |   ❌    |    ✅    |
-| Contexto de error enriquecido (request/response/config)   |   ❌    |   ✅    |    ✅    |
-| Timeouts diferenciados (conexión vs respuesta)   |   ❌    |   ❌    |    ✅    |
-| Logging de debug (modo desarrollo)         |   ❌    |   ❌    |    ✅    |
-| WebSocket/SSE con reconexión automática    |   ❌    |   ❌    |    ✅    |
-| Rate limiting integrado                    |   ❌    |   ❌    |    ✅    |
-| Circuit breaker para fallos en cascada     |   ❌    |   ❌    |    ✅    |
-| Adaptadores multi-entorno (Node, Deno, Bun, Cloudflare) |   ❌    |   ❌    |    ✅    |
-| Tree-shakeable                             |   ✅    |   ❌    |    ✅    |
+| WebSocket/SSE con reconexión automática    |   ❌    |   ❌    |    ✅    |
+| Rate limiting integrado                    |   ❌    |   ❌    |    ✅    |
+| Circuit breaker para fallos en cascada     |   ❌    |   ❌    |    ✅    |
+| Tree-shakeable                             |   ✅    |   ❌    |    ✅    |
+| Dev Overlay (herramientas de desarrollo)   |   ❌    |   ❌    |    ✅    |
 
 ---
 
@@ -103,6 +108,7 @@
 - [Transformadores](#transformadores)
 - [Pipeline de Middleware](#pipeline-de-middleware)
 - [Sistema de Plugins](#sistema-de-plugins)
+- [Dev Overlay](#dev-overlay)
 - [Streaming](#streaming)
 - [Generics Tipados](#generics-tipados)
 - [Manejo de Errores](#manejo-de-errores)
@@ -225,10 +231,12 @@ const client = createHttpClient({
 | `maxConcurrent`       | `number`                      | `0` (ilimitado)                          | Máximo de peticiones concurrentes                            |
 | `defaultResponseType` | `ResponseType`                | `'auto'`                                 | Estrategia de parseo de respuesta por defecto                |
 | `defaultHooks`        | `RequestHooks`                | `{}`                                     | Hooks de ciclo de vida por defecto para todas las peticiones |
-| `debug`               | `boolean \| 'verbose'`        | `undefined`                              | Habilita logging de debug para requests/responses. `true` para logs básicos, `'verbose'` para logs detallados. |
-| `logger`              | `(message: string, data?: unknown) => void` | `undefined`                              | Función de logging personalizada. Si se proporciona, reemplaza el console.log por defecto con logging personalizado. |
-
----
+| `debug`               | `boolean \| 'verbose'`        | `undefined`                              | Habilita logging de debug para requests/responses. `true` para logs básicos, `'verbose'` para logs detallados. |
+| `logger`              | `(message: string, data?: unknown) => void` | `undefined`                              | Función de logging personalizada. Si se proporciona, reemplaza el console.log por defecto con logging personalizado. |
+
+**Nota:** Las opciones avanzadas `transformRequest`, `credentials`, `withCredentials`, `debug`, `logger`, `transport`, `nodeOptions` y `autoFormData` ya están tipadas, pero no todas están completamente integradas en el pipeline principal de `HttpClient` en esta versión. Úsalas con validación manual hasta que se cierre esa integración.
+
+---
 
 ## Métodos HTTP
 
@@ -362,7 +370,7 @@ await client.post('/api', data, { withCredentials: true });
 
 // Configuración global
 const client = createHttpClient({
-  credentials: 'same-origin', // Por defecto: 'omit'
+  credentials: 'same-origin',
   // o
   withCredentials: true, // Equivalente a credentials: 'include'
 });
@@ -1283,6 +1291,118 @@ manager.register(rateLimitPlugin);
 
 ---
 
+## Dev Overlay
+
+Herramienta visual de desarrollo integrada para depurar y monitorear requests HTTP en tiempo real.
+
+```typescript
+import { createHttpClient, createDevOverlay } from "@bereasoftware/nexa";
+
+// Crear el Dev Overlay - aparece automáticamente
+const { tracker, ui } = createDevOverlay({
+  position: "bottom-right", // top-right, top-left, bottom-left
+  theme: "dark",
+  maxHistory: 200,
+});
+
+// Pasar el tracker al cliente HTTP
+const client = createHttpClient({
+  baseURL: "https://api.example.com",
+  devTracker: tracker,
+});
+
+// ¡Listo! Todas las requests aparecerán en el overlay
+const result = await client.get("/users");
+```
+
+### Características
+
+- **Toggle con teclado** — Presiona `Ctrl+Shift+N` o `Cmd+Shift+N` para mostrar/ocultar
+- **Lista de requests** — Muestra método, status, URL, duración y badges (cache, retries)
+- **Métricas en tiempo real** — Total requests, promedio, throughput, éxitos y fallos
+- **Búsqueda y filtro** — Filtra por URL, método o status (`Ctrl+F`)
+- **Detalle de request** — Click en cualquier request para ver headers, body y timing
+- **Retry rápido** — Reejecuta la URL seleccionada con `fetch` para una verificación rápida
+- **Keyboard shortcuts** — `Ctrl+Shift+N` / `Cmd+Shift+N` (toggle), `Escape` (cerrar), `Ctrl+F` / `Cmd+F` (buscar)
+
+### API
+
+```typescript
+createDevOverlay(config?: DevOverlayConfig): { tracker: RequestTracker; ui: DevOverlayUI }
+```
+
+**Opciones de configuración:**
+
+| Opción | Tipo | Por defecto | Descripción |
+|--------|------|-------------|-------------|
+| `enabled` | `boolean` | `true` | Flag de configuración almacenado por el tracker para habilitar o deshabilitar el overlay desde tu flujo |
+| `position` | `'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Posición del overlay |
+| `theme` | `'dark' \| 'light'` | `'dark'` | Tema visual tipado; la UI actual está optimizada para el tema oscuro |
+| `maxHistory` | `number` | `500` |Máximo de requests en historial |
+| `keyboardShortcut` | `string` | `'ctrl+shift+n'` | Atajo de teclado |
+
+**Notas de comportamiento:**
+
+- `createDevOverlay()` es singleton. Si lo llamas varias veces, reutiliza la misma instancia.
+- `theme` está tipado como `'dark' | 'light'`, pero la UI actual está diseñada principalmente para tema oscuro.
+- El botón de retry del panel usa `fetch()` directo para revalidación rápida; no reaplica automáticamente interceptores ni configuración avanzada del `HttpClient`.
+
+**Métodos del UI:**
+
+```typescript
+ui.show()   // Mostrar overlay
+ui.hide()   // Ocultar overlay
+ui.toggle() // Alternar visibilidad
+ui.destroy() // Desmontar el panel del DOM
+
+tracker.clear() // Limpiar historial
+tracker.getHistory() // Obtener todos los requests
+tracker.getMetrics() // Obtener métricas
+tracker.getConfig() // Obtener configuración resuelta
+tracker.onChange((request) => {}) // Escuchar nuevos requests
+```
+
+**Métodos del módulo:**
+
+```typescript
+getDevOverlay() // Obtener { tracker, ui } actuales o null si no existen
+destroyDevOverlay() // Destruir la instancia singleton actual
+```
+
+**Estructuras expuestas:**
+
+```typescript
+type TrackedRequest = {
+  id: string;
+  method: string;
+  url: string;
+  status?: number;
+  duration: number;
+  timestamp: number;
+  cached: boolean;
+  ok: boolean;
+  code?: string;
+  headers: Record<string, string>;
+  body?: unknown;
+  responseHeaders?: Record<string, string>;
+  retryCount: number;
+};
+
+type DevMetrics = {
+  totalRequests: number;
+  successfulRequests: number;
+  failedRequests: number;
+  cachedRequests: number;
+  avgDuration: number;
+  maxDuration: number;
+  minDuration: number;
+  requestsPerSecond: number;
+  slowestRequests: TrackedRequest[];
+};
+```
+
+---
+
 ## Streaming
 
 Maneja archivos grandes y respuestas streaming:
@@ -1433,7 +1553,7 @@ deferred.reject(new Error("falló"));
 
 ### Contexto de Error Enriquecido
 
-Nexa proporciona contexto de error enriquecido similar a axios, incluyendo la request original, response y configuración en los objetos de error. Esto facilita el debugging.
+`HttpErrorDetails` incluye campos opcionales para `request`, `response` y `config`, pero en esta versión no todos los caminos de error los rellenan de forma consistente. Úsalos como metadatos opcionales, no como garantía fuerte.
 
 ```typescript
 const result = await client.get('/api');
@@ -1445,7 +1565,7 @@ if (!result.ok) {
 }
 ```
 
-Todos los errores ahora incluyen propiedades `request`, `response` (si está disponible), y `config`.
+Si necesitas ese contexto en todos los errores, conviene complementarlo temporalmente con hooks o interceptores propios.
 
 ### Clase HttpError
 
@@ -1570,10 +1690,29 @@ npm run test:watch
 
 # Test coverage
 npm run test:coverage
+
+# UI de tests
+npm run test:ui
 ```
 
 Los tests usan **Vitest** (globals mode) con BDD style (`describe`/`it`/`expect`).
 
+### Linting y Formato
+
+```bash
+# Verificar tipo
+npm run lint
+
+# Corregir errores de estilo
+npm run lint:fix
+
+# Formatear código
+npm run format
+
+# Verificar formato
+npm run format:check
+```
+
 ### Build
 
 ```bash
@@ -1600,6 +1739,22 @@ dist/
   └── types/            (Tipo definitivo .d.ts)
 ```
 
+### Benchmark
+
+```bash
+# Ejecutar benchmark de performance
+npm run benchmark
+```
+
+### Ejemplos
+
+Ver la carpeta `examples/` para ejemplos de uso con diferentes frameworks:
+
+- `react-example.ts` — Uso con React
+- `vue-example.ts` — Uso con Vue
+- `svelte-example.ts` — Uso con Svelte
+- `node-example.ts` — Uso con Node.js
+
 ### Cobertura de Tests
 
 **Cobertura General: 71.4%** — sólida cobertura de tests unitarios con mocking HTTP