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

package/dist/cjs/adapters/FetchAdapter.cjs

@@ -0,0 +1,218 @@
+'use strict';
+
+var httpMethods = require('../constants/httpMethods.cjs');
+var httpResponseTypes = require('../constants/httpResponseTypes.cjs');
+var HttpClientError = require('../errors/HttpClientError.cjs');
+var HttpResponseError = require('../errors/HttpResponseError.cjs');
+var NetworkError = require('../errors/NetworkError.cjs');
+var ParseError = require('../errors/ParseError.cjs');
+var RequestPreparationError = require('../errors/RequestPreparationError.cjs');
+var TimeoutError = require('../errors/TimeoutError.cjs');
+var AbortError = require('../errors/AbortError.cjs');
+var assertValidFetchAdapterOptions = require('../asserts/assertValidFetchAdapterOptions.cjs');
+var buildUrl = require('../utilities/buildUrl.cjs');
+var getErrorMessage = require('../utilities/getErrorMessage.cjs');
+var mergeHeaders = require('../utilities/mergeHeaders.cjs');
+var prepareRequestBody = require('../utilities/prepareRequestBody.cjs');
+var isStatusAccepted = require('../utilities/isStatusAccepted.cjs');
+
+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.buildUrl(baseURL, url, params);
+        const requestHeaders = mergeHeaders.mergeHeaders(headers);
+        const body = data !== undefined && method !== httpMethods.HTTP_METHODS.GET && method !== httpMethods.HTTP_METHODS.HEAD
+            ? prepareRequestBody.prepareRequestBody(data, requestHeaders)
+            : undefined;
+        if (timeout) {
+            const controller = new AbortController();
+            timeoutId = setTimeout(() => controller.abort(), timeout);
+            if (userSignal) {
+                if (userSignal.aborted) {
+                    throw new AbortError.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.HttpClientError) {
+        return error;
+    }
+    if (request.userSignal?.aborted) {
+        return new AbortError.AbortError('Request was aborted', { cause: request.userSignal.reason ?? error, config });
+    }
+    if (request.timeout && error instanceof DOMException && error.name === 'AbortError') {
+        return new TimeoutError.TimeoutError(`Request timed out after ${request.timeout}ms`, {
+            cause: error,
+            config,
+            timeout: request.timeout
+        });
+    }
+    return new NetworkError.NetworkError(getErrorMessage.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 httpResponseTypes.HTTP_RESPONSE_TYPES.TEXT:
+            return response.text();
+        case httpResponseTypes.HTTP_RESPONSE_TYPES.BLOB:
+            return response.blob();
+        case httpResponseTypes.HTTP_RESPONSE_TYPES.ARRAY_BUFFER:
+            return response.arrayBuffer();
+        case httpResponseTypes.HTTP_RESPONSE_TYPES.STREAM:
+            if (response.body === null) {
+                throw new ParseError.ParseError('Streaming response body is not available', {
+                    config,
+                    responseType: httpResponseTypes.HTTP_RESPONSE_TYPES.STREAM
+                });
+            }
+            return response.body;
+        case httpResponseTypes.HTTP_RESPONSE_TYPES.JSON:
+        default: {
+            const resolvedResponseType = responseType ?? httpResponseTypes.HTTP_RESPONSE_TYPES.JSON;
+            const text = await response.text();
+            if (!text) {
+                return undefined;
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch (error) {
+                throw new ParseError.ParseError('Failed to parse response body as JSON', {
+                    cause: error,
+                    config,
+                    responseType: resolvedResponseType,
+                    raw: text
+                });
+            }
+        }
+    }
+}
+class FetchAdapter {
+    options;
+    constructor(options = {}) {
+        assertValidFetchAdapterOptions.assertValidFetchAdapterOptions(options);
+        this.options = { ...options };
+    }
+    async request(config) {
+        let request;
+        try {
+            request = prepareFetchRequest(config);
+        }
+        catch (error) {
+            if (error instanceof HttpClientError.HttpClientError) {
+                throw error;
+            }
+            throw new RequestPreparationError.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.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.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();
+        }
+    }
+}
+
+exports.FetchAdapter = FetchAdapter;

package/dist/cjs/adapters/XhrAdapter.cjs

@@ -0,0 +1,357 @@
+'use strict';
+
+var httpMethods = require('../constants/httpMethods.cjs');
+var httpResponseTypes = require('../constants/httpResponseTypes.cjs');
+var HttpClientError = require('../errors/HttpClientError.cjs');
+var HttpResponseError = require('../errors/HttpResponseError.cjs');
+var NetworkError = require('../errors/NetworkError.cjs');
+var ParseError = require('../errors/ParseError.cjs');
+var RequestPreparationError = require('../errors/RequestPreparationError.cjs');
+var TimeoutError = require('../errors/TimeoutError.cjs');
+var AbortError = require('../errors/AbortError.cjs');
+var assertValidXhrAdapterOptions = require('../asserts/assertValidXhrAdapterOptions.cjs');
+var buildUrl = require('../utilities/buildUrl.cjs');
+var getErrorMessage = require('../utilities/getErrorMessage.cjs');
+var mergeHeaders = require('../utilities/mergeHeaders.cjs');
+var prepareRequestBody = require('../utilities/prepareRequestBody.cjs');
+var isStatusAccepted = require('../utilities/isStatusAccepted.cjs');
+
+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 httpResponseTypes.HTTP_RESPONSE_TYPES.ARRAY_BUFFER:
+        case httpResponseTypes.HTTP_RESPONSE_TYPES.BLOB:
+            return xhr.response;
+        case httpResponseTypes.HTTP_RESPONSE_TYPES.TEXT:
+            return xhr.response;
+        case httpResponseTypes.HTTP_RESPONSE_TYPES.JSON:
+        default: {
+            const resolvedResponseType = responseType ?? httpResponseTypes.HTTP_RESPONSE_TYPES.JSON;
+            const text = xhr.response;
+            if (!text) {
+                return undefined;
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch (error) {
+                throw new ParseError.ParseError('Failed to parse response body as JSON', {
+                    cause: error,
+                    config,
+                    responseType: resolvedResponseType,
+                    raw: text
+                });
+            }
+        }
+    }
+}
+function setResponseType(xhr, responseType) {
+    if (responseType === httpResponseTypes.HTTP_RESPONSE_TYPES.ARRAY_BUFFER) {
+        // XHR accepts only a lowercase DOM value.
+        xhr.responseType = 'arraybuffer';
+    }
+    else if (responseType === httpResponseTypes.HTTP_RESPONSE_TYPES.BLOB) {
+        xhr.responseType = 'blob';
+    }
+    else {
+        xhr.responseType = 'text';
+    }
+}
+function assertStreamingSupported(responseType, config) {
+    if (responseType === httpResponseTypes.HTTP_RESPONSE_TYPES.STREAM &&
+        (typeof ReadableStream === 'undefined' || typeof TextEncoder === 'undefined')) {
+        throw new RequestPreparationError.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.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.buildUrl(baseURL, url, params);
+    if (userSignal?.aborted) {
+        throw new AbortError.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.mergeHeaders(headers);
+    const body = data !== undefined && method !== httpMethods.HTTP_METHODS.GET && method !== httpMethods.HTTP_METHODS.HEAD
+        ? prepareRequestBody.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.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 === httpResponseTypes.HTTP_RESPONSE_TYPES.STREAM) {
+        xhr.onreadystatechange = () => {
+            if (xhr.readyState === XMLHttpRequest.HEADERS_RECEIVED) {
+                try {
+                    resolveStream();
+                }
+                catch (error) {
+                    request.cleanup();
+                    reject(error);
+                    xhr.abort();
+                }
+            }
+        };
+    }
+    if (responseType === httpResponseTypes.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 === httpResponseTypes.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.HttpClientError
+                ? error
+                : new NetworkError.NetworkError(getErrorMessage.getErrorMessage(error, 'Network request failed'), { cause: error, config }));
+        }
+    };
+    xhr.onerror = event => {
+        rejectOrFailStream(new NetworkError.NetworkError('Network request failed', { cause: event, config }));
+    };
+    xhr.onabort = event => {
+        rejectOrFailStream(new AbortError.AbortError('Request was aborted', { cause: userSignal?.reason ?? event, config }));
+    };
+    xhr.ontimeout = event => {
+        const timeoutMs = timeout ?? 0;
+        rejectOrFailStream(new TimeoutError.TimeoutError(`Request timed out after ${timeoutMs}ms`, {
+            cause: event,
+            config,
+            timeout: timeoutMs
+        }));
+    };
+}
+class XhrAdapter {
+    options;
+    constructor(options = {}) {
+        assertValidXhrAdapterOptions.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.HttpClientError
+                    ? error
+                    : new RequestPreparationError.RequestPreparationError('Failed to prepare HTTP request', {
+                        cause: error,
+                        config: resolvedConfig
+                    }));
+            }
+        });
+    }
+}
+
+exports.XhrAdapter = XhrAdapter;

package/dist/cjs/asserts/assertNonBlankString.cjs

@@ -0,0 +1,11 @@
+'use strict';
+
+var RequestBuilderError = require('../errors/RequestBuilderError.cjs');
+
+function assertNonBlankString(value, message, code) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new RequestBuilderError.RequestBuilderError(message, code);
+    }
+}
+
+exports.assertNonBlankString = assertNonBlankString;

package/dist/cjs/asserts/assertValidAdapter.cjs

@@ -0,0 +1,15 @@
+'use strict';
+
+var requestBuilderErrorCodes = require('../constants/requestBuilderErrorCodes.cjs');
+var RequestBuilderError = require('../errors/RequestBuilderError.cjs');
+
+/** Validates an HTTP client adapter. */
+function assertValidAdapter(adapter) {
+    if (adapter === null ||
+        (typeof adapter !== 'object' && typeof adapter !== 'function') ||
+        typeof adapter.request !== 'function') {
+        throw new RequestBuilderError.RequestBuilderError('Adapter must implement a request method', requestBuilderErrorCodes.REQUEST_BUILDER_ERROR_CODES.INVALID_ADAPTER);
+    }
+}
+
+exports.assertValidAdapter = assertValidAdapter;

package/dist/cjs/asserts/assertValidBaseUrl.cjs

@@ -0,0 +1,10 @@
+'use strict';
+
+var requestBuilderErrorCodes = require('../constants/requestBuilderErrorCodes.cjs');
+var assertNonBlankString = require('./assertNonBlankString.cjs');
+
+function assertValidBaseUrl(baseUrl) {
+    assertNonBlankString.assertNonBlankString(baseUrl, 'Base URL must be a non-empty string', requestBuilderErrorCodes.REQUEST_BUILDER_ERROR_CODES.INVALID_BASE_URL);
+}
+
+exports.assertValidBaseUrl = assertValidBaseUrl;

package/dist/cjs/asserts/assertValidBody.cjs

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