@bereasoftware/nexa 1.0.5 → 1.2.0

package/dist/types/types/index.d.ts

@@ -22,8 +22,31 @@ export interface HttpRequest {
     body?: unknown;
     query?: Record<string, string | number | boolean>;
     params?: Record<string, string | number>;
-    timeout?: number;
+    timeout?: HttpTimeout;
     signal?: AbortSignal;
+    /**
+     * Controls cookie/credential policy for CORS requests. Same as fetch API.
+     * 'omit' | 'same-origin' | 'include'
+     */
+    credentials?: RequestCredentials;
+    /**
+     * Adapter personalizado para esta request (firma igual a fetch).
+     */
+    adapter?: (input: RequestInfo, init?: RequestInit) => Promise<Response>;
+    /**
+     * Si es true (default), convierte automáticamente el body a FormData si detecta archivos.
+     */
+    autoFormData?: boolean;
+    /**
+     * Transport layer to use for this request.
+     * Overrides global transport setting.
+     */
+    transport?: 'fetch' | 'node' | 'http2' | 'deno' | 'bun' | 'cloudflare';
+    /**
+     * Node.js specific transport options for this request.
+     * Overrides global nodeOptions.
+     */
+    nodeOptions?: NodeTransportOptions;
 }
 export interface HttpResponse<T = unknown> {
     status: number;
@@ -39,6 +62,18 @@ export interface HttpErrorDetails {
     statusText?: string;
     code?: string;
     originalError?: unknown;
+    /**
+     * The HTTP request that caused the error (available for both network and HTTP errors)
+     */
+    request?: HttpRequest;
+    /**
+     * The HTTP response if the request reached the server and received a response (HTTP errors only)
+     */
+    response?: HttpResponse<unknown>;
+    /**
+     * The configuration used for the request
+     */
+    config?: HttpRequestConfig;
 }
 export interface ProgressEvent {
     loaded: number;
@@ -60,10 +95,49 @@ export interface ResponseInterceptor {
     onResponse<T = unknown>(response: HttpResponse<T>): HttpResponse<T> | Promise<HttpResponse<T>>;
     onError?(error: HttpErrorDetails): HttpErrorDetails | Promise<HttpErrorDetails>;
 }
+export type RetryCondition = (error: HttpErrorDetails, attempt: number) => boolean;
 export interface RetryStrategy {
     shouldRetry(attempt: number, error: HttpErrorDetails): boolean;
     delayMs(attempt: number): number;
 }
+export interface InlineRetryConfig {
+    maxAttempts?: number;
+    backoffMs?: number;
+    on?: RetryCondition;
+}
+/**
+ * Node.js specific transport configuration for HTTP/1.1 and HTTP/2.
+ */
+export interface NodeTransportOptions {
+    /**
+     * Enable keep-alive connections. Default: true
+     */
+    keepAlive?: boolean;
+    /**
+     * Maximum number of sockets to allow per host. Default: 50
+     */
+    maxSockets?: number;
+    /**
+     * Maximum number of sockets to leave open in a free state. Default: 10
+     */
+    maxFreeSockets?: number;
+    /**
+     * Maximum number of requests per socket. Default: 0 (unlimited)
+     */
+    maxRequestsPerSocket?: number;
+    /**
+     * Socket timeout in milliseconds. Default: 60000 (60 seconds)
+     */
+    timeout?: number;
+    /**
+     * Enable HTTP/2 protocol (only when transport is 'http2').
+     */
+    http2?: boolean;
+    /**
+     * HTTP/2 specific settings.
+     */
+    http2Settings?: Record<string, unknown>;
+}
 export interface CacheStrategy {
     get(key: string): unknown | null;
     set(key: string, value: unknown, ttlMs?: number): void;
@@ -77,12 +151,54 @@ export interface Transformer {
     transform(data: unknown): unknown;
 }
 export type ResponseType = 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData' | 'stream' | 'auto';
+/**
+ * Timeout configuration for HTTP requests.
+ * - number: total timeout for the entire request (connection + response)
+ * - object: differentiated timeouts for connection and response phases
+ */
+export type HttpTimeout = number | {
+    /**
+     * Maximum time to establish connection (TCP/TLS handshake) in milliseconds.
+     * If not specified, no connection timeout is applied.
+     */
+    connection?: number;
+    /**
+     * Maximum time to receive complete response (after connection is established) in milliseconds.
+     * If not specified, no response timeout is applied.
+     */
+    response?: number;
+    /**
+     * Total timeout for the entire request (connection + response) in milliseconds.
+     * If specified, overrides both connection and response timeouts.
+     * Provided for backward compatibility and convenience.
+     */
+    total?: number;
+};
+/**
+ * Configuración extendida para solicitudes HTTP.
+ * - credentials: controla el envío de cookies/credenciales ('omit' | 'same-origin' | 'include').
+ */
 export interface HttpRequestConfig extends HttpRequest {
-    retry?: RetryStrategy | {
-        maxAttempts: number;
-        backoffMs: number;
-    };
-    timeout?: number;
+    /**
+     * Si es true (default), convierte automáticamente el body a FormData si detecta archivos.
+     */
+    autoFormData?: boolean;
+    /**
+     * Compatibilidad con axios: si es true, establece credentials: 'include'; si es false, credentials: 'same-origin'.
+     * Si también se especifica credentials, este campo es ignorado.
+     */
+    withCredentials?: boolean;
+    /**
+     * Permite usar un adapter personalizado para la request (firma igual a fetch).
+     * Útil para mocks, tests, o entornos especiales.
+     */
+    adapter?: (input: RequestInfo, init?: RequestInit) => Promise<Response>;
+    /**
+     * Permite transformar el body antes de serializarlo y enviarlo. Similar a axios.transformRequest.
+     * Puede ser una función o un array de funciones.
+     */
+    transformRequest?: ((data: unknown, headers: Record<string, string>) => unknown) | Array<(data: unknown, headers: Record<string, string>) => unknown>;
+    retry?: RetryStrategy | InlineRetryConfig;
     validate?: Validator;
     transform?: Transformer;
     cache?: {
@@ -93,6 +209,24 @@ export interface HttpRequestConfig extends HttpRequest {
     hooks?: RequestHooks;
     onUploadProgress?: (event: ProgressEvent) => void;
     onDownloadProgress?: (event: ProgressEvent) => void;
+    /**
+     * Enable debug logging for this request. Overrides global debug setting.
+     */
+    debug?: boolean | 'verbose';
+    /**
+     * Custom logger function for this request. Overrides global logger.
+     */
+    logger?: (message: string, data?: unknown) => void;
+    /**
+     * Transport layer to use for this request.
+     * Overrides global transport setting.
+     */
+    transport?: 'fetch' | 'node' | 'http2' | 'deno' | 'bun' | 'cloudflare';
+    /**
+     * Node.js specific transport options for this request.
+     * Overrides global nodeOptions.
+     */
+    nodeOptions?: NodeTransportOptions;
 }
 export interface PaginateOptions<T> {
     /** Extract items from a response page */
@@ -131,12 +265,219 @@ export interface IHttpClient {
 /** Function that removes a previously added interceptor */
 export type Disposer = () => void;
 export interface HttpClientConfig {
+    /**
+     * Adapter global para todas las requests (firma igual a fetch).
+     */
+    adapter?: (input: RequestInfo, init?: RequestInit) => Promise<Response>;
     baseURL?: string;
     defaultHeaders?: Record<string, string>;
-    defaultTimeout?: number;
+    /**
+     * Controls cookie/credential policy for CORS requests. Same as fetch API.
+     * 'omit' | 'same-origin' | 'include'
+     */
+    credentials?: RequestCredentials;
+    /**
+     * Compatibilidad con axios: si es true, establece credentials: 'include'; si es false, credentials: 'same-origin'.
+     * Si también se especifica credentials, este campo es ignorado.
+     */
+    withCredentials?: boolean;
+    defaultTimeout?: HttpTimeout;
     cacheStrategy?: CacheStrategy;
     validateStatus?: (status: number) => boolean;
     maxConcurrent?: number;
     defaultResponseType?: ResponseType;
     defaultHooks?: RequestHooks;
+    /**
+     * Permite transformar el body antes de serializarlo y enviarlo por defecto en todas las requests.
+     */
+    transformRequest?: ((data: unknown, headers: Record<string, string>) => unknown) | Array<(data: unknown, headers: Record<string, string>) => unknown>;
+    /**
+     * Si es true (default), convierte automáticamente el body a FormData si detecta archivos.
+     */
+    autoFormData?: boolean;
+    /**
+     * Enable debug logging for requests/responses. true for basic logs, 'verbose' for detailed logs.
+     */
+    debug?: boolean | 'verbose';
+    /**
+     * Custom logger function. If provided, replaces the default console.log with custom logging.
+     */
+    logger?: (message: string, data?: unknown) => void;
+    /**
+     * Transport layer to use for HTTP requests.
+     * - 'fetch': Uses global fetch API (default)
+     * - 'node': Uses Node.js http/https modules with HTTP/1.1
+     * - 'http2': Uses Node.js http2 module (HTTP/2)
+     * - 'deno': Uses Deno's fetch API (Deno environment)
+     * - 'bun': Uses Bun's fetch API (Bun environment)
+     * - 'cloudflare': Uses Cloudflare Workers fetch API
+     *
+     * When 'node' or 'http2' is specified, nodeOptions can be used to configure
+     * keep-alive, connection pooling, and other Node-specific settings.
+     *
+     * Note: Node transports are only available in Node.js environments.
+     * Deno, Bun, and Cloudflare transports use their respective fetch implementations.
+     */
+    transport?: 'fetch' | 'node' | 'http2' | 'deno' | 'bun' | 'cloudflare';
+    /**
+     * Node.js specific transport options.
+     * Only applies when transport is 'node' or 'http2'.
+     */
+    nodeOptions?: NodeTransportOptions;
+}
+/**
+ * WebSocket connection options
+ */
+export interface WebSocketOptions {
+    /** WebSocket protocols (subprotocols) */
+    protocols?: string | string[];
+    /** Headers to send during handshake */
+    headers?: Record<string, string>;
+    /** Automatic reconnection settings */
+    reconnect?: {
+        /** Enable automatic reconnection (default: true) */
+        enabled?: boolean;
+        /** Base delay in ms for exponential backoff (default: 1000) */
+        baseDelay?: number;
+        /** Maximum delay in ms (default: 30000) */
+        maxDelay?: number;
+        /** Maximum number of reconnect attempts (default: Infinity) */
+        maxAttempts?: number;
+        /** Called before each reconnection attempt */
+        onReconnecting?: (attempt: number, delay: number) => void;
+    };
+    /** Timeout for connection establishment in ms (default: 10000) */
+    timeout?: number;
+    /** Callback for connection open */
+    onOpen?: (event: Event) => void;
+    /** Callback for connection close */
+    onClose?: (event: CloseEvent) => void;
+    /** Callback for connection error */
+    onError?: (event: Event) => void;
+    /** Enable heartbeat/ping-pong to keep connection alive */
+    heartbeat?: {
+        /** Interval in ms to send ping (default: 30000) */
+        interval?: number;
+        /** Timeout in ms to wait for pong before closing (default: 5000) */
+        timeout?: number;
+        /** Custom ping message (default: 'ping') */
+        pingMessage?: string | ArrayBuffer | Blob;
+        /** Custom pong message (default: 'pong') */
+        pongMessage?: string | ArrayBuffer | Blob;
+    };
+}
+/**
+ * Server-Sent Events (SSE) connection options
+ */
+export interface SSEOptions {
+    /** Headers to send with the request */
+    headers?: Record<string, string>;
+    /** Request method (default: GET) */
+    method?: string;
+    /** Request body (for POST requests) */
+    body?: unknown;
+    /** Whether to send credentials (cookies) (default: same-origin) */
+    credentials?: RequestCredentials;
+    /** Timeout for connection establishment in ms (default: 10000) */
+    timeout?: number;
+    /** Automatic reconnection settings */
+    reconnect?: {
+        /** Enable automatic reconnection (default: true) */
+        enabled?: boolean;
+        /** Base delay in ms for exponential backoff (default: 1000) */
+        baseDelay?: number;
+        /** Maximum delay in ms (default: 30000) */
+        maxDelay?: number;
+        /** Maximum number of reconnect attempts (default: Infinity) */
+        maxAttempts?: number;
+        /** Called before each reconnection attempt */
+        onReconnecting?: (attempt: number, delay: number) => void;
+    };
+    /** Callback for connection open */
+    onOpen?: (event: Event) => void;
+    /** Callback for connection error */
+    onError?: (event: Event) => void;
+    /** Callback for connection close */
+    onClose?: () => void;
+}
+/**
+ * Real-time message event
+ */
+export interface RealtimeMessageEvent<T = unknown> {
+    /** Message data (parsed if possible) */
+    data: T;
+    /** Raw message data */
+    raw: string | ArrayBuffer | Blob;
+    /** Message type (for WebSocket: 'message', for SSE: event type) */
+    type: string;
+    /** Timestamp when message was received */
+    timestamp: number;
+}
+/**
+ * Real-time client interface
+ */
+export interface IRealtimeClient {
+    /** Connect to the server */
+    connect(): Promise<void>;
+    /** Disconnect from the server */
+    disconnect(): void;
+    /** Send a message */
+    send(data: string | ArrayBuffer | Blob): void;
+    /** Subscribe to messages */
+    onMessage<T = unknown>(callback: (event: RealtimeMessageEvent<T>) => void): () => void;
+    /** Subscribe to connection open events */
+    onOpen(callback: (event: Event) => void): () => void;
+    /** Subscribe to connection close events */
+    onClose(callback: (event?: CloseEvent) => void): () => void;
+    /** Subscribe to connection error events */
+    onError(callback: (event: Event) => void): () => void;
+    /** Get connection status */
+    getStatus(): 'connecting' | 'open' | 'closing' | 'closed';
+    /** Get connection statistics */
+    getStats(): {
+        messagesSent: number;
+        messagesReceived: number;
+        connectionTime: number;
+        reconnectAttempts: number;
+    };
+}
+/**
+ * WebSocket client interface (extends IRealtimeClient)
+ */
+export interface IWebSocketClient extends IRealtimeClient {
+    /** WebSocket instance */
+    readonly socket: WebSocket | null;
+    /** Send JSON data (automatically serialized) */
+    sendJson(data: unknown): void;
+    /** Subscribe to specific message types */
+    onMessageType<T = unknown>(type: string, callback: (data: T) => void): () => void;
+}
+/**
+ * SSE client interface (extends IRealtimeClient)
+ */
+export interface ISSEClient extends IRealtimeClient {
+    /** EventSource instance */
+    readonly source: EventSource | null;
+    /** Subscribe to specific event types */
+    onEvent<T = unknown>(event: string, callback: (data: T) => void): () => void;
+    /** Last event ID */
+    readonly lastEventId: string | null;
+}
+declare global {
+    interface Deno {
+        readonly version: {
+            deno: string;
+        };
+    }
+    const Deno: Deno | undefined;
+    interface Bun {
+        readonly version: string;
+    }
+    const Bun: Bun | undefined;
+    const WebSocketPair: {
+        new (): {
+            0: WebSocket;
+            1: WebSocket;
+        };
+    } | undefined;
 }

package/dist/types/utils/index.d.ts

@@ -129,6 +129,43 @@ export declare function createDedupeMiddleware(options?: {
  * Pre-configured deduplication middleware for GET requests
  */
 export declare const dedupeMiddleware: Middleware<HttpContext>;
+/**
+ * Rate limiting middleware factory - limits requests per time window
+ */
+export declare function createRateLimitMiddleware(options?: {
+    /** Maximum number of requests per window */
+    maxRequests: number;
+    /** Time window in milliseconds (default: 60000 = 1 minute) */
+    windowMs?: number;
+    /** Function to generate rate limit key (default: uses request URL) */
+    keyGenerator?: (ctx: HttpContext) => string;
+    /** Custom error response when limit is exceeded (default: 429 Too Many Requests) */
+    errorResponse?: {
+        status: number;
+        body: unknown;
+    };
+}): Middleware<HttpContext>;
+/**
+ * Pre-configured rate limit middleware: 100 requests per minute per endpoint
+ */
+export declare const rateLimitMiddleware: Middleware<HttpContext>;
+/**
+ * Circuit breaker middleware factory - prevents cascading failures
+ */
+export declare function createCircuitBreakerMiddleware(options?: {
+    /** Failure threshold to open circuit (default: 5) */
+    failureThreshold?: number;
+    /** Time in ms to wait before attempting again (default: 30000) */
+    resetTimeout?: number;
+    /** Function to determine if a response is a failure (default: status >= 500) */
+    isFailure?: (ctx: HttpContext) => boolean;
+    /** Function to generate circuit key (default: uses request URL) */
+    keyGenerator?: (ctx: HttpContext) => string;
+}): Middleware<HttpContext>;
+/**
+ * Pre-configured circuit breaker middleware
+ */
+export declare const circuitBreakerMiddleware: Middleware<HttpContext>;
 /**
  * HTTP Context passed through middleware chain
  */
@@ -389,4 +426,35 @@ export declare class DedupePlugin implements Plugin {
     name: string;
     setup(manager: PluginManager): void;
 }
+/**
+ * Rate limiting plugin - adds rate limiting middleware
+ */
+export declare class RateLimitPlugin implements Plugin {
+    name: string;
+    private options;
+    constructor(options?: {
+        maxRequests?: number;
+        windowMs?: number;
+        keyGenerator?: (ctx: HttpContext) => string;
+        errorResponse?: {
+            status: number;
+            body: unknown;
+        };
+    });
+    setup(manager: PluginManager): void;
+}
+/**
+ * Circuit breaker plugin - adds circuit breaker middleware
+ */
+export declare class CircuitBreakerPlugin implements Plugin {
+    name: string;
+    private options;
+    constructor(options?: {
+        failureThreshold?: number;
+        resetTimeout?: number;
+        isFailure?: (ctx: HttpContext) => boolean;
+        keyGenerator?: (ctx: HttpContext) => string;
+    });
+    setup(manager: PluginManager): void;
+}
 export type { HttpErrorDetails };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bereasoftware/nexa",
-  "version": "1.0.5",
+  "version": "1.2.0",
   "type": "module",
   "main": "./dist/nexa.cjs.js",
   "module": "./dist/nexa.es.js",
@@ -16,6 +16,12 @@
       "import": "./dist/nexa.es.js",
       "require": "./dist/nexa.cjs.js",
       "default": "./dist/nexa.umd.js"
+    },
+    "./testing": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/nexa.es.js",
+      "require": "./dist/nexa.cjs.js",
+      "default": "./dist/nexa.umd.js"
     }
   },
   "files": [
@@ -47,6 +53,8 @@
   "author": "John Andrade <johnandrade@bereasoft.com>",
   "license": "MIT",
   "description": "Nexa is a TypeScript HTTP client library that combines the power of fetch with the convenience of axios, while adhering to SOLID principles. It provides a flexible and extensible API for making HTTP requests, handling retries, caching, and more.",
+  "about": "Nexa is designed to be a modern, type-safe HTTP client that simplifies the process of making API requests in TypeScript. It offers features such as request and response interceptors, automatic retries with exponential backoff, caching mechanisms, and a result type for better error handling. With support for both ESM and CommonJS, Nexa can be easily integrated into any TypeScript project.",
+  "homepage": "https://github.com/Berea-Soft/nexa",
   "maintainers": [
     {
       "name": "John Andrade",
@@ -81,18 +89,22 @@
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.58.0",
+    "@microsoft/api-extractor": "^7.58.5",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^12.0.6",
     "@semantic-release/npm": "^13.1.5",
-    "@types/node": "^25.5.0",
-    "@vitest/coverage-v8": "^4.1.2",
-    "@vitest/ui": "^4.1.2",
+    "@types/cookie-parser": "^1.4.10",
+    "@types/node": "^25.6.0",
+    "@vitest/coverage-v8": "^4.1.4",
+    "@vitest/ui": "^4.1.4",
     "semantic-release": "^25.0.3",
-    "typescript": "~6.0.2",
-    "vite": "^8.0.3",
+    "typescript": "~6.0.3",
+    "vite": "^8.0.8",
     "vite-plugin-dts": "^4.5.4",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.4"
+  },
+  "dependencies": {
+    "npm": "^11.12.1"
   }
 }