@samchon/openapi/lib/HttpMigration.d.ts

OpenAPI definitions and converters for 'typia' and 'nestia'.

import { OpenApi } from "./OpenApi";
import { OpenApiV3 } from "./OpenApiV3";
import { OpenApiV3_1 } from "./OpenApiV3_1";
import { SwaggerV2 } from "./SwaggerV2";
import { IHttpConnection } from "./structures/IHttpConnection";
import { IHttpMigrateApplication } from "./structures/IHttpMigrateApplication";
import { IHttpMigrateRoute } from "./structures/IHttpMigrateRoute";
import { IHttpResponse } from "./structures/IHttpResponse";
/**
 * HTTP migration application composer from OpenAPI document.
 *
 * `HttpMigration` is a module for composing HTTP migration application from the
 * {@link OpenApi.IDocument OpenAPI document}. It is designed for helping the
 * OpenAPI generator libraries, which converts
 * {@link OpenApi.IOperation OpenAPI operations} to an RPC (Remote Procedure
 * Call) function.
 *
 * The key feature of the `HttpModule` is the {@link HttpMigration.application}
 * function. It converts the {@link OpenApi.IOperation OpenAPI operations} to the
 * {@link IHttpMigrateRoute HTTP migration route}, and it normalizes the OpenAPI
 * operations to the RPC function calling suitable route structure.
 *
 * The other functions, {@link HttpMigration.execute} and
 * {@link HttpMigration.propagate}, are for executing the HTTP request to the
 * HTTP server. The {@link HttpMigration.execute} function returns the response
 * body from the API endpoint when the status code is `200` or `201`. Otherwise,
 * it throws an {@link HttpError} when the status code is not `200` or `201`. The
 * {@link HttpMigration.propagate} function returns the response information from
 * the API endpoint, including the status code, headers, and response body.
 *
 * The {@link HttpLlm} module is a good example utilizing this `HttpMigration`
 * module for composing RPC function calling application. The {@link HttpLlm}
 * module composes LLM (Large Language Model) function calling application from
 * the OpenAPI document bypassing through the {@link IHttpLlmApplication} type.
 *
 * @author Jeongho Nam - https://github.com/samchon
 */
export declare namespace HttpMigration {
    /**
     * Convert HTTP migration application from OpenAPI document.
     *
     * `HttpMigration.application()` is a function converting the
     * {@link OpenApi.IDocument OpenAPI document} and its
     * {@link OpenApi.IOperation operations} to the
     * {@link IHttpMigrateApplication HTTP migration application}.
     *
     * The HTTP migration application is designed for helping the OpenAPI
     * generator libraries, which converts OpenAPI operations to an RPC (Remote
     * Procedure Call) function. To support the OpenAPI generator libraries,
     * {@link IHttpMigrateRoute} takes below normalization rules:
     *
     * - Path parameters are separated to atomic level.
     * - Query parameters are binded into one object.
     * - Header parameters are binded into one object.
     * - Allow only below HTTP methods
     *
     *   - `head`
     *   - `get`
     *   - `post`
     *   - `put`
     *   - `patch`
     *   - `delete`
     * - Allow only below content media types
     *
     *   - `application/json`
     *   - `application/x-www-form-urlencoded`
     *   - `multipart/form-data`
     *   - `text/plain`
     *
     * If there're some {@link OpenApi.IOperation API operations} which canont
     * adjust the above rules or there're some logically insensible, these
     * operation would be failed to migrate and registered into the
     * {@link IHttpMigrateApplication.errors}.
     *
     * @param document OpenAPI document to migrate.
     * @returns Migrated application.
     */
    const application: (document: OpenApi.IDocument | SwaggerV2.IDocument | OpenApiV3.IDocument | OpenApiV3_1.IDocument) => IHttpMigrateApplication;
    /** Properties for the request to the HTTP server. */
    interface IFetchProps {
        /** Connection info to the HTTP server. */
        connection: IHttpConnection;
        /** Route information for the migration. */
        route: IHttpMigrateRoute;
        /**
         * Path parameters.
         *
         * Path parameters with sequenced array or key-value paired object.
         */
        parameters: Array<string | number | boolean | bigint | null> | Record<string, string | number | boolean | bigint | null>;
        /** Query parameters as a key-value paired object. */
        query?: object | undefined;
        /** Request body data. */
        body?: object | undefined;
    }
    /**
     * Execute the HTTP request.
     *
     * `HttpMigration.execute()` is a function executing the HTTP request to the
     * HTTP server.
     *
     * It returns the response body from the API endpoint when the status code is
     * `200` or `201`. Otherwise, it throws an {@link HttpError} when the status
     * code is not `200` or `201`.
     *
     * If you want to get more information than the response body, or get the
     * detailed response information even when the status code is `200` or `201`,
     * use the {@link HttpMigration.propagate} function instead.
     *
     * @param props Properties for the request.
     * @returns Return value (response body) from the API endpoint.
     * @throws HttpError when the API endpoint responds none 200/201 status.
     */
    const execute: (props: IFetchProps) => Promise<unknown>;
    /**
     * Propagate the HTTP request.
     *
     * `HttpMigration.propagate()` is a function propagating the request to the
     * HTTP server.
     *
     * It returns the response information from the API endpoint, including the
     * status code, headers, and response body.
     *
     * Even if the status code is not `200` or `201`, this function would return
     * the response information. By the way, if the connection to the HTTP server
     * is failed, this function would throw an {@link Error}.
     *
     * @param props Properties for the request.
     * @returns Response from the API endpoint.
     * @throws Error when the connection is failed.
     */
    const propagate: (props: IFetchProps) => Promise<IHttpResponse>;
}