@bereasoftware/nexa 1.0.4 → 1.1.0

package/dist/types/http-client/http-client.d.ts

@@ -11,18 +11,19 @@ export declare class HttpClient implements IHttpClient {
     private requestQueue;
     private pendingRequests;
     constructor(config?: HttpClientConfig);
+    private logDebug;
     /**
      * Core request method — all others delegate to this
-     * Pipeline: hooks → cache → interceptors → fetch → parse → validate → transform → interceptors → cache → hooks
+     * Pipeline: hooks → cache → interceptors → transformRequest → fetch → parse → validate → transformResponse → interceptors → cache → hooks
      */
     request<T = unknown>(config: HttpRequestConfig): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
-    get<T = unknown>(url: string, config?: Omit<HttpRequestConfig, 'url' | 'method'>): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
-    post<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, 'url' | 'method' | 'body'>): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
-    put<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, 'url' | 'method' | 'body'>): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
-    patch<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, 'url' | 'method' | 'body'>): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
-    delete<T = unknown>(url: string, config?: Omit<HttpRequestConfig, 'url' | 'method'>): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
-    head(url: string, config?: Omit<HttpRequestConfig, 'url' | 'method'>): Promise<Result<HttpResponse<void>, HttpErrorDetails>>;
-    options(url: string, config?: Omit<HttpRequestConfig, 'url' | 'method'>): Promise<Result<HttpResponse<void>, HttpErrorDetails>>;
+    get<T = unknown>(url: string, config?: Omit<HttpRequestConfig, "url" | "method">): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
+    post<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, "url" | "method" | "body">): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
+    put<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, "url" | "method" | "body">): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
+    patch<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, "url" | "method" | "body">): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
+    delete<T = unknown>(url: string, config?: Omit<HttpRequestConfig, "url" | "method">): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
+    head(url: string, config?: Omit<HttpRequestConfig, "url" | "method">): Promise<Result<HttpResponse<void>, HttpErrorDetails>>;
+    options(url: string, config?: Omit<HttpRequestConfig, "url" | "method">): Promise<Result<HttpResponse<void>, HttpErrorDetails>>;
     addRequestInterceptor(interceptor: RequestInterceptor): Disposer;
     addResponseInterceptor(interceptor: ResponseInterceptor): Disposer;
     clearInterceptors(): void;
@@ -64,7 +65,7 @@ export declare class HttpClient implements IHttpClient {
      * }
      * ```
      */
-    paginate<T = unknown>(url: string, options: PaginateOptions<T>, config?: Omit<HttpRequestConfig, 'url' | 'method'>): AsyncGenerator<T[]>;
+    paginate<T = unknown>(url: string, options: PaginateOptions<T>, config?: Omit<HttpRequestConfig, "url" | "method">): AsyncGenerator<T[]>;
     /**
      * Poll an endpoint until a condition is met.
      * Returns the final response that satisfied `until()`.
@@ -79,15 +80,26 @@ export declare class HttpClient implements IHttpClient {
      * });
      * ```
      */
-    poll<T = unknown>(url: string, options: PollOptions<T>, config?: Omit<HttpRequestConfig, 'url' | 'method'>): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
+    poll<T = unknown>(url: string, options: PollOptions<T>, config?: Omit<HttpRequestConfig, "url" | "method">): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
     private buildRequest;
     private buildUrl;
+    /**
+     * Apply transformRequest functions to the request body and headers.
+     * Combines global transformRequest (from client config) and request-specific transformRequest.
+     * Mutates headers object in place (axios-style).
+     */
+    private applyTransformRequestToRequest;
     private getCacheKey;
     private fetchWithTimeout;
     /**
      * Wraps response body with a progress-tracking ReadableStream
      */
     private trackDownloadProgress;
+    /**
+     * Wraps a promise with a timeout. If the timeout elapses before the promise resolves,
+     * rejects with a TimeoutError.
+     */
+    private withTimeout;
     private parseResponse;
     private parseBody;
     private normalizeError;

package/dist/types/http-client/index.d.ts

@@ -4,4 +4,4 @@
 export { createHttpClient, HttpClient, HttpError, isHttpError } from './http-client.js';
 export type { IHttpClient, HttpRequest, HttpRequestConfig, HttpResponse, HttpErrorDetails, RequestInterceptor, ResponseInterceptor, RetryStrategy, CacheStrategy, Validator, Transformer, HttpClientConfig, ResponseType, RequestHooks, ProgressEvent, PaginateOptions, PollOptions, Disposer, Result, } from '../types/index.js';
 export { Ok, Err } from '../types/index.js';
-export { withTimeout, retry, createSchemaValidator, createRequiredFieldsValidator, validatorIsArray, validatorIsObject, transformSnakeToCamel, transformCamelToSnake, transformFlatten, createProjectionTransformer, createWrapperTransformer, AggressiveRetry, ConservativeRetry, CircuitBreakerRetry, CacheStore, createCacheMiddleware, cacheMiddleware, RequestDeduplicator, createDedupeMiddleware, dedupeMiddleware, MiddlewarePipeline, createPipeline, type Middleware, type HttpContext, createTypedResponse, createTypedRequest, createTypedApiClient, createTypeGuard, createUrl, createApiUrl, TypedObservable, Defer, type TypedResponse, type ApiEndpoint, type ApiSchema, type Url, type ApiUrl, type FileUrl, type UnionToIntersection, type ResultOf, handleStream, streamToFile, createStreamingMiddleware, streamingMiddleware, type StreamOptions, PluginManager, LoggerPlugin, MetricsPlugin, CachePlugin, DedupePlugin, type Plugin, } from '../utils';
+export { withTimeout, retry, createSchemaValidator, createRequiredFieldsValidator, validatorIsArray, validatorIsObject, transformSnakeToCamel, transformCamelToSnake, transformFlatten, createProjectionTransformer, createWrapperTransformer, AggressiveRetry, ConservativeRetry, CircuitBreakerRetry, CacheStore, createCacheMiddleware, cacheMiddleware, RequestDeduplicator, createDedupeMiddleware, dedupeMiddleware, createRateLimitMiddleware, rateLimitMiddleware, createCircuitBreakerMiddleware, circuitBreakerMiddleware, MiddlewarePipeline, createPipeline, type Middleware, type HttpContext, createTypedResponse, createTypedRequest, createTypedApiClient, createTypeGuard, createUrl, createApiUrl, TypedObservable, Defer, type TypedResponse, type ApiEndpoint, type ApiSchema, type Url, type ApiUrl, type FileUrl, type UnionToIntersection, type ResultOf, handleStream, streamToFile, createStreamingMiddleware, streamingMiddleware, type StreamOptions, PluginManager, LoggerPlugin, MetricsPlugin, CachePlugin, DedupePlugin, RateLimitPlugin, CircuitBreakerPlugin, type Plugin, } from '../utils';

package/dist/types/http-client/node-http-adapter.d.ts

@@ -0,0 +1,46 @@
+import { NodeTransportOptions } from '../types/index.js';
+declare class Http2SessionPool {
+    private sessions;
+    private cleanupInterval;
+    private readonly maxIdleTime;
+    private readonly maxRequestsPerSession;
+    constructor();
+    private startCleanup;
+    private cleanup;
+    private closeSession;
+    getSession(origin: string, options?: NodeTransportOptions): Promise<import('http2').ClientHttp2Session>;
+    releaseSession(origin: string): void;
+    getStats(): {
+        sessionCount: number;
+        origins: string[];
+        sessions: {
+            origin: string;
+            requestCount: number;
+            lastUsed: number;
+            closing: boolean | undefined;
+            sessionAlive: boolean;
+        }[];
+    };
+    closeAll(): void;
+}
+/**
+ * Node.js HTTP/1.1 adapter
+ */
+export declare function nodeHttpAdapter(input: RequestInfo, init?: RequestInit, options?: NodeTransportOptions): Promise<Response>;
+/**
+ * Node.js HTTP/2 adapter (basic implementation)
+ */
+export declare function nodeHttp2Adapter(input: RequestInfo, init?: RequestInit, options?: NodeTransportOptions): Promise<Response>;
+/**
+ * Close all HTTP/2 sessions in the pool.
+ * Useful for cleanup in tests or when shutting down the application.
+ */
+export declare function closeHttp2SessionPool(): void;
+/**
+ * Get statistics about the HTTP/2 session pool.
+ */
+export declare function getHttp2SessionPoolStats(): {
+    sessionCount: number;
+    origins: string[];
+};
+export { Http2SessionPool };

package/dist/types/index.d.ts

@@ -3,3 +3,6 @@
  * Combines fetch power + axios convenience with SOLID principles
  */
 export * from './http-client';
+export * from './realtime/index.js';
+export { createMockClient, MockAdapter } from './testing/index.js';
+export type { MockResponse, MockClientOptions } from './testing/index.js';

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

@@ -0,0 +1,9 @@
+/**
+ * Real-time communication clients for WebSocket and Server-Sent Events.
+ * Provides unified API for real-time communication with automatic reconnection,
+ * heartbeat, and plugin support.
+ */
+export type { WebSocketOptions, SSEOptions, RealtimeMessageEvent, IRealtimeClient, IWebSocketClient, ISSEClient, } from '../types/index.js';
+export { createWebSocketClient } from './websocket-client.js';
+export { createSSEClient } from './sse-client.js';
+export { createRealtimePlugin } from './plugin.js';

package/dist/types/realtime/plugin.d.ts

@@ -0,0 +1,12 @@
+import { Plugin, PluginManager } from '../utils/index.js';
+/**
+ * Real-time plugin that adds WebSocket and SSE event listeners to the plugin manager
+ */
+export declare class RealtimePlugin implements Plugin {
+    name: string;
+    setup(manager: PluginManager): void;
+}
+/**
+ * Create a realtime plugin instance
+ */
+export declare function createRealtimePlugin(): RealtimePlugin;

package/dist/types/realtime/sse-client.d.ts

@@ -0,0 +1,5 @@
+import { SSEOptions, ISSEClient } from '../types/index.js';
+/**
+ * Create an SSE client appropriate for the current environment
+ */
+export declare function createSSEClient(url: string, options?: SSEOptions): ISSEClient;

package/dist/types/realtime/websocket-client.d.ts

@@ -0,0 +1,5 @@
+import { WebSocketOptions, IWebSocketClient } from '../types/index.js';
+/**
+ * Create a WebSocket client appropriate for the current environment
+ */
+export declare function createWebSocketClient(url: string, options?: WebSocketOptions): IWebSocketClient;

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

@@ -0,0 +1,5 @@
+/**
+ * Testing utilities for Nexa HTTP Client
+ */
+export { createMockClient, MockAdapter } from './mock-client.js';
+export type { MockResponse, MockClientOptions } from './mock-client.js';

package/dist/types/testing/mock-client.d.ts

@@ -0,0 +1,152 @@
+import { IHttpClient, HttpRequestConfig } from '../types/index.js';
+/**
+ * Configuration for a mocked response
+ */
+export interface MockResponse {
+    /** HTTP status code (default: 200) */
+    status?: number;
+    /** HTTP status text (default: 'OK') */
+    statusText?: string;
+    /** Response headers (default: { 'content-type': 'application/json' }) */
+    headers?: Record<string, string>;
+    /** Response body (will be JSON.stringified if object/array) */
+    data?: any;
+    /** Optional delay in milliseconds before responding */
+    delay?: number;
+    /** Throw a network error instead of returning a response */
+    networkError?: boolean;
+    /** Error message for network error */
+    errorMessage?: string;
+}
+/**
+ * Options for creating a mock client
+ */
+export interface MockClientOptions {
+    /** Base URL to match against (optional) */
+    baseURL?: string;
+    /** Default delay for all responses (optional) */
+    delay?: number;
+    /** Whether to pass through unmatched requests to original adapter (default: false) */
+    passthrough?: boolean;
+}
+/**
+ * Route builder returned by onGet(), onPost(), etc.
+ * Allows fluent API like mockAdapter.onGet('/users').reply(200, users)
+ */
+declare class RouteBuilder {
+    private adapter;
+    private method;
+    private urlPattern;
+    constructor(adapter: MockAdapter, method: string, urlPattern: string | RegExp);
+    /**
+     * Configure a response for this route
+     */
+    reply(status: number, data?: any, headers?: Record<string, string>): MockAdapter;
+    reply(response: MockResponse): MockAdapter;
+    /**
+     * Configure a response that will only be used once
+     */
+    replyOnce(status: number, data?: any, headers?: Record<string, string>): MockAdapter;
+    replyOnce(response: MockResponse): MockAdapter;
+    /**
+     * Configure a network error for this route
+     */
+    networkError(errorMessage?: string): MockAdapter;
+    /**
+     * Configure a timeout error for this route
+     */
+    timeout(): MockAdapter;
+}
+/**
+ * Mock adapter that intercepts HTTP requests and returns configured responses.
+ * Similar to axios-mock-adapter.
+ */
+export declare class MockAdapter {
+    private routes;
+    private originalAdapter?;
+    private mockClient;
+    private options;
+    private defaultResponse;
+    /**
+     * Create a new MockAdapter and attach it to a client.
+     * The original client is not modified. Instead, a new client with the mock adapter is created.
+     * Use the `client` property to access the mock-enabled client.
+     */
+    constructor(client: IHttpClient, options?: MockClientOptions);
+    /**
+     * Get the mock-enabled client
+     */
+    get client(): IHttpClient;
+    /**
+     * Create a mock adapter that can be used as a standalone adapter.
+     * This adapter can be set on any HttpClient via config.adapter.
+     */
+    createAdapter(): (input: RequestInfo, init?: RequestInit) => Promise<Response>;
+    /**
+     * Add a route for GET requests
+     */
+    onGet(urlPattern: string | RegExp): RouteBuilder;
+    /**
+     * Add a route for POST requests
+     */
+    onPost(urlPattern: string | RegExp): RouteBuilder;
+    /**
+     * Add a route for PUT requests
+     */
+    onPut(urlPattern: string | RegExp): RouteBuilder;
+    /**
+     * Add a route for PATCH requests
+     */
+    onPatch(urlPattern: string | RegExp): RouteBuilder;
+    /**
+     * Add a route for DELETE requests
+     */
+    onDelete(urlPattern: string | RegExp): RouteBuilder;
+    /**
+     * Add a route for any HTTP method
+     */
+    onAny(urlPattern: string | RegExp): RouteBuilder;
+    /**
+     * Add a route with a specific HTTP method and response
+     */
+    addRoute(method: string, urlPattern: string | RegExp, response: MockResponse | ((config: HttpRequestConfig) => MockResponse | Promise<MockResponse>), options?: {
+        times?: number;
+    }): this;
+    /**
+     * Reset all mock routes
+     */
+    reset(): void;
+    /**
+     * Restore original adapter (if any)
+     */
+    restore(): void;
+    /**
+     * Helper to create a response configuration
+     */
+    static reply(status: number, data?: any, headers?: Record<string, string>): MockResponse;
+    /**
+     * Helper to create a network error response
+     */
+    static networkError(message?: string): MockResponse;
+    private findMatchingRoute;
+}
+/**
+ * Create a mock client with axios-mock-adapter-like API
+ *
+ * @example
+ * ```typescript
+ * import { createHttpClient } from '@bereasoftware/nexa';
+ * import { createMockClient } from '@bereasoftware/nexa/testing';
+ *
+ * const client = createHttpClient({ baseURL: 'https://api.example.com' });
+ * const mockClient = createMockClient(client);
+ *
+ * mockClient.onGet('/users').reply(200, [{ id: 1 }]);
+ * mockClient.onPost('/users').reply(201, { id: 2 });
+ *
+ * // Use mockClient.client for making requests
+ * const result = await mockClient.client.get('/users');
+ * ```
+ */
+export declare function createMockClient(client: IHttpClient, options?: MockClientOptions): MockAdapter;
+export {};