@bereasoftware/nexa 0.0.1

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

@@ -0,0 +1,392 @@
+import { Validator, Transformer, RetryStrategy, HttpErrorDetails, IHttpClient } from '../types';
+/**
+ * Schema validator using simple checks (can be replaced with Zod, Yup, etc)
+ */
+export declare function createSchemaValidator<T>(schema: Record<keyof T, (value: unknown) => boolean>): Validator;
+/**
+ * Validator that ensures response has required fields
+ */
+export declare function createRequiredFieldsValidator(fields: string[]): Validator;
+/**
+ * Validator that ensures response is an array
+ */
+export declare const validatorIsArray: Validator;
+/**
+ * Validator that ensures response is an object
+ */
+export declare const validatorIsObject: Validator;
+/**
+ * Transform that converts snake_case to camelCase (common API pattern)
+ */
+export declare const transformSnakeToCamel: Transformer;
+/**
+ * Transform that converts camelCase to snake_case
+ */
+export declare const transformCamelToSnake: Transformer;
+/**
+ * Transform that flattens nested data
+ */
+export declare const transformFlatten: Transformer;
+/**
+ * Transform that picks specific fields (projection)
+ */
+export declare function createProjectionTransformer(fields: string[]): Transformer;
+/**
+ * Transform that wraps data in a container
+ */
+export declare function createWrapperTransformer(wrapper: string): Transformer;
+/**
+ * Aggressive retry: retry all errors up to max attempts
+ */
+export declare class AggressiveRetry implements RetryStrategy {
+    private maxAttempts;
+    constructor(maxAttempts?: number);
+    shouldRetry(attempt: number): boolean;
+    delayMs(attempt: number): number;
+}
+/**
+ * Conservative retry: only retry on specific status codes
+ */
+export declare class ConservativeRetry implements RetryStrategy {
+    private retryableStatuses;
+    private maxAttempts;
+    constructor(maxAttempts?: number);
+    shouldRetry(attempt: number, error: HttpErrorDetails): boolean;
+    delayMs(attempt: number): number;
+}
+/**
+ * Circuit breaker pattern: fail fast after threshold
+ */
+export declare class CircuitBreakerRetry implements RetryStrategy {
+    private failureCount;
+    private lastFailureTime;
+    private maxAttempts;
+    private failureThreshold;
+    private resetTimeMs;
+    constructor(maxAttempts?: number, failureThreshold?: number, resetTimeMs?: number);
+    shouldRetry(attempt: number): boolean;
+    delayMs(attempt: number): number;
+    reset(): void;
+}
+/**
+ * Creates an AbortController with a timeout.
+ * Automatically aborts the operation after the specified milliseconds.
+ * The timer is cleaned up when the signal is aborted (either by timeout or externally).
+ * @param ms - Timeout in milliseconds
+ * @returns AbortController that will abort after timeout
+ */
+export declare function withTimeout(ms: number): AbortController;
+/**
+ * Retry helper function that retries an async operation
+ * @param fn - Async function to retry
+ * @param retries - Number of retries (default: 3)
+ * @returns Result of the function call
+ */
+export declare function retry<T>(fn: () => Promise<T>, retries?: number): Promise<T>;
+/**
+ * Simple cache store with TTL support
+ */
+export declare class CacheStore {
+    private cache;
+    get<T>(key: string): T | null;
+    set<T>(key: string, data: T, ttlMs?: number): void;
+    clear(): void;
+    has(key: string): boolean;
+    delete(key: string): void;
+}
+/**
+ * Cache middleware factory - caches HTTP responses with TTL support
+ * Automatically skips caching for non-GET requests
+ */
+export declare function createCacheMiddleware(options?: {
+    cache?: CacheStore;
+    ttlMs?: number;
+    cacheableStatuses?: number[];
+}): Middleware<HttpContext>;
+/**
+ * Pre-configured cache middleware with default 60s TTL
+ */
+export declare const cacheMiddleware: Middleware<HttpContext>;
+/**
+ * Prevents duplicate requests to the same endpoint
+ * Shares pending request promises
+ */
+export declare class RequestDeduplicator {
+    private pending;
+    execute<T>(key: string, fn: () => Promise<T>): Promise<T>;
+    clear(): void;
+}
+/**
+ * Deduplication middleware factory - shares pending requests to the same URL
+ * Prevents duplicate network requests by sharing the same Promise
+ */
+export declare function createDedupeMiddleware(options?: {
+    deduplicator?: RequestDeduplicator;
+    includeBody?: boolean;
+    methods?: string[];
+}): Middleware<HttpContext>;
+/**
+ * Pre-configured deduplication middleware for GET requests
+ */
+export declare const dedupeMiddleware: Middleware<HttpContext>;
+/**
+ * HTTP Context passed through middleware chain
+ */
+export interface HttpContext {
+    request: {
+        method: string;
+        url: string;
+        headers: Record<string, string>;
+        body?: unknown;
+    };
+    response: {
+        status: number;
+        headers: Record<string, string>;
+        body?: unknown;
+    };
+    state: Record<string, unknown>;
+    error?: unknown;
+}
+/**
+ * Middleware function type with Express/Koa-like pattern
+ * Receives context and next() function to proceed through pipeline
+ */
+export type Middleware<T extends HttpContext = HttpContext> = (ctx: T, next: () => Promise<void>) => Promise<void>;
+/**
+ * Create a middleware pipeline executor with proper sequencing
+ * Prevents multiple next() calls and ensures proper error propagation
+ */
+export declare function createPipeline<T extends HttpContext = HttpContext>(middlewares: Middleware<T>[]): (ctx: T) => Promise<void>;
+/**
+ * Legacy: MiddlewarePipeline class (backwards compatible)
+ * For simpler use cases, kept for compatibility
+ */
+export declare class MiddlewarePipeline<T = unknown> {
+    private middlewares;
+    use(middleware: Middleware<T extends HttpContext ? T : HttpContext> | ((data: T) => T | Promise<T>)): this;
+    execute(data: T): Promise<T>;
+    clear(): void;
+}
+/**
+ * Type-safe response wrapper with automatic type inference
+ */
+export interface TypedResponse<T, U = unknown> {
+    ok: boolean;
+    data?: T;
+    error?: U;
+    status: number;
+    headers: Record<string, string>;
+}
+/**
+ * Create a typed response builder
+ */
+export declare function createTypedResponse<T, U = unknown>(status: number, data?: T, error?: U, headers?: Record<string, string>): TypedResponse<T, U>;
+/**
+ * API Endpoint definition with typed request/response
+ */
+export interface ApiEndpoint<TRequest = unknown, TResponse = unknown> {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    request?: TRequest;
+    response: TResponse;
+}
+/**
+ * Create a strongly-typed API client method
+ */
+export declare function createTypedRequest<TRequest, TResponse>(endpoint: ApiEndpoint<TRequest, TResponse>): (client: IHttpClient, req?: TRequest) => Promise<TResponse>;
+/**
+ * API Schema - maps multiple endpoints with automatic type inference
+ */
+export type ApiSchema = Record<string, ApiEndpoint>;
+/**
+ * Create a typed API client from schema
+ */
+export declare function createTypedApiClient<T extends ApiSchema>(schema: T): {
+    request: <K extends keyof T>(client: IHttpClient, endpoint: K, data?: T[K] extends ApiEndpoint<infer TReq, any> ? TReq : never) => Promise<T[K] extends ApiEndpoint<any, infer TRes> ? TRes : never>;
+};
+/**
+ * Observable-like response wrapper for reactive patterns
+ */
+export declare class TypedObservable<T> {
+    private subscribers;
+    private errorSubscribers;
+    private completeSubscribers;
+    subscribe(next?: (value: T) => void, error?: (err: unknown) => void, complete?: () => void): {
+        unsubscribe: () => void;
+    };
+    next(value: T): void;
+    error(err: unknown): void;
+    complete(): void;
+    map<U>(fn: (value: T) => U): TypedObservable<U>;
+    filter(predicate: (value: T) => boolean): TypedObservable<T>;
+}
+/**
+ * Union type helper - extracts success/error types
+ */
+export type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Result type extractor for discriminated unions
+ */
+export type ResultOf<T extends {
+    ok: boolean;
+}> = T extends {
+    ok: true;
+} ? Omit<T, 'ok'> : T extends {
+    ok: false;
+} ? Omit<T, 'ok'> : never;
+/**
+ * Guard function for typing - validates data is T at runtime
+ */
+export declare function createTypeGuard<T>(check: (value: unknown) => value is T): (value: unknown) => T;
+/**
+ * Branded types for URL safety
+ */
+export type Url<T extends string = string> = string & {
+    readonly __url: unique symbol;
+    readonly __type: T;
+};
+export type ApiUrl = Url<'api'>;
+export type FileUrl = Url<'file'>;
+export declare function createUrl<T extends string = string>(url: string): Url<T>;
+export declare function createApiUrl(path: string): ApiUrl;
+/**
+ * Defer pattern for lazy evaluation
+ */
+export declare class Defer<T> {
+    private _promise;
+    private resolveFunc;
+    private rejectFunc;
+    constructor();
+    resolve(value: T): void;
+    reject(reason?: unknown): void;
+    get promise(): Promise<T>;
+    /**
+     * @deprecated Use `defer.promise` getter instead
+     */
+    promise_(): Promise<T>;
+}
+/**
+ * Streaming response handler for large files/streams
+ */
+export interface StreamOptions {
+    chunkSize?: number;
+    onChunk?: (chunk: Uint8Array) => void | Promise<void>;
+    onProgress?: (loaded: number, total: number) => void;
+}
+/**
+ * Handle streaming responses
+ */
+export declare function handleStream(response: Response, options?: StreamOptions): Promise<Uint8Array>;
+/**
+ * Stream to file (Node.js compatible)
+ */
+export declare function streamToFile(response: Response, filePath: string): Promise<void>;
+/**
+ * Streaming middleware factory - handles streaming responses with progress tracking
+ * Useful for large file downloads, real-time data streaming, etc.
+ */
+export declare function createStreamingMiddleware(options?: {
+    onChunk?: (chunk: Uint8Array) => void | Promise<void>;
+    onProgress?: (loaded: number, total: number) => void;
+}): Middleware<HttpContext>;
+/**
+ * Pre-configured streaming middleware with default progress tracking
+ */
+export declare const streamingMiddleware: Middleware<HttpContext>;
+/**
+ * Plugin interface - plugins can extend HttpClient functionality
+ */
+export interface Plugin {
+    name: string;
+    setup(manager: PluginManager): void | Promise<void>;
+}
+/**
+ * Plugin manager for extensible architecture
+ * Integrates cache, deduplication, and middleware
+ */
+export declare class PluginManager {
+    private plugins;
+    private cache;
+    private deduplicator;
+    private middlewares;
+    private listeners;
+    /**
+     * Register a plugin and call its setup method
+     */
+    register(plugin: Plugin): this;
+    /**
+     * Add middleware to the pipeline
+     */
+    addMiddleware(middleware: Middleware<HttpContext>): this;
+    /**
+     * Get cache store
+     */
+    getCache(): CacheStore;
+    /**
+     * Get request deduplicator
+     */
+    getDeduplicator(): RequestDeduplicator;
+    /**
+     * Get middleware pipeline executor
+     */
+    getPipeline(): (ctx: HttpContext) => Promise<void>;
+    /**
+     * Execute middleware pipeline for a context
+     */
+    executePipeline(ctx: HttpContext): Promise<void>;
+    /**
+     * Register event listener
+     */
+    on(event: string, handler: (...args: unknown[]) => void | Promise<void>): this;
+    /**
+     * Emit event to all listeners
+     */
+    emit(event: string, ...args: unknown[]): void;
+    /**
+     * Unregister event listener
+     */
+    off(event: string, handler: (...args: unknown[]) => void): this;
+    /**
+     * Get all registered plugins
+     */
+    getPlugins(): Plugin[];
+    /**
+     * Clear all plugins, middlewares, and listeners
+     */
+    clear(): void;
+}
+/**
+ * Example: Logger plugin - logs HTTP requests and responses
+ */
+export declare const LoggerPlugin: Plugin;
+/**
+ * Example: Metrics plugin - collects request metrics
+ */
+export declare class MetricsPlugin implements Plugin {
+    name: string;
+    private metrics;
+    setup(manager: PluginManager): void;
+    getMetrics(): {
+        requests: number;
+        errors: number;
+        totalTime: number;
+        avgTime: number;
+    };
+}
+/**
+ * Example: Cache plugin - automatically adds caching middleware
+ */
+export declare class CachePlugin implements Plugin {
+    name: string;
+    ttlMs: number;
+    constructor(ttlMs?: number);
+    setup(manager: PluginManager): void;
+}
+/**
+ * Example: Deduplication plugin - prevents duplicate requests
+ */
+export declare class DedupePlugin implements Plugin {
+    name: string;
+    setup(manager: PluginManager): void;
+}
+export type { HttpErrorDetails };

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@bereasoftware/nexa",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/nexa.cjs.js",
+  "module": "./dist/nexa.es.js",
+  "types": "./dist/types/index.d.ts",
+  "unpkg": "./dist/nexa.umd.js",
+  "browser": {
+    "./dist/nexa.umd.js": "./dist/nexa.umd.js",
+    "./dist/nexa.iife.js": "./dist/nexa.iife.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/nexa.es.js",
+      "require": "./dist/nexa.cjs.js",
+      "default": "./dist/nexa.umd.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "keywords": [
+    "http",
+    "client",
+    "typescript",
+    "fetch",
+    "api",
+    "request",
+    "library",
+    "retry",
+    "interceptor",
+    "cache",
+    "result-type",
+    "error-handling",
+    "validator",
+    "transformer",
+    "esm",
+    "commonjs",
+    "type-safe"
+  ],
+  "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.",
+  "maintainers": [
+    {
+      "name": "John Andrade",
+      "email": "johnandrade@bereasoft.com"
+    }
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Berea-Soft/nexa.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Berea-Soft/nexa/issues"
+  },
+  "engines": {
+    "node": ">=20.18.0",
+    "npm": ">=10.8.2"
+  },
+  "browserslist": [
+    "last 2 versions",
+    "not dead",
+    "not IE 11",
+    "> 1%"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "^7.58.0",
+    "@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",
+    "semantic-release": "^25.0.3",
+    "typescript": "~6.0.2",
+    "vite": "^8.0.3",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.1.2"
+  }
+}