@nu-art/http-client 0.401.1

package/core/HttpClient.d.ts

@@ -0,0 +1,92 @@
+import { Logger } from '@nu-art/ts-common';
+import { HttpRequest } from './HttpRequest.js';
+import { AxiosRequestConfig as Axios_RequestConfig } from 'axios';
+import { HttpException } from '../exceptions/HttpException.js';
+import { ApiDef, TypedApi } from '../types/api-types.js';
+/**
+ * HTTP client configuration.
+ */
+export type HttpConfig = {
+    origin?: string;
+    timeout?: number;
+    compress?: boolean;
+};
+/**
+ * HTTP client for creating and configuring typed HTTP requests.
+ *
+ * Manages default configuration (origin, timeout, compression, headers) and provides
+ * a factory method for creating typed HttpRequest instances. All requests created
+ * from this client inherit the default configuration and callbacks.
+ *
+ * Extends Logger for built-in logging capabilities.
+ */
+export declare class HttpClient_Class extends Logger {
+    protected origin?: string;
+    protected timeout: number;
+    protected compress: boolean;
+    private readonly defaultHeaders;
+    protected defaultOnComplete?: (response: unknown, input: unknown, request: HttpRequest<any>) => Promise<any>;
+    protected defaultOnError?: (errorResponse: HttpException) => Promise<any>;
+    private requestOption;
+    /**
+     * Creates a new HTTP client instance.
+     *
+     * @param config - Optional configuration (origin, timeout, compress)
+     * @param label - Optional label for logging (defaults to 'HttpClient')
+     */
+    constructor(config?: HttpConfig, label?: string);
+    /**
+     * Sets the HTTP client configuration.
+     *
+     * Normalizes the origin URL by removing trailing slashes to ensure consistent
+     * URL composition in requests.
+     *
+     * @param config - Configuration object
+     */
+    setConfig(config: HttpConfig): void;
+    getOrigin(): string | undefined;
+    shouldCompress(): boolean;
+    setDefaultOnComplete: (defaultOnComplete: (response: unknown, input: unknown, request: HttpRequest<any>) => Promise<any>) => void;
+    setDefaultOnError: (defaultOnError: (errorResponse: HttpException) => Promise<any>) => void;
+    /**
+     * Adds a default header that will be included in all requests created by this client.
+     *
+     * Headers can be static values (string or array) or functions that return values
+     * (evaluated when creating requests). Functions are useful for dynamic headers
+     * like authentication tokens.
+     *
+     * @param key - Header name
+     * @param header - Header value (string, array, or function returning string/array)
+     */
+    addDefaultHeader(key: string, header: (() => string | string[]) | string | string[]): void;
+    /**
+     * Resolves default headers, evaluating functions and normalizing values.
+     *
+     * Converts all default header definitions into a flat object of string arrays.
+     * Functions are called to get their return values. Throws if header value type
+     * is invalid.
+     *
+     * @returns Object mapping header names to string arrays
+     * @throws BadImplementationException if header value type is invalid
+     */
+    getDefaultHeaders(): {
+        [k: string]: string | string[];
+    };
+    setRequestOption(requestOption: Axios_RequestConfig): this;
+    /**
+     * Creates a new typed HTTP request with default configuration applied.
+     *
+     * The request is pre-configured with:
+     * - Method, timeout, and request options from client defaults
+     * - Default headers (evaluated at creation time)
+     * - Default error and completion callbacks (if set)
+     * - URL (either fullUrl or composed from baseUrl/origin + path)
+     *
+     * @template API - Typed API definition
+     * @param apiDef - API definition with method, path, and optional URL configuration
+     * @param data - Optional request data (used as request key identifier)
+     * @returns Configured HttpRequest instance ready for further customization
+     */
+    createRequest<API extends TypedApi<any, any, any, any>>(apiDef: ApiDef<API>, data?: string): HttpRequest<API>;
+}
+export declare const HttpClient: HttpClient_Class;

package/core/HttpClient.js

@@ -0,0 +1,157 @@
+/*
+ * @nu-art/thunderstorm-http - A robust and type-safe HTTP client for Thunderstorm applications
+ * Copyright (C) 2024 Adam van der Kruk aka TacB0sS
+ * Licensed under the Apache License, Version 2.0
+ */
+// noinspection TypeScriptPreferShortImport
+import { BadImplementationException, Logger } from '@nu-art/ts-common';
+import { HttpRequest } from './HttpRequest.js';
+/**
+ * HTTP client for creating and configuring typed HTTP requests.
+ *
+ * Manages default configuration (origin, timeout, compression, headers) and provides
+ * a factory method for creating typed HttpRequest instances. All requests created
+ * from this client inherit the default configuration and callbacks.
+ *
+ * Extends Logger for built-in logging capabilities.
+ */
+export class HttpClient_Class extends Logger {
+    origin;
+    timeout = 10000;
+    compress = true;
+    defaultHeaders = {};
+    defaultOnComplete;
+    defaultOnError;
+    requestOption = {};
+    /**
+     * Creates a new HTTP client instance.
+     *
+     * @param config - Optional configuration (origin, timeout, compress)
+     * @param label - Optional label for logging (defaults to 'HttpClient')
+     */
+    constructor(config, label = 'HttpClient') {
+        super(label);
+        if (config) {
+            this.setConfig(config);
+        }
+    }
+    /**
+     * Sets the HTTP client configuration.
+     *
+     * Normalizes the origin URL by removing trailing slashes to ensure consistent
+     * URL composition in requests.
+     *
+     * @param config - Configuration object
+     */
+    setConfig(config) {
+        if (config.timeout !== undefined)
+            this.timeout = config.timeout;
+        if (config.compress !== undefined)
+            this.compress = config.compress;
+        if (config.origin) {
+            let origin = config.origin;
+            if (origin.endsWith('/'))
+                origin = origin.substring(0, origin.length - 1);
+            this.origin = origin;
+        }
+    }
+    getOrigin() {
+        return this.origin;
+    }
+    shouldCompress() {
+        return this.compress;
+    }
+    setDefaultOnComplete = (defaultOnComplete) => {
+        this.defaultOnComplete = defaultOnComplete;
+    };
+    setDefaultOnError = (defaultOnError) => {
+        this.defaultOnError = defaultOnError;
+    };
+    /**
+     * Adds a default header that will be included in all requests created by this client.
+     *
+     * Headers can be static values (string or array) or functions that return values
+     * (evaluated when creating requests). Functions are useful for dynamic headers
+     * like authentication tokens.
+     *
+     * @param key - Header name
+     * @param header - Header value (string, array, or function returning string/array)
+     */
+    addDefaultHeader(key, header) {
+        this.defaultHeaders[key] = header;
+    }
+    /**
+     * Resolves default headers, evaluating functions and normalizing values.
+     *
+     * Converts all default header definitions into a flat object of string arrays.
+     * Functions are called to get their return values. Throws if header value type
+     * is invalid.
+     *
+     * @returns Object mapping header names to string arrays
+     * @throws BadImplementationException if header value type is invalid
+     */
+    getDefaultHeaders() {
+        return Object.keys(this.defaultHeaders).reduce((toRet, _key) => {
+            const defaultHeader = this.defaultHeaders[_key];
+            const key = _key.toLowerCase();
+            switch (typeof defaultHeader) {
+                case 'string':
+                    toRet[key] = [defaultHeader];
+                    break;
+                case 'function':
+                    const functionResult = defaultHeader();
+                    // Wrap string results in array, keep arrays as-is
+                    toRet[key] = typeof functionResult === 'string' ? [functionResult] : functionResult;
+                    break;
+                case 'object':
+                    if (Array.isArray(defaultHeader)) {
+                        toRet[key] = defaultHeader;
+                        break;
+                    }
+                // eslint-disable-next-line no-fallthrough
+                case 'boolean':
+                case 'number':
+                case 'symbol':
+                case 'bigint':
+                case 'undefined':
+                    throw new BadImplementationException(`Headers values can only be of type: (() => string | string[]) | string | string[], got type ${typeof defaultHeader} `);
+            }
+            return toRet;
+        }, {});
+    }
+    setRequestOption(requestOption) {
+        this.requestOption = requestOption;
+        return this;
+    }
+    /**
+     * Creates a new typed HTTP request with default configuration applied.
+     *
+     * The request is pre-configured with:
+     * - Method, timeout, and request options from client defaults
+     * - Default headers (evaluated at creation time)
+     * - Default error and completion callbacks (if set)
+     * - URL (either fullUrl or composed from baseUrl/origin + path)
+     *
+     * @template API - Typed API definition
+     * @param apiDef - API definition with method, path, and optional URL configuration
+     * @param data - Optional request data (used as request key identifier)
+     * @returns Configured HttpRequest instance ready for further customization
+     */
+    createRequest(apiDef, data) {
+        const request = new HttpRequest(apiDef.path, data, this.shouldCompress())
+            .setMethod(apiDef.method)
+            .setTimeout(this.timeout)
+            .setRequestOption(this.requestOption)
+            .addHeaders(this.getDefaultHeaders());
+        if (apiDef.fullUrl)
+            request.setUrl(apiDef.fullUrl);
+        else
+            request.setOrigin(apiDef.baseUrl ?? this.origin).setRelativeUrl(apiDef.path);
+        if (this.defaultOnError)
+            request.setOnError(this.defaultOnError);
+        if (this.defaultOnComplete)
+            request.setOnCompleted(this.defaultOnComplete);
+        return request;
+    }
+}
+export const HttpClient = new HttpClient_Class();

package/core/HttpRequest.d.ts

@@ -0,0 +1,205 @@
+import { Logger } from '@nu-art/ts-common';
+import { ApiError_GeneralErrorMessage, ApiErrorResponse, ResponseError } from '@nu-art/ts-common/core/exceptions/types';
+import { AxiosRequestConfig as Axios_RequestConfig, AxiosResponse as Axios_Response } from 'axios';
+import { HttpException } from '../exceptions/HttpException.js';
+import { TS_Progress } from '../types/error-types.js';
+import { HttpMethod, TypedApi } from '../types/api-types.js';
+/**
+ * Typed HTTP request with fluent builder API and comprehensive logging.
+ *
+ * Provides a type-safe, chainable interface for building and executing HTTP requests.
+ * Extends Logger for built-in request lifecycle logging (verbose, debug, info, warning, error).
+ *
+ * Features:
+ * - Type-safe request/response handling via TypedApi generics
+ * - Fluent builder pattern for configuration
+ * - Automatic JSON parsing of responses
+ * - Request cancellation via AbortController
+ * - Callback chaining for error and completion handlers
+ * - Comprehensive logging at all stages
+ *
+ * @template API - Typed API definition specifying method, response, body, params, and error types
+ */
+export declare class HttpRequest<API extends TypedApi<any, any, any, any>> extends Logger {
+    key: string;
+    requestData: any;
+    protected origin?: string;
+    protected headers: {
+        [s: string]: string[];
+    };
+    protected method: HttpMethod;
+    protected timeout: number;
+    protected body: API['B'];
+    protected url: string;
+    protected params: {
+        [K in keyof API['P']]?: API['P'][K];
+    };
+    protected responseType: string;
+    protected label: string;
+    protected onProgressListener: (ev: TS_Progress) => void;
+    protected aborted: boolean;
+    protected compress: boolean;
+    private onCompleted?;
+    private onError?;
+    private response?;
+    private cancelController;
+    protected status?: number;
+    private requestOption;
+    /**
+     * Creates a new HTTP request instance.
+     *
+     * Automatically extends timeout to 5 minutes in debug mode for development.
+     * Initializes AbortController for request cancellation support.
+     *
+     * @param requestKey - Identifier for this request (used in logging)
+     * @param requestData - Optional data associated with the request
+     * @param shouldCompress - Whether to enable compression (default: false)
+     */
+    constructor(requestKey: string, requestData?: any, shouldCompress?: boolean);
+    resolveTypedException(exception: HttpException<any> | unknown): API['E'] | undefined;
+    getRequestData(): any;
+    setOrigin(origin?: string): this;
+    setOnProgressListener(onProgressListener: (ev: TS_Progress) => void): this;
+    setLabel(label: string): this;
+    setMethod(method: HttpMethod): this;
+    setResponseType(responseType: string): this;
+    setUrlParams(params: API['P']): this;
+    setUrlParam<K extends keyof API['P'] = keyof API['P']>(key: K, value: API['P'][K]): this;
+    setUrl(url: string): this;
+    getUrl(): string;
+    /**
+     * Sets a relative URL path, composing it with the origin.
+     *
+     * Automatically removes leading slashes from the relative path and combines
+     * with origin. Requires origin to be set first.
+     *
+     * @param relativeUrl - Relative path (leading slash is removed if present)
+     * @returns This instance for chaining
+     * @throws BadImplementationException if origin is not set
+     */
+    setRelativeUrl(relativeUrl: string): this;
+    setTimeout(timeout: number): this;
+    setHeaders(headers: {
+        [s: string]: string | string[];
+    }): this;
+    addHeaders(headers: {
+        [s: string]: string | string[];
+    }): this;
+    /**
+     * Sets a header, replacing any existing values for the key.
+     *
+     * Header keys are normalized to lowercase. Multiple calls to setHeader
+     * for the same key will replace previous values.
+     *
+     * @param _key - Header name (case-insensitive, normalized to lowercase)
+     * @param value - Header value(s)
+     * @returns This instance for chaining
+     */
+    setHeader(_key: string, value: string | string[]): this;
+    /**
+     * Adds a header value, appending to existing values if the key already exists.
+     *
+     * Header keys are normalized to lowercase. Multiple values for the same header
+     * are joined with '; ' when the request is executed.
+     *
+     * @param _key - Header name (case-insensitive, normalized to lowercase)
+     * @param value - Header value(s) to append
+     * @returns This instance for chaining
+     */
+    addHeader(_key: string, value: string | string[]): this;
+    removeHeader(key: string): this;
+    protected _addHeaderImpl(key: string, value: string | string[]): this;
+    protected prepareJsonBody(bodyObject: API['B']): any;
+    setBodyAsJson(bodyObject: API['B'], compress?: boolean): this;
+    /**
+     * Sets the request body.
+     *
+     * If compression is enabled and body is a string, automatically adds
+     * 'Content-encoding: gzip' header.
+     *
+     * @param bodyAsString - Request body (any type)
+     * @param _compress - Override compression setting (optional)
+     * @returns This instance for chaining
+     */
+    setBody(bodyAsString: any, _compress?: boolean): this;
+    isValidStatus(statusCode: number): boolean;
+    protected print(): void;
+    /**
+     * Executes the HTTP request and returns the typed response.
+     *
+     * Process:
+     * 1. Validates request isn't aborted
+     * 2. Composes full URL with query parameters
+     * 3. Prepares headers (joins multiple values with '; ')
+     * 4. Sends request via Axios
+     * 5. Validates response status (200-299 considered success)
+     * 6. Attempts JSON parsing (falls back to raw response if not JSON)
+     * 7. Calls completion/error callbacks
+     *
+     * Automatically handles:
+     * - Request cancellation (AbortController)
+     * - Error response parsing
+     * - JSON response parsing
+     * - Callback execution (onError for failures, onCompleted for success)
+     *
+     * @param print - If true, logs request details (URL, params, headers) before execution
+     * @returns Typed response data (API['R'])
+     * @throws HttpException if request fails or returns non-2xx status
+     */
+    execute(print?: boolean): Promise<API['R']>;
+    clearOnCompleted: () => void;
+    /**
+     * Generic callback chaining helper.
+     *
+     * Chains multiple callbacks of the same type, executing them in order.
+     * If an existing callback exists, both are executed (existing first, then new).
+     *
+     * @template T - Callback function type
+     * @param existingCallback - Previously set callback (if any)
+     * @param newCallback - New callback to add
+     * @param setter - Function to set the final callback
+     * @returns This instance for chaining
+     */
+    private setCallback;
+    setOnCompleted: (onCompleted?: (response: API["R"], input: API["P"] | API["B"], request: HttpRequest<API>) => Promise<any>) => this;
+    setOnError(onError?: (errorResponse: HttpException<API['E']>) => Promise<any>): this;
+    getStatus(): number;
+    getResponse(): any;
+    /**
+     * Gets the full Axios response object.
+     *
+     * Returns the complete Axios response including:
+     * - status, statusText
+     * - headers (full object)
+     * - data (response body)
+     * - config (request configuration)
+     *
+     * Useful when you need access to response metadata beyond just the body,
+     * such as response headers, status text, or the full request configuration.
+     *
+     * @returns Full Axios response object
+     * @throws BadImplementationException if response is not yet available (execute() hasn't been called)
+     */
+    getRawResponse(): Axios_Response<API['R']>;
+    /**
+     * Extracts error response from the HTTP response.
+     *
+     * Returns a basic error response structure with the raw response data
+     * as the debug message. Used when status validation fails.
+     *
+     * @returns Error response structure with debug message
+     */
+    getErrorResponse(): ApiErrorResponse<ResponseError | ApiError_GeneralErrorMessage>;
+    private abortImpl;
+    setRequestOption(requestOption: Axios_RequestConfig): this;
+    _getResponseHeader(headerKey: string): string | string[] | undefined;
+    getResponseHeader(headerKey: string): string | string[] | undefined;
+    /**
+     * Aborts the HTTP request.
+     *
+     * Marks the request as aborted and triggers the AbortController signal,
+     * which cancels the underlying Axios request. If executed before the request
+     * completes, the execute() method will throw an HttpException with status 0.
+     */
+    abort(): void;
+}