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

package/dist/cjs/utilities/prepareRequestBody.cjs

@@ -0,0 +1,43 @@
+'use strict';
+
+var mergeHeaders = require('./mergeHeaders.cjs');
+
+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) && !mergeHeaders.hasHeader(headers, 'Content-Type')) {
+            headers['Content-Type'] = 'application/x-www-form-urlencoded;charset=UTF-8';
+        }
+        return isUrlSearchParams(data) ? data.toString() : data;
+    }
+    if (!mergeHeaders.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;
+}
+
+exports.prepareRequestBody = prepareRequestBody;

package/dist/esm/adapters/FetchAdapter.js

@@ -0,0 +1,216 @@
+import { HTTP_METHODS } from '../constants/httpMethods.js';
+import { HTTP_RESPONSE_TYPES } from '../constants/httpResponseTypes.js';
+import { HttpClientError } from '../errors/HttpClientError.js';
+import { HttpResponseError } from '../errors/HttpResponseError.js';
+import { NetworkError } from '../errors/NetworkError.js';
+import { ParseError } from '../errors/ParseError.js';
+import { RequestPreparationError } from '../errors/RequestPreparationError.js';
+import { TimeoutError } from '../errors/TimeoutError.js';
+import { AbortError } from '../errors/AbortError.js';
+import { assertValidFetchAdapterOptions } from '../asserts/assertValidFetchAdapterOptions.js';
+import { buildUrl } from '../utilities/buildUrl.js';
+import { getErrorMessage } from '../utilities/getErrorMessage.js';
+import { mergeHeaders } from '../utilities/mergeHeaders.js';
+import { prepareRequestBody } from '../utilities/prepareRequestBody.js';
+import { isStatusAccepted } from '../utilities/isStatusAccepted.js';
+
+function extractResponseHeaders(headers) {
+    const result = {};
+    headers.forEach((value, key) => {
+        result[key] = value;
+    });
+    return result;
+}
+function prepareFetchRequest(config) {
+    const { url, method, headers = {}, params, data, signal: userSignal, timeout, baseUrl: baseURL } = config;
+    let timeoutId;
+    let removeAbortListener;
+    const cleanup = () => {
+        if (timeoutId !== undefined) {
+            clearTimeout(timeoutId);
+        }
+        removeAbortListener?.();
+    };
+    try {
+        const fullUrl = buildUrl(baseURL, url, params);
+        const requestHeaders = mergeHeaders(headers);
+        const body = data !== undefined && method !== HTTP_METHODS.GET && method !== HTTP_METHODS.HEAD
+            ? prepareRequestBody(data, requestHeaders)
+            : undefined;
+        if (timeout) {
+            const controller = new AbortController();
+            timeoutId = setTimeout(() => controller.abort(), timeout);
+            if (userSignal) {
+                if (userSignal.aborted) {
+                    throw new AbortError('Request was aborted', { cause: userSignal.reason, config });
+                }
+                const abort = () => controller.abort();
+                userSignal.addEventListener('abort', abort, { once: true });
+                removeAbortListener = () => userSignal.removeEventListener('abort', abort);
+            }
+            return {
+                fullUrl,
+                requestHeaders,
+                body,
+                signal: controller.signal,
+                userSignal,
+                timeout,
+                cleanup
+            };
+        }
+        return {
+            fullUrl,
+            requestHeaders,
+            body,
+            signal: userSignal,
+            userSignal,
+            timeout,
+            cleanup
+        };
+    }
+    catch (error) {
+        cleanup();
+        throw error;
+    }
+}
+function resolveCredentials(withCredentials, adapterCredentials) {
+    if (withCredentials === true) {
+        return 'include';
+    }
+    if (withCredentials === false) {
+        return 'same-origin';
+    }
+    return adapterCredentials ?? 'same-origin';
+}
+function createFetchError(error, request, config) {
+    if (error instanceof HttpClientError) {
+        return error;
+    }
+    if (request.userSignal?.aborted) {
+        return new AbortError('Request was aborted', { cause: request.userSignal.reason ?? error, config });
+    }
+    if (request.timeout && error instanceof DOMException && error.name === 'AbortError') {
+        return new TimeoutError(`Request timed out after ${request.timeout}ms`, {
+            cause: error,
+            config,
+            timeout: request.timeout
+        });
+    }
+    return new NetworkError(getErrorMessage(error, 'Network request failed'), { cause: error, config });
+}
+async function parseResponseBody(response, config, responseType) {
+    if (response.status === 204 || response.headers.get('content-length') === '0') {
+        return undefined;
+    }
+    switch (responseType) {
+        case HTTP_RESPONSE_TYPES.TEXT:
+            return response.text();
+        case HTTP_RESPONSE_TYPES.BLOB:
+            return response.blob();
+        case HTTP_RESPONSE_TYPES.ARRAY_BUFFER:
+            return response.arrayBuffer();
+        case HTTP_RESPONSE_TYPES.STREAM:
+            if (response.body === null) {
+                throw new ParseError('Streaming response body is not available', {
+                    config,
+                    responseType: HTTP_RESPONSE_TYPES.STREAM
+                });
+            }
+            return response.body;
+        case HTTP_RESPONSE_TYPES.JSON:
+        default: {
+            const resolvedResponseType = responseType ?? HTTP_RESPONSE_TYPES.JSON;
+            const text = await response.text();
+            if (!text) {
+                return undefined;
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch (error) {
+                throw new ParseError('Failed to parse response body as JSON', {
+                    cause: error,
+                    config,
+                    responseType: resolvedResponseType,
+                    raw: text
+                });
+            }
+        }
+    }
+}
+class FetchAdapter {
+    options;
+    constructor(options = {}) {
+        assertValidFetchAdapterOptions(options);
+        this.options = { ...options };
+    }
+    async request(config) {
+        let request;
+        try {
+            request = prepareFetchRequest(config);
+        }
+        catch (error) {
+            if (error instanceof HttpClientError) {
+                throw error;
+            }
+            throw new RequestPreparationError('Failed to prepare HTTP request', { cause: error, config });
+        }
+        let response;
+        try {
+            response = await fetch(request.fullUrl, {
+                ...this.options,
+                method: config.method,
+                headers: request.requestHeaders,
+                body: request.body,
+                credentials: resolveCredentials(config.withCredentials, this.options.credentials),
+                signal: request.signal
+            });
+        }
+        catch (error) {
+            request.cleanup();
+            throw createFetchError(error, request, config);
+        }
+        let statusAccepted;
+        try {
+            statusAccepted = isStatusAccepted(response.status, config.validateStatus);
+        }
+        catch (error) {
+            request.cleanup();
+            throw error;
+        }
+        try {
+            if (!statusAccepted) {
+                let errorData;
+                try {
+                    const text = await response.text();
+                    try {
+                        errorData = JSON.parse(text);
+                    }
+                    catch {
+                        errorData = text || undefined;
+                    }
+                }
+                catch {
+                    errorData = undefined;
+                }
+                throw new HttpResponseError(`Request failed with status code ${response.status}`, response.status, response.statusText, extractResponseHeaders(response.headers), config, errorData);
+            }
+            const responseData = await parseResponseBody(response, config, config.responseType);
+            return {
+                data: responseData,
+                status: response.status,
+                statusText: response.statusText,
+                headers: extractResponseHeaders(response.headers),
+                config
+            };
+        }
+        catch (error) {
+            throw createFetchError(error, request, config);
+        }
+        finally {
+            request.cleanup();
+        }
+    }
+}
+
+export { FetchAdapter };

package/dist/esm/adapters/XhrAdapter.js

@@ -0,0 +1,355 @@
+import { HTTP_METHODS } from '../constants/httpMethods.js';
+import { HTTP_RESPONSE_TYPES } from '../constants/httpResponseTypes.js';
+import { HttpClientError } from '../errors/HttpClientError.js';
+import { HttpResponseError } from '../errors/HttpResponseError.js';
+import { NetworkError } from '../errors/NetworkError.js';
+import { ParseError } from '../errors/ParseError.js';
+import { RequestPreparationError } from '../errors/RequestPreparationError.js';
+import { TimeoutError } from '../errors/TimeoutError.js';
+import { AbortError } from '../errors/AbortError.js';
+import { assertValidXhrAdapterOptions } from '../asserts/assertValidXhrAdapterOptions.js';
+import { buildUrl } from '../utilities/buildUrl.js';
+import { getErrorMessage } from '../utilities/getErrorMessage.js';
+import { mergeHeaders } from '../utilities/mergeHeaders.js';
+import { prepareRequestBody } from '../utilities/prepareRequestBody.js';
+import { isStatusAccepted } from '../utilities/isStatusAccepted.js';
+
+function parseResponseHeaders(rawHeaders) {
+    const result = {};
+    const lines = rawHeaders.trim().split('\r\n');
+    for (const line of lines) {
+        const index = line.indexOf(': ');
+        if (index > 0) {
+            const key = line.slice(0, index).toLowerCase();
+            const value = line.slice(index + 2);
+            result[key] = value;
+        }
+    }
+    return result;
+}
+function createResponseStream(xhr) {
+    let controller;
+    let textLength = 0;
+    const encoder = new TextEncoder();
+    const data = new ReadableStream({
+        start(value) {
+            controller = value;
+        }
+    });
+    return {
+        data,
+        append() {
+            const text = xhr.responseText;
+            const chunk = text.slice(textLength);
+            if (chunk) {
+                controller?.enqueue(encoder.encode(chunk));
+                textLength = text.length;
+            }
+        },
+        close() {
+            controller?.close();
+        },
+        error(reason) {
+            controller?.error(reason);
+        }
+    };
+}
+async function readBlobAsText(blob) {
+    if (typeof blob.text === 'function') {
+        return blob.text();
+    }
+    return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onload = () => {
+            if (typeof reader.result !== 'string') {
+                reject(new TypeError('Failed to read response Blob as text'));
+                return;
+            }
+            resolve(reader.result);
+        };
+        reader.onerror = () => {
+            reject(reader.error ?? new TypeError('Failed to read response Blob as text'));
+        };
+        reader.readAsText(blob);
+    });
+}
+function hasEmptyResponseBody(xhr) {
+    return xhr.status === 204 || xhr.getResponseHeader('content-length') === '0';
+}
+function getResponseBody(xhr, config, responseType) {
+    if (hasEmptyResponseBody(xhr)) {
+        return undefined;
+    }
+    switch (responseType) {
+        case HTTP_RESPONSE_TYPES.ARRAY_BUFFER:
+        case HTTP_RESPONSE_TYPES.BLOB:
+            return xhr.response;
+        case HTTP_RESPONSE_TYPES.TEXT:
+            return xhr.response;
+        case HTTP_RESPONSE_TYPES.JSON:
+        default: {
+            const resolvedResponseType = responseType ?? HTTP_RESPONSE_TYPES.JSON;
+            const text = xhr.response;
+            if (!text) {
+                return undefined;
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch (error) {
+                throw new ParseError('Failed to parse response body as JSON', {
+                    cause: error,
+                    config,
+                    responseType: resolvedResponseType,
+                    raw: text
+                });
+            }
+        }
+    }
+}
+function setResponseType(xhr, responseType) {
+    if (responseType === HTTP_RESPONSE_TYPES.ARRAY_BUFFER) {
+        // XHR accepts only a lowercase DOM value.
+        xhr.responseType = 'arraybuffer';
+    }
+    else if (responseType === HTTP_RESPONSE_TYPES.BLOB) {
+        xhr.responseType = 'blob';
+    }
+    else {
+        xhr.responseType = 'text';
+    }
+}
+function assertStreamingSupported(responseType, config) {
+    if (responseType === HTTP_RESPONSE_TYPES.STREAM &&
+        (typeof ReadableStream === 'undefined' || typeof TextEncoder === 'undefined')) {
+        throw new RequestPreparationError('Streaming responses are not supported in this environment', { config });
+    }
+}
+function createResponse(xhr, config, data) {
+    return {
+        data,
+        status: xhr.status,
+        statusText: xhr.statusText,
+        headers: parseResponseHeaders(xhr.getAllResponseHeaders()),
+        config
+    };
+}
+async function getErrorResponseText(xhr) {
+    if (xhr.responseType === 'blob') {
+        const blob = xhr.response;
+        if (!(blob instanceof Blob)) {
+            return undefined;
+        }
+        return readBlobAsText(blob);
+    }
+    if (xhr.responseType === 'arraybuffer') {
+        const arrayBuffer = xhr.response;
+        if (typeof TextDecoder === 'undefined' || !(arrayBuffer instanceof ArrayBuffer)) {
+            return undefined;
+        }
+        return new TextDecoder().decode(arrayBuffer);
+    }
+    return xhr.responseText;
+}
+async function getErrorData(xhr) {
+    try {
+        const text = await getErrorResponseText(xhr);
+        if (!text) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+async function createResponseError(xhr, config) {
+    return new HttpResponseError(`Request failed with status code ${xhr.status}`, xhr.status, xhr.statusText, parseResponseHeaders(xhr.getAllResponseHeaders()), config, await getErrorData(xhr));
+}
+function resolveRequestConfig(config, options) {
+    return {
+        ...config,
+        ...(config.responseType === undefined && options.responseType !== undefined
+            ? { responseType: options.responseType }
+            : {}),
+        ...(config.timeout === undefined && options.timeout !== undefined ? { timeout: options.timeout } : {}),
+        ...(config.withCredentials === undefined && options.withCredentials !== undefined
+            ? { withCredentials: options.withCredentials }
+            : {})
+    };
+}
+function prepareXhrRequest(config, options) {
+    const { url, method, headers = {}, params, data, signal: userSignal, timeout, responseType, baseUrl: baseURL } = config;
+    const fullUrl = buildUrl(baseURL, url, params);
+    if (userSignal?.aborted) {
+        throw new AbortError('Request was aborted', { cause: userSignal.reason, config });
+    }
+    assertStreamingSupported(responseType, config);
+    const xhr = new XMLHttpRequest();
+    xhr.open(method, fullUrl, true);
+    xhr.withCredentials = config.withCredentials === true;
+    if (options.mimeType !== undefined) {
+        xhr.overrideMimeType(options.mimeType);
+    }
+    if (timeout !== undefined && timeout > 0) {
+        xhr.timeout = timeout;
+    }
+    setResponseType(xhr, responseType);
+    const requestHeaders = mergeHeaders(headers);
+    const body = data !== undefined && method !== HTTP_METHODS.GET && method !== HTTP_METHODS.HEAD
+        ? prepareRequestBody(data, requestHeaders)
+        : undefined;
+    for (const [key, value] of Object.entries(requestHeaders)) {
+        xhr.setRequestHeader(key, value);
+    }
+    const onAbort = () => xhr.abort();
+    userSignal?.addEventListener('abort', onAbort, { once: true });
+    return {
+        xhr,
+        body,
+        cleanup() {
+            userSignal?.removeEventListener('abort', onAbort);
+        }
+    };
+}
+function configureXhrEventHandlers(request, config, options, resolve, reject) {
+    const { xhr } = request;
+    const { signal: userSignal, timeout, responseType } = config;
+    const { onDownloadProgress, onUploadProgress } = options;
+    let responseStream;
+    let streamResponseResolved = false;
+    let statusValidation;
+    const isSuccessful = () => {
+        if (statusValidation === undefined) {
+            try {
+                statusValidation = { accepted: isStatusAccepted(xhr.status, config.validateStatus) };
+            }
+            catch (error) {
+                statusValidation = { error };
+            }
+        }
+        if ('error' in statusValidation) {
+            throw statusValidation.error;
+        }
+        return statusValidation.accepted;
+    };
+    const resolveStream = () => {
+        if (streamResponseResolved || !isSuccessful()) {
+            return;
+        }
+        responseStream = createResponseStream(xhr);
+        streamResponseResolved = true;
+        resolve(createResponse(xhr, config, responseStream.data));
+    };
+    const rejectOrFailStream = (error) => {
+        request.cleanup();
+        if (streamResponseResolved) {
+            responseStream?.error(error);
+            return;
+        }
+        reject(error);
+    };
+    if (responseType === HTTP_RESPONSE_TYPES.STREAM) {
+        xhr.onreadystatechange = () => {
+            if (xhr.readyState === XMLHttpRequest.HEADERS_RECEIVED) {
+                try {
+                    resolveStream();
+                }
+                catch (error) {
+                    request.cleanup();
+                    reject(error);
+                    xhr.abort();
+                }
+            }
+        };
+    }
+    if (responseType === HTTP_RESPONSE_TYPES.STREAM || onDownloadProgress !== undefined) {
+        xhr.onprogress = event => {
+            responseStream?.append();
+            onDownloadProgress?.(event, config);
+        };
+    }
+    if (request.body !== undefined && onUploadProgress !== undefined) {
+        xhr.upload.onprogress = event => {
+            onUploadProgress(event, config);
+        };
+    }
+    xhr.onload = async () => {
+        request.cleanup();
+        let successful;
+        try {
+            successful = isSuccessful();
+        }
+        catch (error) {
+            reject(error);
+            return;
+        }
+        if (!successful) {
+            reject(await createResponseError(xhr, config));
+            return;
+        }
+        if (responseType === HTTP_RESPONSE_TYPES.STREAM) {
+            resolveStream();
+            responseStream?.append();
+            responseStream?.close();
+            return;
+        }
+        try {
+            const responseData = getResponseBody(xhr, config, responseType);
+            resolve(createResponse(xhr, config, responseData));
+        }
+        catch (error) {
+            reject(error instanceof HttpClientError
+                ? error
+                : new NetworkError(getErrorMessage(error, 'Network request failed'), { cause: error, config }));
+        }
+    };
+    xhr.onerror = event => {
+        rejectOrFailStream(new NetworkError('Network request failed', { cause: event, config }));
+    };
+    xhr.onabort = event => {
+        rejectOrFailStream(new AbortError('Request was aborted', { cause: userSignal?.reason ?? event, config }));
+    };
+    xhr.ontimeout = event => {
+        const timeoutMs = timeout ?? 0;
+        rejectOrFailStream(new TimeoutError(`Request timed out after ${timeoutMs}ms`, {
+            cause: event,
+            config,
+            timeout: timeoutMs
+        }));
+    };
+}
+class XhrAdapter {
+    options;
+    constructor(options = {}) {
+        assertValidXhrAdapterOptions(options);
+        this.options = { ...options };
+    }
+    request(config) {
+        const resolvedConfig = resolveRequestConfig(config, this.options);
+        return new Promise((resolve, reject) => {
+            let request;
+            try {
+                request = prepareXhrRequest(resolvedConfig, this.options);
+                configureXhrEventHandlers(request, resolvedConfig, this.options, resolve, reject);
+                request.xhr.send(request.body);
+            }
+            catch (error) {
+                request?.cleanup();
+                reject(error instanceof HttpClientError
+                    ? error
+                    : new RequestPreparationError('Failed to prepare HTTP request', {
+                        cause: error,
+                        config: resolvedConfig
+                    }));
+            }
+        });
+    }
+}
+
+export { XhrAdapter };

package/dist/esm/asserts/assertNonBlankString.js

@@ -0,0 +1,9 @@
+import { RequestBuilderError } from '../errors/RequestBuilderError.js';
+
+function assertNonBlankString(value, message, code) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new RequestBuilderError(message, code);
+    }
+}
+
+export { assertNonBlankString };

package/dist/esm/asserts/assertValidAdapter.js

@@ -0,0 +1,13 @@
+import { REQUEST_BUILDER_ERROR_CODES } from '../constants/requestBuilderErrorCodes.js';
+import { RequestBuilderError } from '../errors/RequestBuilderError.js';
+
+/** Validates an HTTP client adapter. */
+function assertValidAdapter(adapter) {
+    if (adapter === null ||
+        (typeof adapter !== 'object' && typeof adapter !== 'function') ||
+        typeof adapter.request !== 'function') {
+        throw new RequestBuilderError('Adapter must implement a request method', REQUEST_BUILDER_ERROR_CODES.INVALID_ADAPTER);
+    }
+}
+
+export { assertValidAdapter };

package/dist/esm/asserts/assertValidBaseUrl.js

@@ -0,0 +1,8 @@
+import { REQUEST_BUILDER_ERROR_CODES } from '../constants/requestBuilderErrorCodes.js';
+import { assertNonBlankString } from './assertNonBlankString.js';
+
+function assertValidBaseUrl(baseUrl) {
+    assertNonBlankString(baseUrl, 'Base URL must be a non-empty string', REQUEST_BUILDER_ERROR_CODES.INVALID_BASE_URL);
+}
+
+export { assertValidBaseUrl };

package/dist/esm/asserts/assertValidBody.js

@@ -0,0 +1,15 @@
+import { HTTP_METHODS } from '../constants/httpMethods.js';
+import { REQUEST_BUILDER_ERROR_CODES } from '../constants/requestBuilderErrorCodes.js';
+import { RequestBuilderError } from '../errors/RequestBuilderError.js';
+
+/** Validates that a request method supports a body and that the body is explicitly defined. */
+function assertValidBody(method, data) {
+    if (method === HTTP_METHODS.GET || method === HTTP_METHODS.HEAD) {
+        throw new RequestBuilderError('Body is not allowed for GET or HEAD requests', REQUEST_BUILDER_ERROR_CODES.INVALID_BODY);
+    }
+    if (data === undefined) {
+        throw new RequestBuilderError('Body must not be undefined', REQUEST_BUILDER_ERROR_CODES.INVALID_BODY);
+    }
+}
+
+export { assertValidBody };