@hyperttp/core 1.2.6 → 1.3.1

package/Core/HyperCore.js

@@ -1,124 +1,88 @@
 import { defaultConfig } from "../defaultConfig.js";
 import { mapResponseFast, mapStreamFast, mergeHeadersFast, } from "../utils/response.js";
-import { createRequire } from "node:module";
-import { createPipelines, executeErrorPipeline, executeRequestPipeline, executeResponsePipeline, insertHookSorted, } from "../utils/pipeline.js";
-import { normalizeBody, normalizeHeaders, normalizeMethod, } from "../utils/normalize.js";
-export function getRuntime() {
-    if (typeof Bun !== "undefined")
-        return "bun";
-    return "node";
-}
-export const TRANSPORTS = [
-    {
-        name: "Bun",
-        runtime: ["bun"],
-        pkg: "@hyperttp/transport-bun",
-        export: "BunTransport",
-        priority: 100,
-    },
-    {
-        name: "Undici",
-        runtime: ["node"],
-        pkg: "@hyperttp/transport-undici",
-        export: "UndiciTransport",
-        priority: 90,
-    },
-    {
-        name: "Node",
-        runtime: ["node", "bun"],
-        pkg: "../transports/node.js",
-        export: "NodeTransport",
-        priority: 10,
-    },
-];
-export async function resolveTransport(config) {
-    if (config.customTransport) {
-        config.logger?.("debug", "Using user-provided custom transport.");
-        return config.customTransport;
-    }
-    const runtime = getRuntime();
-    const candidates = TRANSPORTS.filter((t) => t.runtime.includes(runtime)).sort((a, b) => b.priority - a.priority);
-    const localRequire = createRequire(process.cwd() + "/package.json");
-    for (const t of candidates) {
-        config.logger?.("debug", `Loading transport: ${t.name}`);
-        try {
-            const path = t.pkg.startsWith(".")
-                ? new URL(t.pkg, import.meta.url).href
-                : localRequire.resolve(t.pkg);
-            const mod = await import(path);
-            const Transport = mod[t.export] || mod.default?.[t.export] || mod.default;
-            if (!Transport)
-                continue;
-            config.logger?.("info", `Selected transport: ${t.name}`);
-            return new Transport(config);
-        }
-        catch (e) {
-            config.logger?.("debug", `Skip ${t.name}: ${e}`);
-        }
-    }
-    throw new Error(`No compatible transport implementation available for runtime: ${runtime}`);
-}
+import { TransportManager } from "../transports/manager.js";
+import { createPipelines, executeErrorPipeline, executeRequestPipeline, executeResponsePipeline, executeResponseDataPipeline, insertHookSorted, } from "../utils/pipeline.js";
+import { normalizeBody, normalizeHeaders, normalizeUrl, } from "../utils/normalize.js";
+import { decompressBuffer, createDecompressStream, } from "../utils/decompress.js";
+/**
+ * @ru Основной класс HTTP-клиента Hyperttp. Управляет транспортами, плагинами, перехватчиками, повторными попытками и сжатием.
+ * @en Core HTTP client class for Hyperttp. Manages transports, plugins, interceptors, retries, and compression.
+ */
 export class HyperCore {
+    /** @ru Конфигурация клиента (базовый URL, таймауты, заголовки и т.д.). @en Client configuration (base URL, timeouts, headers, etc.). */
     config;
-    transport = null;
-    transportPromise = null;
+    transportManager;
     defaultHeaders;
     pluginCtx;
     pipelines = createPipelines();
+    /**
+     * @ru Создаёт экземпляр HyperCore.
+     * @en Creates an instance of HyperCore.
+     * @param config - Client configuration options.
+     * @param transport - Optional custom transport implementation.
+     */
     constructor(config = defaultConfig, transport) {
         this.config = {
             ...defaultConfig,
             ...config,
             network: { ...defaultConfig.network, ...config.network },
         };
-        if (transport) {
-            this.transport = transport;
-            this.transportPromise = Promise.resolve(transport);
-            if ("config" in transport) {
-                transport.config = this.config;
-            }
-        }
-        this.defaultHeaders = {
+        this.transportManager = new TransportManager(this.config, transport);
+        this.defaultHeaders = normalizeHeaders({
             Accept: "application/json, text/plain, */*",
             "Accept-Encoding": "gzip, deflate, br",
             "User-Agent": this.config.network?.userAgent ?? "Hyperttp/2.0",
             ...this.config.network?.headers,
-        };
+        });
         this.pluginCtx = { config: this.config, core: this };
     }
-    async createTransport() {
-        return resolveTransport(this.config);
+    get transport() {
+        return this.transportManager.instance;
     }
     ensureTransport() {
-        return (this.transportPromise ||
-            (this.transportPromise = this.createTransport().then((t) => {
-                this.transport = t;
-                return t;
-            })));
+        return this.transportManager.get();
     }
-    async dispatch(req) {
+    async dispatchInternal(req) {
         try {
-            const shortCircuit = await executeRequestPipeline(this.pipelines.request, req, this.pluginCtx);
-            if (shortCircuit) {
-                await executeResponsePipeline(this.pipelines.responseMutators, this.pipelines.responseSideEffects, shortCircuit, req, this.pluginCtx, this.config.logger);
-                return shortCircuit;
+            if (this.pipelines.request.length > 0) {
+                const shortCircuit = await executeRequestPipeline(this.pipelines.request, req, this.pluginCtx);
+                if (shortCircuit) {
+                    await this.runResponsePipeline(shortCircuit, req);
+                    return shortCircuit;
+                }
             }
             const transport = this.transport || (await this.ensureTransport());
-            const rawResponse = await transport.execute(req);
-            const response = mapResponseFast(rawResponse);
-            await executeResponsePipeline(this.pipelines.responseMutators, this.pipelines.responseSideEffects, response, req, this.pluginCtx, this.config.logger);
+            let rawResponse = await transport.execute(req);
+            if (this.pipelines.responseData.length > 0) {
+                rawResponse = await executeResponseDataPipeline(this.pipelines.responseData, rawResponse, this.pluginCtx);
+            }
+            this.applyDecompression(rawResponse);
+            const isStream = req.meta?.responseType === "stream";
+            const response = isStream
+                ? mapStreamFast(rawResponse)
+                : mapResponseFast(rawResponse);
+            await this.runResponsePipeline(response, req);
             return response;
         }
         catch (error) {
-            const httpError = error;
-            const recovered = await executeErrorPipeline(this.pipelines.error, httpError, req, this.pluginCtx);
-            if (recovered) {
-                await executeResponsePipeline(this.pipelines.responseMutators, this.pipelines.responseSideEffects, recovered, req, this.pluginCtx, this.config.logger);
-                return recovered;
-            }
-            throw error;
+            return this.handleDispatchError(error, req);
         }
     }
+    /**
+     * @ru Выполняет HTTP-запрос с полным контролем (через объект InternalRequest).
+     * @en Performs an HTTP request with full control (via InternalRequest object).
+     * @param req - Internal request object.
+     * @returns Promise with the HTTP response.
+     */
+    async dispatch(req) {
+        return this.dispatchInternal(req);
+    }
+    /**
+     * @ru Регистрирует плагин для расширения функциональности клиента.
+     * @en Registers a plugin to extend client functionality.
+     * @param plugin - Plugin instance.
+     * @returns This instance for chaining.
+     */
     use(plugin) {
         const isEnabled = plugin.enabled ? plugin.enabled(this.config) : true;
         if (!isEnabled)
@@ -134,20 +98,21 @@ export class HyperCore {
             });
         }
         if (plugin.onResponse) {
-            if (plugin.mode === "background") {
-                insertHookSorted(this.pipelines.responseSideEffects, {
-                    name: plugin.name,
-                    priority,
-                    run: plugin.onResponse,
-                });
-            }
-            else {
-                insertHookSorted(this.pipelines.responseMutators, {
-                    name: plugin.name,
-                    priority,
-                    run: plugin.onResponse,
-                });
-            }
+            const targetPipeline = plugin.mode === "background"
+                ? this.pipelines.responseSideEffects
+                : this.pipelines.responseMutators;
+            insertHookSorted(targetPipeline, {
+                name: plugin.name,
+                priority,
+                run: plugin.onResponse,
+            });
+        }
+        if (plugin.onResponseData) {
+            insertHookSorted(this.pipelines.responseData, {
+                name: plugin.name,
+                priority,
+                run: plugin.onResponseData,
+            });
         }
         if (plugin.onError) {
             insertHookSorted(this.pipelines.error, {
@@ -158,176 +123,305 @@ export class HyperCore {
         }
         return this;
     }
+    /**
+     * @ru Выполняет GET-запрос и возвращает ответ в виде потока (StreamResponse).
+     * @en Performs a GET request and returns the response as a stream (StreamResponse).
+     * @param req - Request URL or RequestInterface object.
+     * @param signal - Optional abort signal.
+     * @returns Promise with the stream response.
+     */
     async stream(req, signal) {
-        const isStr = typeof req === "string";
-        const url = isStr ? req : req.url;
-        const reqHeaders = isStr ? undefined : req.headers;
-        const finalSignal = isStr ? signal : (req.signal ?? signal);
-        const transportArgs = {
-            method: normalizeMethod("GET"),
-            url,
-            headers: normalizeHeaders(mergeHeadersFast(this.defaultHeaders, reqHeaders)),
-            signal: finalSignal,
-        };
-        const transport = this.transport || (await this.ensureTransport());
-        const rawResponse = await transport.execute(transportArgs);
-        return mapStreamFast(rawResponse);
+        const internalReq = this.buildInternalRequest("GET", req, undefined, signal);
+        internalReq.meta = { ...internalReq.meta, responseType: "stream" };
+        return this.dispatchInternal(internalReq);
     }
+    /**
+     * @ru Выполняет POST-запрос и возвращает ответ в виде потока (StreamResponse).
+     * @en Performs a POST request and returns the response as a stream (StreamResponse).
+     * @param req - Request URL or RequestInterface object.
+     * @param body - Request body data.
+     * @param signal - Optional abort signal.
+     * @returns Promise with the stream response.
+     */
+    async postStream(req, body, signal) {
+        const internalReq = this.buildInternalRequest("POST", req, body, signal);
+        internalReq.meta = { ...internalReq.meta, responseType: "stream" };
+        return this.dispatchInternal(internalReq);
+    }
+    /**
+     * @ru Выполняет GET-запрос.
+     * @en Performs a GET request.
+     * @param req - Request URL or RequestInterface object.
+     * @param signal - Optional abort signal.
+     * @returns Promise with the HTTP response.
+     */
     get(req, signal) {
         return this.dispatch(this.buildInternalRequest("GET", req, undefined, signal));
     }
+    /**
+     * @ru Выполняет POST-запрос.
+     * @en Performs a POST request.
+     * @param req - Request URL or RequestInterface object.
+     * @param body - Request body data.
+     * @param signal - Optional abort signal.
+     * @returns Promise with the HTTP response.
+     */
     post(req, body, signal) {
         return this.dispatch(this.buildInternalRequest("POST", req, body, signal));
     }
-    async postStream(req, body, signal) {
-        const isStr = typeof req === "string";
-        const url = isStr ? req : req.url;
-        const reqHeaders = isStr ? undefined : req.headers;
-        const finalSignal = isStr ? signal : (req.signal ?? signal);
-        const transportArgs = {
-            method: normalizeMethod("POST"),
-            url,
-            headers: normalizeHeaders(mergeHeadersFast(this.defaultHeaders, reqHeaders)),
-            body: normalizeBody("POST", isStr ? body : (req.body ?? body)),
-            signal: finalSignal,
-        };
-        const transport = this.transport || (await this.ensureTransport());
-        const rawResponse = await transport.execute(transportArgs);
-        return mapStreamFast(rawResponse);
-    }
+    /**
+     * @ru Выполняет PUT-запрос.
+     * @en Performs a PUT request.
+     * @param req - Request URL or RequestInterface object.
+     * @param body - Request body data.
+     * @param signal - Optional abort signal.
+     * @returns Promise with the HTTP response.
+     */
     put(req, body, signal) {
         return this.dispatch(this.buildInternalRequest("PUT", req, body, signal));
     }
+    /**
+     * @ru Выполняет PATCH-запрос.
+     * @en Performs a PATCH request.
+     * @param req - Request URL or RequestInterface object.
+     * @param body - Request body data.
+     * @param signal - Optional abort signal.
+     * @returns Promise with the HTTP response.
+     */
     patch(req, body, signal) {
         return this.dispatch(this.buildInternalRequest("PATCH", req, body, signal));
     }
+    /**
+     * @ru Выполняет DELETE-запрос.
+     * @en Performs a DELETE request.
+     * @param req - Request URL or RequestInterface object.
+     * @param signal - Optional abort signal.
+     * @returns Promise with the HTTP response.
+     */
     delete(req, signal) {
         return this.dispatch(this.buildInternalRequest("DELETE", req, undefined, signal));
     }
+    /**
+     * @ru Выполняет OPTIONS-запрос.
+     * @en Performs an OPTIONS request.
+     * @param req - Request URL or RequestInterface object.
+     * @param body - Optional request body data.
+     * @param signal - Optional abort signal.
+     * @returns Promise with the HTTP response.
+     */
     options(req, body, signal) {
         return this.dispatch(this.buildInternalRequest("OPTIONS", req, body, signal));
     }
+    /**
+     * @ru Выполняет HEAD-запрос.
+     * @en Performs a HEAD request.
+     * @param req - Request URL or RequestInterface object.
+     * @param signal - Optional abort signal.
+     * @returns Promise with the HTTP response (body is always null).
+     */
     head(req, signal) {
         return this.dispatch(this.buildInternalRequest("HEAD", req, undefined, signal));
     }
-    buildInternalRequest(method, req, body, signal) {
-        const isStr = typeof req === "string";
-        let rawUrl = isStr ? req : req?.url;
-        if (!rawUrl && !isStr && req && "scheme" in req && "host" in req) {
-            const casted = req;
-            try {
-                const cleanHost = String(casted.host).replace(/^https?:\/\//i, "");
-                const urlObj = new URL(`${casted.scheme}://${cleanHost}`);
-                if (casted.port)
-                    urlObj.port = String(casted.port);
-                if (casted.path)
-                    urlObj.pathname = casted.path;
-                if (casted.query) {
-                    for (const [key, value] of Object.entries(casted.query)) {
-                        if (value == null)
-                            continue;
-                        if (Array.isArray(value)) {
-                            value.forEach((v) => urlObj.searchParams.append(key, String(v)));
-                        }
-                        else {
-                            urlObj.searchParams.set(key, String(value));
-                        }
-                    }
-                }
-                rawUrl = urlObj.toString();
-                // eslint-disable-next-line @typescript-eslint/no-unused-vars
-            }
-            catch (_e) {
-                //
+    /**
+     * @ru Создаёт новый экземпляр HyperCore с расширенной конфигурацией (поверх текущей).
+     * @en Creates a new HyperCore instance with extended configuration (on top of current).
+     * @param options - Additional configuration options.
+     * @returns New HyperCore instance.
+     */
+    extend(options) {
+        return new HyperCore({
+            ...this.config,
+            ...options,
+            network: { ...this.config.network, ...options.network },
+        }, this.transport ?? undefined);
+    }
+    /**
+     * @ru Алиас для extend(). Создаёт новый экземпляр HyperCore.
+     * @en Alias for extend(). Creates a new HyperCore instance.
+     * @param options - Configuration options.
+     * @returns New HyperCore instance.
+     */
+    create(options) {
+        return this.extend(options);
+    }
+    /**
+     * @ru Уничтожает клиент, закрывая соединения и очищая ресурсы.
+     * @en Destroys the client, closing connections and cleaning up resources.
+     * @param graceful - If true, attempts graceful shutdown (default: true).
+     * @returns Promise that resolves when destruction is complete.
+     */
+    async destroy(graceful = true) {
+        await this.transportManager.destroy(graceful);
+    }
+    /**
+     * @ru Выполняет запрос и сразу возвращает распарсенный JSON (сокращённый метод).
+     * @en Performs a request and immediately returns parsed JSON (shortcut method).
+     * @param req - Request URL or RequestInterface object.
+     * @param signal - Optional abort signal.
+     * @returns Promise with the parsed JSON value.
+     * @throws If the response does not contain a json() method.
+     */
+    async json(req, signal) {
+        const res = await this.dispatchShortcut(req, signal);
+        if (!res.json)
+            throw new Error("[HyperCore] Method 'json()' is missing on response object.");
+        return res.json();
+    }
+    /**
+     * @ru Выполняет запрос и возвращает тело как строку (сокращённый метод).
+     * @en Performs a request and returns the body as a string (shortcut method).
+     * @param req - Request URL or RequestInterface object.
+     * @param signal - Optional abort signal.
+     * @returns Promise with the response text.
+     * @throws If the response does not contain a text() method.
+     */
+    async text(req, signal) {
+        const res = await this.dispatchShortcut(req, signal);
+        if (!res.text)
+            throw new Error("[HyperCore] Method 'text()' is missing on response object.");
+        return res.text();
+    }
+    /**
+     * @ru Выполняет запрос и немедленно отменяет (сбрасывает) тело ответа без чтения.
+     * @en Performs a request and immediately discards the response body without reading.
+     * @param req - Request URL or RequestInterface object.
+     * @param signal - Optional abort signal.
+     * @returns Promise that resolves after dumping the response.
+     * @throws If the response does not contain a dump() method.
+     */
+    async dump(req, signal) {
+        const res = await this.dispatchShortcut(req, signal);
+        if (!res.dump)
+            throw new Error("[HyperCore] Method 'dump()' is missing on response object.");
+        await res.dump();
+    }
+    async runResponsePipeline(response, req) {
+        const hasMutators = this.pipelines.responseMutators.length > 0;
+        const hasSideEffects = this.pipelines.responseSideEffects.length > 0;
+        if (hasMutators || hasSideEffects) {
+            await executeResponsePipeline(this.pipelines.responseMutators, this.pipelines.responseSideEffects, response, req, this.pluginCtx, this.config.logger);
+        }
+    }
+    async handleDispatchError(error, req) {
+        if (this.pipelines.error.length > 0) {
+            const recovered = await executeErrorPipeline(this.pipelines.error, error, req, this.pluginCtx);
+            if (recovered) {
+                await this.runResponsePipeline(recovered, req);
+                return recovered;
             }
         }
-        if (this.config.baseURL && rawUrl && !/^https?:\/\//i.test(rawUrl)) {
-            rawUrl = new URL(rawUrl, this.config.baseURL).toString();
+        throw error;
+    }
+    applyDecompression(rawResponse) {
+        if (!rawResponse.body)
+            return;
+        const encodingHeader = rawResponse.headers?.["content-encoding"] ??
+            rawResponse.headers?.["Content-Encoding"];
+        if (!encodingHeader)
+            return;
+        const contentEncoding = typeof encodingHeader === "string"
+            ? encodingHeader
+            : Array.isArray(encodingHeader)
+                ? encodingHeader[0]
+                : undefined;
+        if (!contentEncoding)
+            return;
+        if (rawResponse.body instanceof Uint8Array) {
+            rawResponse.body = decompressBuffer(rawResponse.body, contentEncoding);
         }
+        else {
+            rawResponse.body = createDecompressStream(rawResponse.body, contentEncoding);
+        }
+    }
+    buildInternalRequest(method, req, body, signal) {
+        const isStr = typeof req === "string";
+        const rawUrl = normalizeUrl(req);
         if (!rawUrl) {
-            throw new Error(`[HyperttpCore] Critical execution failure during ${method} method invocation: 'url' resolved to undefined. ` +
-                `Verify incoming arguments or environment configurations.`);
+            throw new Error(`[HyperCore] Critical failure: 'url' resolved to undefined for ${method}.`);
+        }
+        const urlObj = new URL(rawUrl);
+        const castedReq = isStr
+            ? undefined
+            : req;
+        if (castedReq?.query) {
+            this.appendQueryParams(urlObj, castedReq.query);
         }
+        const context = {
+            method,
+            url: urlObj.href,
+            origin: urlObj.origin,
+            path: urlObj.pathname + urlObj.search,
+        };
         if (isStr) {
             return {
-                method: normalizeMethod(method),
-                url: rawUrl,
-                headers: normalizeHeaders(this.defaultHeaders),
+                ...context,
+                headers: { ...this.defaultHeaders },
                 body,
                 signal,
-                meta: undefined,
+                meta: {},
             };
         }
-        const castedReq = req;
-        const rawHeaders = req.headers ?? castedReq._headers;
+        const rawHeaders = (req.headers ?? castedReq._headers);
         const headers = rawHeaders
-            ? mergeHeadersFast(this.defaultHeaders, rawHeaders)
+            ? normalizeHeaders(mergeHeadersFast(this.defaultHeaders, rawHeaders))
             : { ...this.defaultHeaders };
-        const internalRequest = {
-            method: normalizeMethod(method),
-            url: rawUrl,
-            headers: normalizeHeaders(headers),
-            body: normalizeBody(method, castedReq.body ?? castedReq._bodyData ?? body),
-            signal: req.signal ?? castedReq._signal ?? signal,
-            meta: (req.meta ?? castedReq._meta),
-        };
-        this.config.logger?.("debug", `[HyperttpCore] Internal request dispatched: { ` +
-            `method: "${internalRequest.method}", ` +
-            `url: "${internalRequest.url}", ` +
-            `headersCount: ${Object.keys(internalRequest.headers).length}, ` +
-            `bodyType: "${typeof internalRequest.body}", ` +
-            `bodyLength: ${typeof internalRequest.body === "string" ? internalRequest.body.length : 0} ` +
-            `}`);
-        return internalRequest;
-    }
-    extend(options) {
-        this.config = {
-            ...this.config,
-            ...options,
-            network: { ...this.config.network, ...options.network },
-        };
-        this.pluginCtx.config = this.config;
-        return this;
-    }
-    create(options) {
-        return new HyperCore({
-            ...this.config,
-            ...options,
-            network: { ...this.config.network, ...options.network },
-        }, this.transport ?? undefined);
+        const rawBody = castedReq.body ?? castedReq.bodyData ?? castedReq._bodyData ?? body;
+        const computedBody = normalizeBody(method, rawBody);
+        const computedSignal = req.signal ?? castedReq._signal ?? signal;
+        const meta = (req.meta ??
+            castedReq._meta ??
+            {});
+        return this.createInternalRequestObject(castedReq, {
+            ...context,
+            headers,
+            body: computedBody,
+            signal: computedSignal,
+            meta,
+        });
     }
-    async destroy(graceful = true) {
-        this.config.logger?.("debug", "Destroying transport...");
-        const transport = this.transport;
-        if (!transport)
-            return;
-        if (graceful && typeof transport.close === "function") {
-            await transport.close();
+    createInternalRequestObject(sourceReq, overrides) {
+        const proto = Object.getPrototypeOf(sourceReq);
+        const target = proto && proto !== Object.prototype ? Object.create(proto) : {};
+        for (const key in sourceReq) {
+            if (Object.prototype.hasOwnProperty.call(sourceReq, key)) {
+                target[key] = sourceReq[key];
+            }
         }
-        else if (typeof transport.destroy === "function") {
-            await transport.destroy();
+        for (const key in overrides) {
+            if (Object.prototype.hasOwnProperty.call(overrides, key)) {
+                target[key] = overrides[key];
+            }
         }
+        return target;
     }
-    async json(req, signal) {
-        const method = typeof req === "string"
-            ? "GET"
-            : (req.method ?? "GET");
-        const res = await this.dispatch(this.buildInternalRequest(method, req, undefined, signal));
-        return res.json();
-    }
-    async text(req, signal) {
-        const method = typeof req === "string"
-            ? "GET"
-            : (req.method ?? "GET");
-        const res = await this.dispatch(this.buildInternalRequest(method, req, undefined, signal));
-        return res.text();
+    appendQueryParams(url, query) {
+        if (!query)
+            return;
+        for (const key in query) {
+            if (Object.prototype.hasOwnProperty.call(query, key)) {
+                const value = query[key];
+                if (value === undefined || value === null)
+                    continue;
+                if (Array.isArray(value)) {
+                    const len = value.length;
+                    for (let i = 0; i < len; i++) {
+                        const item = value[i];
+                        if (item === undefined || item === null)
+                            continue;
+                        url.searchParams.append(key, String(item));
+                    }
+                }
+                else {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
     }
-    async dump(req, signal) {
+    async dispatchShortcut(req, signal) {
         const method = typeof req === "string"
             ? "GET"
             : (req.method ?? "GET");
-        const res = await this.dispatch(this.buildInternalRequest(method, req, undefined, signal));
-        await res.dump();
+        return this.dispatch(this.buildInternalRequest(method, req, undefined, signal));
     }
 }
 //# sourceMappingURL=HyperCore.js.map