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

package/dist/esm/core/HttpRequestBuilder.js

@@ -0,0 +1,127 @@
+import { HTTP_RESPONSE_TYPES } from '../constants/httpResponseTypes.js';
+import { REQUEST_BUILDER_ERROR_CODES } from '../constants/requestBuilderErrorCodes.js';
+import { RequestBuilderError } from '../errors/RequestBuilderError.js';
+import { assertValidBody } from '../asserts/assertValidBody.js';
+import { assertNonBlankString } from '../asserts/assertNonBlankString.js';
+import { assertValidBaseUrl } from '../asserts/assertValidBaseUrl.js';
+import { assertValidHeader } from '../asserts/assertValidHeader.js';
+import { assertValidHeaders } from '../asserts/assertValidHeaders.js';
+import { assertValidParams } from '../asserts/assertValidParams.js';
+import { assertValidTimeout } from '../asserts/assertValidTimeout.js';
+import { assertValidWithCredentials } from '../asserts/assertValidWithCredentials.js';
+import { assertValidValidateStatus } from '../asserts/assertValidValidateStatus.js';
+import { assertValidMethod } from '../asserts/assertValidMethod.js';
+import { assertValidParam } from '../asserts/assertValidParam.js';
+import { assertValidRequestConfig } from '../asserts/assertValidRequestConfig.js';
+import { assertValidSignal } from '../asserts/assertValidSignal.js';
+import { assertValidUrl } from '../asserts/assertValidUrl.js';
+import { HEADER_VALUE_LINE_BREAK_PATTERN } from '../asserts/headerValueLineBreakPattern.js';
+import { mergeHeaders } from '../utilities/mergeHeaders.js';
+import { mergeParams } from '../utilities/mergeParams.js';
+
+function cloneConfig(config) {
+    return {
+        ...config,
+        ...(config.headers === undefined ? {} : { headers: { ...config.headers } }),
+        ...(config.params === undefined ? {} : { params: mergeParams(config.params) })
+    };
+}
+/**
+ * Builds request configs immutably. Every configuration method returns a new builder instance.
+ */
+class HttpRequestBuilder {
+    executor;
+    config;
+    constructor(executor, method, url) {
+        if (typeof executor !== 'function') {
+            throw new RequestBuilderError('Executor must be a function', REQUEST_BUILDER_ERROR_CODES.INVALID_EXECUTOR);
+        }
+        assertValidMethod(method);
+        assertValidUrl(url);
+        this.executor = executor;
+        this.config = { method, url };
+    }
+    withConfig(partial) {
+        const builder = new HttpRequestBuilder(this.executor, this.config.method, this.config.url);
+        builder.config = cloneConfig({ ...this.config, ...partial });
+        return builder;
+    }
+    build() {
+        assertValidRequestConfig(this.config);
+        return cloneConfig(this.config);
+    }
+    baseUrl(value) {
+        assertValidBaseUrl(value);
+        return this.withConfig({ baseUrl: value });
+    }
+    header(key, value) {
+        assertValidHeader(key, value);
+        return this.withConfig({ headers: mergeHeaders(this.config.headers, { [key]: value }) });
+    }
+    headers(headers) {
+        assertValidHeaders(headers);
+        return this.withConfig({ headers: mergeHeaders(this.config.headers, headers) });
+    }
+    param(key, value) {
+        assertValidParam(key, value);
+        return this.withConfig({
+            params: mergeParams(this.config.params, { [key]: value })
+        });
+    }
+    params(params) {
+        assertValidParams(params);
+        return this.withConfig({
+            params: mergeParams(this.config.params, params)
+        });
+    }
+    body(data) {
+        assertValidBody(this.config.method, data);
+        return this.withConfig({ data });
+    }
+    signal(signal) {
+        assertValidSignal(signal);
+        return this.withConfig({ signal });
+    }
+    /** A zero timeout disables the request timeout, including a timeout inherited from the client config. */
+    timeout(timeout) {
+        assertValidTimeout(timeout);
+        return this.withConfig({ timeout });
+    }
+    /** Determines whether a response status should be treated as successful. */
+    validateStatus(validateStatus) {
+        assertValidValidateStatus(validateStatus);
+        return this.withConfig({ validateStatus });
+    }
+    /** Includes credentials in cross-origin requests. */
+    withCredentials(withCredentials) {
+        assertValidWithCredentials(withCredentials);
+        return this.withConfig({ withCredentials });
+    }
+    bearer(token) {
+        assertNonBlankString(token, 'Bearer token must be a non-empty string', REQUEST_BUILDER_ERROR_CODES.INVALID_BEARER_TOKEN);
+        if (HEADER_VALUE_LINE_BREAK_PATTERN.test(token)) {
+            throw new RequestBuilderError('Bearer token must not contain line breaks', REQUEST_BUILDER_ERROR_CODES.INVALID_BEARER_TOKEN);
+        }
+        return this.header('Authorization', `Bearer ${token}`);
+    }
+    asJson() {
+        return this.withConfig({ responseType: HTTP_RESPONSE_TYPES.JSON });
+    }
+    asText() {
+        return this.withConfig({ responseType: HTTP_RESPONSE_TYPES.TEXT });
+    }
+    asBlob() {
+        return this.withConfig({ responseType: HTTP_RESPONSE_TYPES.BLOB });
+    }
+    asArrayBuffer() {
+        return this.withConfig({ responseType: HTTP_RESPONSE_TYPES.ARRAY_BUFFER });
+    }
+    asStream() {
+        return this.withConfig({ responseType: HTTP_RESPONSE_TYPES.STREAM });
+    }
+    execute() {
+        return this.executor(this.build());
+    }
+}
+
+export { HttpRequestBuilder };

package/dist/esm/errors/AbortError.js

@@ -0,0 +1,9 @@
+import { HttpClientError } from './HttpClientError.js';
+
+class AbortError extends HttpClientError {
+}
+function isAbortError(error) {
+    return error instanceof AbortError;
+}
+
+export { AbortError, isAbortError };

package/dist/esm/errors/HttpClientError.js

@@ -0,0 +1,15 @@
+/** Base class for all HTTP client errors. Supports catching any client error with a single instanceof check. */
+class HttpClientError extends Error {
+    config;
+    constructor(message, options) {
+        super(message, options);
+        this.name = this.constructor.name;
+        this.config = options?.config;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+function isHttpClientError(error) {
+    return error instanceof HttpClientError;
+}
+
+export { HttpClientError, isHttpClientError };

package/dist/esm/errors/HttpResponseError.js

@@ -0,0 +1,23 @@
+import { HttpClientError } from './HttpClientError.js';
+
+/** Indicates that the server completed the request with a non-2xx status. */
+class HttpResponseError extends HttpClientError {
+    status;
+    statusText;
+    headers;
+    config;
+    data;
+    constructor(message, status, statusText, headers, config, data, options) {
+        super(message, { ...options, config });
+        this.status = status;
+        this.statusText = statusText;
+        this.headers = headers;
+        this.config = config;
+        this.data = data;
+    }
+}
+function isHttpResponseError(error) {
+    return error instanceof HttpResponseError;
+}
+
+export { HttpResponseError, isHttpResponseError };

package/dist/esm/errors/NetworkError.js

@@ -0,0 +1,9 @@
+import { HttpClientError } from './HttpClientError.js';
+
+class NetworkError extends HttpClientError {
+}
+function isNetworkError(error) {
+    return error instanceof NetworkError;
+}
+
+export { NetworkError, isNetworkError };

package/dist/esm/errors/ParseError.js

@@ -0,0 +1,17 @@
+import { HttpClientError } from './HttpClientError.js';
+
+/** Indicates that a successful response could not be parsed in the requested format. */
+class ParseError extends HttpClientError {
+    responseType;
+    raw;
+    constructor(message, options) {
+        super(message, options);
+        this.responseType = options?.responseType;
+        this.raw = options?.raw;
+    }
+}
+function isParseError(error) {
+    return error instanceof ParseError;
+}
+
+export { ParseError, isParseError };

package/dist/esm/errors/RequestBuilderError.js

@@ -0,0 +1,15 @@
+import { REQUEST_BUILDER_ERROR_CODES } from '../constants/requestBuilderErrorCodes.js';
+import { HttpClientError } from './HttpClientError.js';
+
+class RequestBuilderError extends HttpClientError {
+    code;
+    constructor(message, code = REQUEST_BUILDER_ERROR_CODES.INVALID_CONFIG) {
+        super(message);
+        this.code = code;
+    }
+}
+function isRequestBuilderError(error) {
+    return error instanceof RequestBuilderError;
+}
+
+export { RequestBuilderError, isRequestBuilderError };

package/dist/esm/errors/RequestPreparationError.js

@@ -0,0 +1,10 @@
+import { HttpClientError } from './HttpClientError.js';
+
+/** Indicates that an adapter could not prepare a request before sending it. */
+class RequestPreparationError extends HttpClientError {
+}
+function isRequestPreparationError(error) {
+    return error instanceof RequestPreparationError;
+}
+
+export { RequestPreparationError, isRequestPreparationError };

package/dist/esm/errors/TimeoutError.js

@@ -0,0 +1,15 @@
+import { HttpClientError } from './HttpClientError.js';
+
+/** Indicates that the request exceeded the configured timeout. */
+class TimeoutError extends HttpClientError {
+    timeout;
+    constructor(message, options) {
+        super(message, options);
+        this.timeout = options?.timeout;
+    }
+}
+function isTimeoutError(error) {
+    return error instanceof TimeoutError;
+}
+
+export { TimeoutError, isTimeoutError };

package/dist/esm/index.js

@@ -0,0 +1,16 @@
+export { HttpClient } from './core/HttpClient.js';
+export { HttpRequestBuilder } from './core/HttpRequestBuilder.js';
+export { FetchAdapter } from './adapters/FetchAdapter.js';
+export { XhrAdapter } from './adapters/XhrAdapter.js';
+export { HTTP_METHODS } from './constants/httpMethods.js';
+export { HTTP_STATUS_CODES } from './constants/httpStatusCodes.js';
+export { HTTP_RESPONSE_TYPES } from './constants/httpResponseTypes.js';
+export { REQUEST_BUILDER_ERROR_CODES } from './constants/requestBuilderErrorCodes.js';
+export { AbortError, isAbortError } from './errors/AbortError.js';
+export { HttpClientError, isHttpClientError } from './errors/HttpClientError.js';
+export { HttpResponseError, isHttpResponseError } from './errors/HttpResponseError.js';
+export { NetworkError, isNetworkError } from './errors/NetworkError.js';
+export { ParseError, isParseError } from './errors/ParseError.js';
+export { RequestBuilderError, isRequestBuilderError } from './errors/RequestBuilderError.js';
+export { RequestPreparationError, isRequestPreparationError } from './errors/RequestPreparationError.js';
+export { TimeoutError, isTimeoutError } from './errors/TimeoutError.js';

package/dist/esm/utilities/buildUrl.js

@@ -0,0 +1,92 @@
+function splitUrl(value) {
+    const hashIndex = value.indexOf('#');
+    const beforeHash = hashIndex === -1 ? value : value.slice(0, hashIndex);
+    const hash = hashIndex === -1 ? '' : value.slice(hashIndex);
+    const queryIndex = beforeHash.indexOf('?');
+    return {
+        path: queryIndex === -1 ? beforeHash : beforeHash.slice(0, queryIndex),
+        query: queryIndex === -1 ? '' : beforeHash.slice(queryIndex + 1),
+        hash
+    };
+}
+function joinPaths(basePath, path) {
+    if (!path) {
+        return basePath;
+    }
+    if (!basePath) {
+        return path;
+    }
+    return `${basePath.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
+}
+function getAbsoluteUrl(value) {
+    try {
+        return new URL(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function serializeParams(params) {
+    if (params === undefined) {
+        return '';
+    }
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === null || value === undefined) {
+            continue;
+        }
+        const values = Array.isArray(value) ? value : [value];
+        for (const item of values) {
+            if (item === null || item === undefined) {
+                continue;
+            }
+            searchParams.append(key, String(item));
+        }
+    }
+    return searchParams.toString();
+}
+function appendParams(url, params) {
+    const query = serializeParams(params);
+    if (!query) {
+        return url;
+    }
+    const { path, query: existingQuery, hash } = splitUrl(url);
+    const combinedQuery = [existingQuery, query].filter(Boolean).join('&');
+    return `${path}?${combinedQuery}${hash}`;
+}
+function resolveRelativeUrl(baseUrl, url) {
+    const base = splitUrl(baseUrl);
+    const request = splitUrl(url);
+    const query = [base.query, request.query].filter(Boolean).join('&');
+    return `${joinPaths(base.path, request.path)}${query ? `?${query}` : ''}${request.hash}`;
+}
+function resolveAbsoluteUrl(base, url) {
+    const request = splitUrl(url);
+    base.pathname = joinPaths(base.pathname, request.path);
+    base.hash = request.hash;
+    if (request.query) {
+        const requestParams = new URLSearchParams(request.query);
+        requestParams.forEach((value, key) => {
+            base.searchParams.append(key, value);
+        });
+    }
+    return base.toString();
+}
+/**
+ * Resolves a request URL against an optional base URL, preserves existing query values and fragments,
+ * and appends serialized params before the fragment.
+ */
+function buildUrl(baseUrl, url, params) {
+    const absoluteUrl = getAbsoluteUrl(url);
+    if (absoluteUrl !== undefined) {
+        return appendParams(absoluteUrl.toString(), params);
+    }
+    if (baseUrl === undefined) {
+        return appendParams(url, params);
+    }
+    const absoluteBaseUrl = getAbsoluteUrl(baseUrl);
+    const fullUrl = absoluteBaseUrl === undefined ? resolveRelativeUrl(baseUrl, url) : resolveAbsoluteUrl(absoluteBaseUrl, url);
+    return appendParams(fullUrl, params);
+}
+
+export { buildUrl };

package/dist/esm/utilities/getErrorMessage.js

@@ -0,0 +1,6 @@
+/** Returns a non-empty Error message or the provided fallback for unknown error values. */
+function getErrorMessage(error, fallback) {
+    return error instanceof Error && error.message ? error.message : fallback;
+}
+
+export { getErrorMessage };

package/dist/esm/utilities/isStatusAccepted.js

@@ -0,0 +1,6 @@
+/** Applies a custom status predicate or accepts the standard successful HTTP status range. */
+function isStatusAccepted(status, validateStatus) {
+    return validateStatus === undefined ? status >= 200 && status < 300 : validateStatus(status);
+}
+
+export { isStatusAccepted };

package/dist/esm/utilities/mergeHeaders.js

@@ -0,0 +1,27 @@
+/** Merges header maps from left to right using case-insensitive names while preserving the latest name casing. */
+function mergeHeaders(...sources) {
+    const result = {};
+    const normalizedKeys = new Map();
+    for (const source of sources) {
+        if (source === undefined) {
+            continue;
+        }
+        for (const [key, value] of Object.entries(source)) {
+            const normalizedKey = key.toLowerCase();
+            const previousKey = normalizedKeys.get(normalizedKey);
+            if (previousKey !== undefined) {
+                delete result[previousKey];
+            }
+            result[key] = value;
+            normalizedKeys.set(normalizedKey, key);
+        }
+    }
+    return result;
+}
+/** Checks whether a header map contains a name using case-insensitive comparison. */
+function hasHeader(headers, name) {
+    const normalizedName = name.toLowerCase();
+    return Object.keys(headers).some(key => key.toLowerCase() === normalizedName);
+}
+
+export { hasHeader, mergeHeaders };

package/dist/esm/utilities/mergeParams.js

@@ -0,0 +1,35 @@
+function isPresentParamPrimitive(value) {
+    return value !== null && value !== undefined;
+}
+/**
+ * Merges query params from left to right. `null` / `undefined` remove a key; nullish array items are dropped.
+ * Returns undefined when no params remain.
+ */
+function mergeParams(...sources) {
+    const result = {};
+    for (const source of sources) {
+        if (source === undefined) {
+            continue;
+        }
+        for (const [key, value] of Object.entries(source)) {
+            if (value === null || value === undefined) {
+                delete result[key];
+                continue;
+            }
+            if (Array.isArray(value)) {
+                const items = value.filter(isPresentParamPrimitive);
+                if (items.length === 0) {
+                    delete result[key];
+                }
+                else {
+                    result[key] = [...items];
+                }
+                continue;
+            }
+            result[key] = value;
+        }
+    }
+    return Object.keys(result).length === 0 ? undefined : result;
+}
+
+export { mergeParams };

package/dist/esm/utilities/prepareRequestBody.js

@@ -0,0 +1,41 @@
+import { hasHeader } from './mergeHeaders.js';
+
+function hasTag(value, tag) {
+    return Object.prototype.toString.call(value) === tag;
+}
+function isRequestBody(value) {
+    return (typeof value === 'string' ||
+        ArrayBuffer.isView(value) ||
+        hasTag(value, '[object ArrayBuffer]') ||
+        hasTag(value, '[object Blob]') ||
+        hasTag(value, '[object FormData]') ||
+        hasTag(value, '[object URLSearchParams]'));
+}
+function isUrlSearchParams(value) {
+    return hasTag(value, '[object URLSearchParams]');
+}
+/**
+ * Converts request data into a transport-compatible body.
+ * Mutates the provided headers by adding a default Content-Type for JSON and URLSearchParams bodies when absent.
+ * FormData is returned without setting Content-Type so the transport can add its boundary.
+ *
+ * @throws TypeError when data cannot be serialized as JSON.
+ */
+function prepareRequestBody(data, headers) {
+    if (isRequestBody(data)) {
+        if (isUrlSearchParams(data) && !hasHeader(headers, 'Content-Type')) {
+            headers['Content-Type'] = 'application/x-www-form-urlencoded;charset=UTF-8';
+        }
+        return isUrlSearchParams(data) ? data.toString() : data;
+    }
+    if (!hasHeader(headers, 'Content-Type')) {
+        headers['Content-Type'] = 'application/json';
+    }
+    const body = JSON.stringify(data);
+    if (typeof body !== 'string') {
+        throw new TypeError('Request body cannot be serialized as JSON');
+    }
+    return body;
+}
+
+export { prepareRequestBody };