@byndyusoft-ui/http-client 0.1.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,354 @@
+declare const HTTP_METHODS: {
+    readonly GET: "GET";
+    readonly HEAD: "HEAD";
+    readonly POST: "POST";
+    readonly PUT: "PUT";
+    readonly DELETE: "DELETE";
+    readonly OPTIONS: "OPTIONS";
+    readonly PATCH: "PATCH";
+};
+
+declare const HTTP_STATUS_CODES: {
+    readonly CONTINUE: 100;
+    readonly SWITCHING_PROTOCOLS: 101;
+    readonly PROCESSING: 102;
+    readonly EARLY_HINTS: 103;
+    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 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 BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly PAYMENT_REQUIRED: 402;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly METHOD_NOT_ALLOWED: 405;
+    readonly NOT_ACCEPTABLE: 406;
+    readonly PROXY_AUTHENTICATION_REQUIRED: 407;
+    readonly REQUEST_TIMEOUT: 408;
+    readonly CONFLICT: 409;
+    readonly GONE: 410;
+    readonly LENGTH_REQUIRED: 411;
+    readonly PRECONDITION_FAILED: 412;
+    readonly PAYLOAD_TOO_LARGE: 413;
+    readonly URI_TOO_LONG: 414;
+    readonly UNSUPPORTED_MEDIA_TYPE: 415;
+    readonly RANGE_NOT_SATISFIABLE: 416;
+    readonly EXPECTATION_FAILED: 417;
+    readonly IM_A_TEAPOT: 418;
+    readonly MISDIRECTED_REQUEST: 421;
+    readonly UNPROCESSABLE_ENTITY: 422;
+    readonly LOCKED: 423;
+    readonly FAILED_DEPENDENCY: 424;
+    readonly TOO_EARLY: 425;
+    readonly UPGRADE_REQUIRED: 426;
+    readonly PRECONDITION_REQUIRED: 428;
+    readonly TOO_MANY_REQUESTS: 429;
+    readonly REQUEST_HEADER_FIELDS_TOO_LARGE: 431;
+    readonly UNAVAILABLE_FOR_LEGAL_REASONS: 451;
+    readonly INTERNAL_SERVER_ERROR: 500;
+    readonly NOT_IMPLEMENTED: 501;
+    readonly BAD_GATEWAY: 502;
+    readonly SERVICE_UNAVAILABLE: 503;
+    readonly GATEWAY_TIMEOUT: 504;
+    readonly HTTP_VERSION_NOT_SUPPORTED: 505;
+    readonly VARIANT_ALSO_NEGOTIATES: 506;
+    readonly INSUFFICIENT_STORAGE: 507;
+    readonly LOOP_DETECTED: 508;
+    readonly NOT_EXTENDED: 510;
+    readonly NETWORK_AUTHENTICATION_REQUIRED: 511;
+};
+
+declare const HTTP_RESPONSE_TYPES: {
+    readonly ARRAY_BUFFER: "arrayBuffer";
+    readonly BLOB: "blob";
+    readonly JSON: "json";
+    readonly STREAM: "stream";
+    readonly TEXT: "text";
+};
+
+declare const REQUEST_BUILDER_ERROR_CODES: {
+    readonly INVALID_BASE_URL: "INVALID_BASE_URL";
+    readonly INVALID_BEARER_TOKEN: "INVALID_BEARER_TOKEN";
+    readonly INVALID_ADAPTER: "INVALID_ADAPTER";
+    readonly INVALID_BODY: "INVALID_BODY";
+    readonly INVALID_CONFIG: "INVALID_CONFIG";
+    readonly INVALID_EXECUTOR: "INVALID_EXECUTOR";
+    readonly INVALID_FETCH_ADAPTER_OPTIONS: "INVALID_FETCH_ADAPTER_OPTIONS";
+    readonly INVALID_HEADER: "INVALID_HEADER";
+    readonly INVALID_HEADERS: "INVALID_HEADERS";
+    readonly INVALID_HOOK: "INVALID_HOOK";
+    readonly INVALID_METHOD: "INVALID_METHOD";
+    readonly INVALID_PARAM: "INVALID_PARAM";
+    readonly INVALID_PARAMS: "INVALID_PARAMS";
+    readonly INVALID_RESPONSE_TYPE: "INVALID_RESPONSE_TYPE";
+    readonly INVALID_SIGNAL: "INVALID_SIGNAL";
+    readonly INVALID_TIMEOUT: "INVALID_TIMEOUT";
+    readonly INVALID_URL: "INVALID_URL";
+    readonly INVALID_VALIDATE_STATUS: "INVALID_VALIDATE_STATUS";
+    readonly INVALID_WITH_CREDENTIALS: "INVALID_WITH_CREDENTIALS";
+    readonly INVALID_XHR_ADAPTER_OPTIONS: "INVALID_XHR_ADAPTER_OPTIONS";
+};
+
+type THttpMethod = (typeof HTTP_METHODS)[keyof typeof HTTP_METHODS];
+
+/** Any valid HTTP response status, including non-standard codes returned by proxies or servers. */
+type THttpStatusCode = number;
+
+type THttpHeaders = Record<string, string>;
+
+type THttpParamPrimitive = string | number | boolean;
+/** A single query value or a list. `null` / `undefined` omit the key (or list item) when the request is sent. */
+type THttpParamValue = THttpParamPrimitive | null | undefined | Array<THttpParamPrimitive | null | undefined>;
+type THttpParams = Record<string, THttpParamValue>;
+
+type THttpResponseType = (typeof HTTP_RESPONSE_TYPES)[keyof typeof HTTP_RESPONSE_TYPES];
+
+/** Determines whether an HTTP response status should be treated as successful. */
+type TValidateStatus = (status: number) => boolean;
+
+interface IHttpRequestConfig<TData = unknown> {
+    readonly url: string;
+    readonly method: THttpMethod;
+    readonly baseUrl?: string;
+    readonly headers?: THttpHeaders;
+    readonly params?: THttpParams;
+    readonly data?: TData;
+    readonly signal?: AbortSignal;
+    readonly timeout?: number;
+    readonly validateStatus?: TValidateStatus;
+    readonly withCredentials?: boolean;
+    readonly responseType?: THttpResponseType;
+}
+
+interface IHttpResponse<T = unknown> {
+    data?: T;
+    status: THttpStatusCode;
+    statusText: string;
+    headers: THttpHeaders;
+    config: IHttpRequestConfig;
+}
+
+interface IHttpClientAdapter {
+    request<T>(config: IHttpRequestConfig): Promise<IHttpResponse<T>>;
+}
+
+/**
+ * Called once per request after merging with the client's default configuration,
+ * immediately before the adapter is called.
+ * The returned config continues through the pipeline. A thrown error is passed to onRequestError.
+ */
+type THttpRequestHook = (config: IHttpRequestConfig) => IHttpRequestConfig | Promise<IHttpRequestConfig>;
+/** A config that continues the request, or nothing, in which case the original error is rethrown. */
+type THttpRequestErrorHookResult = IHttpRequestConfig | void;
+/** Called only when onRequest throws or rejects. */
+type THttpRequestErrorHook = (error: unknown) => THttpRequestErrorHookResult | Promise<THttpRequestErrorHookResult>;
+/**
+ * Called once per request when the adapter resolves successfully (2xx).
+ * The returned response is passed to the caller. A thrown error is passed to onResponseError.
+ */
+type THttpResponseHook = (response: IHttpResponse) => IHttpResponse | Promise<IHttpResponse>;
+/** A recovery response (onResponse is not called for it again), or nothing, in which case the original error is rethrown. */
+type THttpResponseErrorHookResult = IHttpResponse | void;
+/**
+ * Called when the adapter rejects or when onResponse throws.
+ */
+type THttpResponseErrorHook = (error: unknown) => THttpResponseErrorHookResult | Promise<THttpResponseErrorHookResult>;
+
+interface IHttpClientOptions {
+    /** Uses FetchAdapter when omitted. */
+    adapter?: IHttpClientAdapter;
+    baseUrl?: string;
+    headers?: THttpHeaders;
+    params?: THttpParams;
+    timeout?: number;
+    /** Determines whether a response status should be treated as successful. */
+    validateStatus?: TValidateStatus;
+    /** Sends cookies and HTTP credentials with cross-origin requests. */
+    withCredentials?: boolean;
+    onRequest?: THttpRequestHook;
+    onRequestError?: THttpRequestErrorHook;
+    onResponse?: THttpResponseHook;
+    onResponseError?: THttpResponseErrorHook;
+}
+
+/** Request modes that can be explicitly set for a programmatic Fetch request. */
+type TFetchAdapterMode = Exclude<RequestMode, 'navigate'>;
+/** Settings that are supported only by the Fetch transport. */
+interface IFetchAdapterOptions {
+    cache?: RequestCache;
+    credentials?: RequestCredentials;
+    integrity?: string;
+    keepalive?: boolean;
+    mode?: TFetchAdapterMode;
+    redirect?: RequestRedirect;
+    referrer?: string;
+    referrerPolicy?: ReferrerPolicy;
+}
+
+type THttpRequestBody = string | Blob | ArrayBuffer | ArrayBufferView | FormData | URLSearchParams;
+
+type THttpRequestExecutor = <T>(config: IHttpRequestConfig) => Promise<IHttpResponse<T>>;
+
+type TRequestBuilderErrorCode = (typeof REQUEST_BUILDER_ERROR_CODES)[keyof typeof REQUEST_BUILDER_ERROR_CODES];
+
+/** Settings that are supported only by the XMLHttpRequest transport. */
+interface IXhrAdapterOptions {
+    mimeType?: string;
+    responseType?: THttpResponseType;
+    timeout?: number;
+    withCredentials?: boolean;
+    onDownloadProgress?: (event: ProgressEvent, config: Readonly<IHttpRequestConfig>) => void;
+    onUploadProgress?: (event: ProgressEvent, config: Readonly<IHttpRequestConfig>) => void;
+}
+
+/**
+ * Builds request configs immutably. Every configuration method returns a new builder instance.
+ */
+declare class HttpRequestBuilder<TResponse = unknown> {
+    private readonly executor;
+    private config;
+    constructor(executor: THttpRequestExecutor, method: THttpMethod, url: string);
+    private withConfig;
+    build(): Readonly<IHttpRequestConfig>;
+    baseUrl(value: string): HttpRequestBuilder<TResponse>;
+    header(key: string, value: string): HttpRequestBuilder<TResponse>;
+    headers(headers: THttpHeaders): HttpRequestBuilder<TResponse>;
+    param(key: string, value: THttpParamValue): HttpRequestBuilder<TResponse>;
+    params(params: THttpParams): HttpRequestBuilder<TResponse>;
+    body(data: unknown): HttpRequestBuilder<TResponse>;
+    signal(signal: AbortSignal): HttpRequestBuilder<TResponse>;
+    /** A zero timeout disables the request timeout, including a timeout inherited from the client config. */
+    timeout(timeout: number): HttpRequestBuilder<TResponse>;
+    /** Determines whether a response status should be treated as successful. */
+    validateStatus(validateStatus: NonNullable<IHttpRequestConfig['validateStatus']>): HttpRequestBuilder<TResponse>;
+    /** Includes credentials in cross-origin requests. */
+    withCredentials(withCredentials: boolean): HttpRequestBuilder<TResponse>;
+    bearer(token: string): HttpRequestBuilder<TResponse>;
+    asJson<T>(): HttpRequestBuilder<T>;
+    asText(): HttpRequestBuilder<string>;
+    asBlob(): HttpRequestBuilder<Blob>;
+    asArrayBuffer(): HttpRequestBuilder<ArrayBuffer>;
+    asStream(): HttpRequestBuilder<ReadableStream<Uint8Array>>;
+    execute(): Promise<IHttpResponse<TResponse>>;
+}
+
+declare class HttpClient {
+    private readonly adapter;
+    private readonly defaultConfig;
+    private onRequestHook?;
+    private onRequestErrorHook?;
+    private onResponseHook?;
+    private onResponseErrorHook?;
+    constructor(options: IHttpClientOptions);
+    /** Creates an independent client with the current defaults and hooks, using the provided adapter. */
+    withAdapter(adapter: IHttpClientAdapter): HttpClient;
+    /** Sets the onRequest hook, replacing the hook configured through constructor options. Returns this client for chaining. */
+    onRequest(hook: THttpRequestHook): this;
+    /** Sets the onRequestError hook, replacing the hook configured through constructor options. Returns this client for chaining. */
+    onRequestError(hook: THttpRequestErrorHook): this;
+    /** Sets the onResponse hook, replacing the hook configured through constructor options. Returns this client for chaining. */
+    onResponse(hook: THttpResponseHook): this;
+    /** Sets the onResponseError hook, replacing the hook configured through constructor options. Returns this client for chaining. */
+    onResponseError(hook: THttpResponseErrorHook): this;
+    private request;
+    get(url: string): HttpRequestBuilder;
+    head(url: string): HttpRequestBuilder;
+    post(url: string): HttpRequestBuilder;
+    put(url: string): HttpRequestBuilder;
+    delete(url: string): HttpRequestBuilder;
+    options(url: string): HttpRequestBuilder;
+    patch(url: string): HttpRequestBuilder;
+    private executeRequest;
+}
+
+declare class FetchAdapter implements IHttpClientAdapter {
+    private readonly options;
+    constructor(options?: IFetchAdapterOptions);
+    request<T>(config: IHttpRequestConfig): Promise<IHttpResponse<T>>;
+}
+
+declare class XhrAdapter implements IHttpClientAdapter {
+    private readonly options;
+    constructor(options?: IXhrAdapterOptions);
+    request<T>(config: IHttpRequestConfig): Promise<IHttpResponse<T>>;
+}
+
+interface IHttpClientErrorOptions extends ErrorOptions {
+    config?: IHttpRequestConfig;
+}
+/** Base class for all HTTP client errors. Supports catching any client error with a single instanceof check. */
+declare class HttpClientError extends Error {
+    readonly config?: IHttpRequestConfig;
+    constructor(message: string, options?: IHttpClientErrorOptions);
+}
+declare function isHttpClientError(error: unknown): error is HttpClientError;
+
+declare class AbortError extends HttpClientError {
+}
+declare function isAbortError(error: unknown): error is AbortError;
+
+/** Indicates that the server completed the request with a non-2xx status. */
+declare class HttpResponseError<T = unknown> extends HttpClientError {
+    readonly status: THttpStatusCode;
+    readonly statusText: string;
+    readonly headers: THttpHeaders;
+    readonly config: IHttpRequestConfig;
+    readonly data: T | undefined;
+    constructor(message: string, status: THttpStatusCode, statusText: string, headers: THttpHeaders, config: IHttpRequestConfig, data?: T, options?: ErrorOptions);
+}
+declare function isHttpResponseError(error: unknown): error is HttpResponseError;
+
+declare class NetworkError extends HttpClientError {
+}
+declare function isNetworkError(error: unknown): error is NetworkError;
+
+interface IParseErrorOptions extends IHttpClientErrorOptions {
+    responseType?: THttpResponseType;
+    raw?: string;
+}
+/** Indicates that a successful response could not be parsed in the requested format. */
+declare class ParseError extends HttpClientError {
+    readonly responseType?: THttpResponseType;
+    readonly raw?: string;
+    constructor(message: string, options?: IParseErrorOptions);
+}
+declare function isParseError(error: unknown): error is ParseError;
+
+declare class RequestBuilderError extends HttpClientError {
+    readonly code: TRequestBuilderErrorCode;
+    constructor(message: string, code?: TRequestBuilderErrorCode);
+}
+declare function isRequestBuilderError(error: unknown): error is RequestBuilderError;
+
+/** Indicates that an adapter could not prepare a request before sending it. */
+declare class RequestPreparationError extends HttpClientError {
+}
+declare function isRequestPreparationError(error: unknown): error is RequestPreparationError;
+
+interface ITimeoutErrorOptions extends IHttpClientErrorOptions {
+    timeout?: number;
+}
+/** Indicates that the request exceeded the configured timeout. */
+declare class TimeoutError extends HttpClientError {
+    readonly timeout?: number;
+    constructor(message: string, options?: ITimeoutErrorOptions);
+}
+declare function isTimeoutError(error: unknown): error is TimeoutError;
+
+export { AbortError, FetchAdapter, HTTP_METHODS, HTTP_RESPONSE_TYPES, HTTP_STATUS_CODES, HttpClient, HttpClientError, HttpRequestBuilder, HttpResponseError, NetworkError, ParseError, REQUEST_BUILDER_ERROR_CODES, RequestBuilderError, RequestPreparationError, TimeoutError, XhrAdapter, isAbortError, isHttpClientError, isHttpResponseError, isNetworkError, isParseError, isRequestBuilderError, isRequestPreparationError, isTimeoutError };
+export type { IFetchAdapterOptions, IHttpClientAdapter, IHttpClientErrorOptions, IHttpClientOptions, IHttpRequestConfig, IHttpResponse, IParseErrorOptions, ITimeoutErrorOptions, IXhrAdapterOptions, TFetchAdapterMode, THttpHeaders, THttpMethod, THttpParamPrimitive, THttpParamValue, THttpParams, THttpRequestBody, THttpRequestErrorHook, THttpRequestErrorHookResult, THttpRequestExecutor, THttpRequestHook, THttpResponseErrorHook, THttpResponseErrorHookResult, THttpResponseHook, THttpResponseType, THttpStatusCode, TRequestBuilderErrorCode, TValidateStatus };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@byndyusoft-ui/http-client",
+  "version": "0.1.0-alpha.0",
+  "description": "Byndyusoft UI HTTP Client Service",
+  "keywords": [
+    "byndyusoft",
+    "byndyusoft-ui",
+    "http-client"
+  ],
+  "author": "Byndyusoft Frontend Developer <frontend@byndyusoft.com>",
+  "homepage": "https://github.com/Byndyusoft/ui/tree/master/services/http-client#readme",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Byndyusoft/ui.git"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc --project tsconfig.build.json && rollup --config && rimraf dist/declarations && npm run test:package",
+    "clean": "rimraf dist && rimraf .turbo && rimraf node_modules && rimraf package-lock.json",
+    "lint": "eslint src --config ../../eslint.config.js",
+    "test": "vitest run --config vitest.config.mjs --typecheck",
+    "test:package": "node scripts/verify-package.mjs"
+  },
+  "bugs": {
+    "url": "https://github.com/Byndyusoft/ui/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "devDependencies": {
+    "msw": "^2.4.9"
+  }
+}