@nu-art/http-client 0.401.1

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@nu-art/http-client",
+  "version": "0.401.1",
+  "description": "Type-safe HTTP client with fluent API, comprehensive logging, and request/response type safety",
+  "keywords": [
+    "TacB0sS",
+    "http",
+    "client",
+    "axios",
+    "typescript",
+    "type-safe",
+    "api",
+    "request",
+    "response",
+    "infra",
+    "nu-art",
+    "thunderstorm"
+  ],
+  "homepage": "https://github.com/nu-art-js/thunderstorm",
+  "bugs": {
+    "url": "https://github.com/nu-art-js/thunderstorm/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com:nu-art-js/thunderstorm.git"
+  },
+  "license": "Apache-2.0",
+  "author": "TacB0sS",
+  "scripts": {
+    "build": "tsc"
+  },
+  "contributors": [
+    {
+      "name": "TacB0sS"
+    },
+    {
+      "name": "Cipher",
+      "url": "https://www.linkedin.com/in/itay-leybovich-470b87229/"
+    }
+  ],
+  "publishConfig": {
+    "directory": "dist",
+    "linkDirectory": true
+  },
+  "dependencies": {
+    "@nu-art/ts-common": "0.401.1",
+    "axios": "^1.13.1"
+  },
+  "devDependencies": {
+    "@nu-art/testalot": "0.401.1"
+  },
+  "unitConfig": {
+    "type": "typescript-lib"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  }
+}

package/types/api-types.d.ts

@@ -0,0 +1,142 @@
+import type { HttpRequest } from '../core/HttpRequest.js';
+import type { ResponseError } from './error-types.js';
+import type { QueryParams } from './types.js';
+/**
+ * HTTP method enumeration.
+ *
+ * Standard HTTP methods supported by the client.
+ */
+export declare enum HttpMethod {
+    ALL = "all",
+    POST = "post",
+    GET = "get",
+    PATCH = "patch",
+    DELETE = "delete",
+    PUT = "put",
+    OPTIONS = "options",
+    HEAD = "head"
+}
+/** HTTP methods that use query parameters (no request body) */
+export type HttpMethod_Query = 'get' | 'delete';
+/** HTTP methods that use request body */
+export type HttpMethod_Body = 'post' | 'put' | 'patch';
+/** HTTP methods with no parameters or body */
+export type HttpMethod_Empty = 'options' | 'head';
+/**
+ * Type-safe API definition with full type information for requests and responses.
+ *
+ * Provides compile-time type safety for HTTP API calls, ensuring request bodies,
+ * query parameters, and responses match their declared types.
+ *
+ * @template M - HTTP method (string literal)
+ * @template R - Response type
+ * @template B - Body type (internal representation)
+ * @template P - Query parameters type
+ * @template IB - Input body type (what callers provide, defaults to B)
+ * @template IP - Input params type (what callers provide, defaults to P)
+ * @template E - Error response type
+ *
+ * @example
+ * ```typescript
+ * type MyApi = TypedApi<'post', {id: string}, {name: string}, {filter: string}, {name: string}, {filter: string}>;
+ * // Method: POST
+ * // Response: {id: string}
+ * // Body: {name: string}
+ * // Params: {filter: string}
+ * ```
+ */
+export type TypedApi<M extends string, R, B, P extends QueryParams | undefined, IB = B, IP = P, E extends ResponseError = ResponseError> = {
+    Method: M;
+    Response: R;
+    Body: B;
+    Params: P;
+    InternalParams: IP;
+    InternalBody: IB;
+    Error: E;
+    M: M;
+    R: R;
+    B: B;
+    P: P;
+    IP: IP;
+    IB: IB;
+    E: E;
+};
+/**
+ * Convenience type for APIs that use request bodies (POST, PUT, PATCH).
+ *
+ * @template R - Response type
+ * @template B - Body type
+ * @template IB - Input body type (defaults to B)
+ * @template E - Error type
+ * @template M - HTTP method (defaults to POST)
+ * @template P - Query params type (defaults to never)
+ */
+export type BodyApi<R, B, IB = B, E extends ResponseError = ResponseError, M extends HttpMethod_Body = HttpMethod.POST, P extends QueryParams = never> = TypedApi<M, R, B, P, IB, P, E>;
+/**
+ * Convenience type for APIs that use query parameters (GET, DELETE).
+ *
+ * @template R - Response type
+ * @template P - Query params type
+ * @template E - Error type
+ * @template IP - Input params type (defaults to P)
+ * @template M - HTTP method (defaults to GET)
+ * @template B - Body type (defaults to never)
+ */
+export type QueryApi<R, P extends QueryParams | undefined = QueryParams, E extends ResponseError = ResponseError, IP = P, M extends HttpMethod_Query = HttpMethod.GET, B = never> = TypedApi<M, R, B, P, B, IP, E>;
+/**
+ * Convenience type for APIs with no parameters or body (OPTIONS, HEAD).
+ *
+ * @template R - Response type
+ * @template M - HTTP method (must be OPTIONS or HEAD)
+ * @template E - Error type
+ * @template P - Query params type (defaults to never)
+ * @template B - Body type (defaults to never)
+ */
+export type EmptyApi<R, M extends HttpMethod_Empty, E extends ResponseError = ResponseError, P extends QueryParams = never, B = never> = TypedApi<M, R, B, P, B, P, E>;
+/**
+ * API definition for creating requests.
+ *
+ * Specifies the HTTP method, URL configuration, and optional timeout.
+ * Either `fullUrl` (absolute) or `baseUrl` + `path` (relative) must be provided.
+ *
+ * @template API - Typed API definition
+ */
+export type ApiDef<API extends TypedApi<any, any, any, any, any>> = {
+    method: API['Method'];
+    fullUrl?: string;
+    baseUrl?: string;
+    path: string;
+    timeout?: number;
+    errors?: API['Error']['type'];
+};
+/**
+ * Recursive API structure type for organizing APIs into namespaces.
+ *
+ * Allows nesting APIs in a hierarchical structure, where each level can contain
+ * either a TypedApi or another ApiStruct (sub-namespace).
+ */
+export type ApiStruct = {
+    [k: string]: (TypedApi<any, any, any, any, any> | ApiStruct);
+};
+export type ApiDefResolver<API_Struct extends ApiStruct> = API_Struct extends TypedApi<any, any, any, any, any> ? ApiDef<API_Struct> : API_Struct extends ApiStruct ? ApiDefRouter<API_Struct> : never;
+export type ApiDefRouter<API_Struct extends ApiStruct> = {
+    [P in keyof API_Struct]: ApiDefResolver<API_Struct[P]>;
+};
+export type ApiDefCaller<API_Struct extends ApiStruct> = API_Struct extends TypedApi<any, any, any, any, any> ? ApiCaller<API_Struct> : API_Struct extends ApiStruct ? ApiCallerRouter<API_Struct> : never;
+export type ApiCallerRouter<API_Struct extends ApiStruct> = {
+    [P in keyof API_Struct]: ApiDefCaller<API_Struct[P]>;
+};
+export type ApiCaller_Query<API extends QueryApi<any, any, any, any, HttpMethod_Query>> = API['IP'] extends undefined ? () => HttpRequest<API> : (query: API['IP']) => HttpRequest<API>;
+export type ApiCaller_Body<API extends BodyApi<any, any, any, any, HttpMethod_Body>> = API['IB'] extends undefined ? () => HttpRequest<API> : (query: API['IB']) => HttpRequest<API>;
+export type ApiCaller_Any<API extends TypedApi<any, any, any, any, any>> = (body: API['IB'], query: API['IP']) => HttpRequest<API>;
+/**
+ * Resolves the appropriate caller function type based on API method.
+ *
+ * Automatically selects the correct function signature:
+ * - QueryApi → function(query?) → HttpRequest
+ * - BodyApi → function(body?) → HttpRequest
+ * - Other → function(body, query) → HttpRequest
+ *
+ * @template API - Typed API definition
+ */
+export type ApiCaller<API> = API extends QueryApi<any, any, any, any, HttpMethod_Query> ? ApiCaller_Query<API> : API extends BodyApi<any, any, any, any, HttpMethod_Body> ? ApiCaller_Body<API> : API extends TypedApi<any, any, any, any, any> ? ApiCaller_Any<API> : never;

package/types/api-types.js

@@ -0,0 +1,21 @@
+/*
+ * @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
+ */
+/**
+ * HTTP method enumeration.
+ *
+ * Standard HTTP methods supported by the client.
+ */
+export var HttpMethod;
+(function (HttpMethod) {
+    HttpMethod["ALL"] = "all";
+    HttpMethod["POST"] = "post";
+    HttpMethod["GET"] = "get";
+    HttpMethod["PATCH"] = "patch";
+    HttpMethod["DELETE"] = "delete";
+    HttpMethod["PUT"] = "put";
+    HttpMethod["OPTIONS"] = "options";
+    HttpMethod["HEAD"] = "head";
+})(HttpMethod || (HttpMethod = {}));

package/types/error-types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Generic response error type for API error handling.
+ *
+ * @template K - Error type identifier (string literal)
+ * @template Data - Error data payload
+ */
+export type ResponseError<K extends string = string, Data = any> = {
+    /** Error type identifier */
+    type: K;
+    /** Error data payload */
+    data: Data;
+};
+/**
+ * Standard error message response type.
+ *
+ * Used for general error messages in API responses.
+ */
+export type ApiError_GeneralErrorMessage = ResponseError<'error-message', {
+    message: string;
+}>;
+/**
+ * API error response structure.
+ *
+ * Contains an optional debug message (for developers) and an optional
+ * structured error object (for clients).
+ *
+ * @template E - Response error type
+ */
+export type ApiErrorResponse<E extends ResponseError> = {
+    /** Optional debug message (typically includes stack traces, internal details) */
+    debugMessage?: string;
+    /** Optional structured error object */
+    error?: E;
+};
+/**
+ * Progress event type for upload/download tracking.
+ *
+ * Mirrors the ProgressEvent interface for compatibility with XMLHttpRequest
+ * and fetch progress events.
+ */
+export type TS_Progress = {
+    readonly lengthComputable: boolean;
+    readonly loaded: number;
+    readonly target: any;
+    readonly total: number;
+};

package/types/error-types.js

@@ -0,0 +1,6 @@
+/*
+ * @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
+ */
+export {};

package/types/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Type for route/query parameters with dynamic value support.
+ *
+ * Supports static values (string, number, boolean) or functions that return values.
+ * Functions are evaluated when composing the query string, allowing dynamic
+ * parameter generation (e.g., timestamps, IDs).
+ */
+export type RouteParams = {
+    [key: string]: string | number | boolean | undefined | (() => string | number);
+};
+/**
+ * Static query parameters type (no functions).
+ *
+ * Used for API type definitions where parameters are known at compile time.
+ */
+export type QueryParams = {
+    [key: string]: string | number | boolean | undefined;
+};
+/**
+ * URL query parameters with string values only.
+ *
+ * Used for URL composition where all values must be strings.
+ */
+export type UrlQueryParams = {
+    [key: string]: string | undefined;
+};

package/types/types.js

@@ -0,0 +1,6 @@
+/*
+ * @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
+ */
+export {};

package/utils/http-codes.d.ts

@@ -0,0 +1,197 @@
+import { ApiError_GeneralErrorMessage } from '../types/error-types.js';
+import { ApiException } from '../exceptions/HttpException.js';
+/**
+ * HTTP status code constants organized by status class.
+ *
+ * Provides:
+ * - Standard HTTP status codes (1XX, 2XX, 3XX, 4XX, 5XX)
+ * - Custom status codes (459-463, 490, 555, 560-561, 598-599)
+ * - Factory functions for 4XX and 5XX errors that create ApiException instances
+ *
+ * **Usage**:
+ * - For errors: `throw HttpCodes._4XX.NOT_FOUND('User not found', 'User ID: 123')`
+ * - For status codes: `HttpCodes._2XX.OK` (returns 200)
+ *
+ * **Note**: 4XX and 5XX codes are functions that create exceptions, while
+ * 1XX, 2XX, and 3XX are just numeric constants.
+ */
+export declare const HttpCodes: {
+    readonly _1XX: {
+        readonly CONTINUE: 100;
+        readonly SWITCHING_PROTOCOLS: 101;
+        readonly PROCESSING: 102;
+        readonly EARLY_HINTS: 103;
+    };
+    readonly _2XX: {
+        readonly OK: 200;
+        readonly CREATED: 201;
+        readonly ACCEPTED: 202;
+        readonly NON_AUTHORITATIVE_INFORMATION: 203;
+        readonly NO_CONTENT: 204;
+        readonly RESET_CONTENT: 205;
+        readonly PARTIAL_CONTENT: 206;
+        readonly MULTI_STATUS: 207;
+        readonly ALREADY_REPORTED: 208;
+        readonly IM_USED: 226;
+    };
+    readonly _3XX: {
+        readonly MULTIPLE_CHOICES: 300;
+        readonly MOVED_PERMANENTLY: 301;
+        readonly FOUND: 302;
+        readonly SEE_OTHER: 303;
+        readonly NOT_MODIFIED: 304;
+        readonly USE_PROXY: 305;
+        readonly TEMPORARY_REDIRECT: 307;
+        readonly PERMANENT_REDIRECT: 308;
+    };
+    readonly _4XX: {
+        readonly BAD_REQUEST: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly UNAUTHORIZED: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly PAYMENT_REQUIRED: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly FORBIDDEN: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly NOT_FOUND: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly METHOD_NOT_ALLOWED: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly NOT_ACCEPTABLE: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly PROXY_AUTHENTICATION_REQUIRED: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly REQUEST_TIMEOUT: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly CONFLICT: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly GONE: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly LENGTH_REQUIRED: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly PRECONDITION_FAILED: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly PAYLOAD_TOO_LARGE: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly URI_TOO_LONG: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly UNSUPPORTED_MEDIA_TYPE: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly RANGE_NOT_SATISFIABLE: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly EXPECTATION_FAILED: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly IM_A_TEAPOT: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly FAILED_VALIDATION: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly MISDIRECTED_REQUEST: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly UNPROCESSABLE_ENTITY: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly LOCKED: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly FAILED_DEPENDENCY: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly TOO_EARLY: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly UPGRADE_REQUIRED: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly PRECONDITION_REQUIRED: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly TOO_MANY_REQUESTS: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly REQUEST_HEADER_FIELDS_TOO_LARGE: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly UNAVAILABLE_FOR_LEGAL_REASONS: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly ENTITY_MISSING: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly ENTITY_ALREADY_EXISTS: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly ENTITY_IS_OUTDATED: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly INTERNAL_MISMATCH: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly ENTITY_DOESNT_EXISTS: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly OPERATION_FAILED: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+    };
+    readonly _5XX: {
+        readonly INTERNAL_SERVER_ERROR: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly NOT_IMPLEMENTED: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly BAD_GATEWAY: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly SERVICE_UNAVAILABLE: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly GATEWAY_TIMEOUT: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly HTTP_VERSION_NOT_SUPPORTED: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly VARIANT_ALSO_NEGOTIATES: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly INSUFFICIENT_STORAGE: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly LOOP_DETECTED: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly NOT_EXTENDED: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly NETWORK_AUTHENTICATION_REQUIRED: ((userMessage: string, debugMessage?: string, cause?: Error) => ApiException<ApiError_GeneralErrorMessage>) & {
+            code: number;
+        };
+        readonly DEBUG_WHO_CALLED_THIS: 555;
+        readonly BAD_IMPLEMENTATION: 560;
+        readonly IMPLEMENTATION_MISSING: 561;
+        readonly SHOULD_NOT_HAPPENED: 598;
+        readonly MUST_NEVER_HAPPENED: 599;
+    };
+};

package/utils/http-codes.js

@@ -0,0 +1,125 @@
+/*
+ * @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
+ */
+import { ApiException } from '../exceptions/HttpException.js';
+/**
+ * Creates a factory function for HTTP error exceptions.
+ *
+ * Returns a function that creates an ApiException with the specified HTTP status code.
+ * The function also has a `code` property for accessing the status code.
+ *
+ * @param code - HTTP status code
+ * @returns Function that creates ApiException instances, with a `code` property
+ */
+function createGeneralError(code) {
+    const errorFunction = (userMessage, debugMessage = userMessage, cause) => new ApiException(code, debugMessage, cause).setErrorBody({
+        type: 'error-message',
+        data: { message: userMessage }
+    });
+    return Object.assign(errorFunction, { code });
+}
+/**
+ * HTTP status code constants organized by status class.
+ *
+ * Provides:
+ * - Standard HTTP status codes (1XX, 2XX, 3XX, 4XX, 5XX)
+ * - Custom status codes (459-463, 490, 555, 560-561, 598-599)
+ * - Factory functions for 4XX and 5XX errors that create ApiException instances
+ *
+ * **Usage**:
+ * - For errors: `throw HttpCodes._4XX.NOT_FOUND('User not found', 'User ID: 123')`
+ * - For status codes: `HttpCodes._2XX.OK` (returns 200)
+ *
+ * **Note**: 4XX and 5XX codes are functions that create exceptions, while
+ * 1XX, 2XX, and 3XX are just numeric constants.
+ */
+export const HttpCodes = {
+    _1XX: {
+        CONTINUE: 100,
+        SWITCHING_PROTOCOLS: 101,
+        PROCESSING: 102,
+        EARLY_HINTS: 103,
+    },
+    _2XX: {
+        OK: 200,
+        CREATED: 201,
+        ACCEPTED: 202,
+        NON_AUTHORITATIVE_INFORMATION: 203,
+        NO_CONTENT: 204,
+        RESET_CONTENT: 205,
+        PARTIAL_CONTENT: 206,
+        MULTI_STATUS: 207,
+        ALREADY_REPORTED: 208,
+        IM_USED: 226,
+    },
+    _3XX: {
+        MULTIPLE_CHOICES: 300,
+        MOVED_PERMANENTLY: 301,
+        FOUND: 302,
+        SEE_OTHER: 303,
+        NOT_MODIFIED: 304,
+        USE_PROXY: 305,
+        TEMPORARY_REDIRECT: 307,
+        PERMANENT_REDIRECT: 308,
+    },
+    _4XX: {
+        BAD_REQUEST: createGeneralError(400),
+        UNAUTHORIZED: createGeneralError(401),
+        PAYMENT_REQUIRED: createGeneralError(402),
+        FORBIDDEN: createGeneralError(403),
+        NOT_FOUND: createGeneralError(404),
+        METHOD_NOT_ALLOWED: createGeneralError(405),
+        NOT_ACCEPTABLE: createGeneralError(406),
+        PROXY_AUTHENTICATION_REQUIRED: createGeneralError(407),
+        REQUEST_TIMEOUT: createGeneralError(408),
+        CONFLICT: createGeneralError(409),
+        GONE: createGeneralError(410),
+        LENGTH_REQUIRED: createGeneralError(411),
+        PRECONDITION_FAILED: createGeneralError(412),
+        PAYLOAD_TOO_LARGE: createGeneralError(413),
+        URI_TOO_LONG: createGeneralError(414),
+        UNSUPPORTED_MEDIA_TYPE: createGeneralError(415),
+        RANGE_NOT_SATISFIABLE: createGeneralError(416),
+        EXPECTATION_FAILED: createGeneralError(417),
+        IM_A_TEAPOT: createGeneralError(418),
+        FAILED_VALIDATION: createGeneralError(420),
+        MISDIRECTED_REQUEST: createGeneralError(421),
+        UNPROCESSABLE_ENTITY: createGeneralError(422),
+        LOCKED: createGeneralError(423),
+        FAILED_DEPENDENCY: createGeneralError(424),
+        TOO_EARLY: createGeneralError(425),
+        UPGRADE_REQUIRED: createGeneralError(426),
+        PRECONDITION_REQUIRED: createGeneralError(428),
+        TOO_MANY_REQUESTS: createGeneralError(429),
+        REQUEST_HEADER_FIELDS_TOO_LARGE: createGeneralError(431),
+        UNAVAILABLE_FOR_LEGAL_REASONS: createGeneralError(451),
+        //custom
+        ENTITY_MISSING: createGeneralError(459),
+        ENTITY_ALREADY_EXISTS: createGeneralError(460),
+        ENTITY_IS_OUTDATED: createGeneralError(461),
+        INTERNAL_MISMATCH: createGeneralError(462),
+        ENTITY_DOESNT_EXISTS: createGeneralError(463),
+        OPERATION_FAILED: createGeneralError(490),
+    },
+    _5XX: {
+        INTERNAL_SERVER_ERROR: createGeneralError(500),
+        NOT_IMPLEMENTED: createGeneralError(501),
+        BAD_GATEWAY: createGeneralError(502),
+        SERVICE_UNAVAILABLE: createGeneralError(503),
+        GATEWAY_TIMEOUT: createGeneralError(504),
+        HTTP_VERSION_NOT_SUPPORTED: createGeneralError(505),
+        VARIANT_ALSO_NEGOTIATES: createGeneralError(506),
+        INSUFFICIENT_STORAGE: createGeneralError(507),
+        LOOP_DETECTED: createGeneralError(508),
+        NOT_EXTENDED: createGeneralError(510),
+        NETWORK_AUTHENTICATION_REQUIRED: createGeneralError(511),
+        //custom
+        DEBUG_WHO_CALLED_THIS: 555,
+        BAD_IMPLEMENTATION: 560,
+        IMPLEMENTATION_MISSING: 561,
+        SHOULD_NOT_HAPPENED: 598,
+        MUST_NEVER_HAPPENED: 599,
+    },
+};

package/utils/utils.d.ts

@@ -0,0 +1,42 @@
+import { StringMap } from '@nu-art/ts-common';
+import { RouteParams } from '../types/types.js';
+/**
+ * Composes a query string from parameters.
+ *
+ * Converts an object of parameters into a URL-encoded query string.
+ * - Functions are evaluated to get their return value
+ * - undefined/null values result in `key=` (empty value)
+ * - All values are URI-encoded
+ *
+ * @param params - Object with parameter keys and values
+ * @returns URL-encoded query string (e.g., "key1=value1&key2=value2")
+ */
+export declare function composeQueryParams(params?: RouteParams): string;
+/**
+ * Composes a complete URL with query parameters and optional hash.
+ *
+ * Combines a base URL with query parameters and/or a hash fragment.
+ * Only adds query string if there are parameters. Hash is added if provided.
+ *
+ * @param url - Base URL
+ * @param params - Query parameters object
+ * @param hash - Optional hash fragment (will add '#' if not present)
+ * @returns Complete URL with query string and/or hash
+ *
+ * @example
+ * ```typescript
+ * composeUrl('/path', {foo: 'bar'}, 'section1')
+ * // Returns: '/path?foo=bar#section1'
+ * ```
+ */
+export declare function composeUrl(url: string, params?: RouteParams, hash?: string): string;
+/**
+ * Encodes URL parameters into a StringMap with URI-encoded values.
+ *
+ * Similar to composeQueryParams but returns an object instead of a query string.
+ * Useful when you need the encoded parameters as a map rather than a string.
+ *
+ * @param params - Route parameters object
+ * @returns Object with URI-encoded parameter values
+ */
+export declare function encodeUrlParams(params?: RouteParams): StringMap;