@samchon/openapi/src/HttpMigration.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 { HttpMigrateApplicationComposer } from "./composers/migrate/HttpMigrateApplicationComposer";
import { HttpMigrateRouteFetcher } from "./http/HttpMigrateRouteFetcher";
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 namespace HttpMigration {
  /* -----------------------------------------------------------
    COMPOSER
  ----------------------------------------------------------- */
  /**
   * 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.
   */
  export const application = (
    document:
      | OpenApi.IDocument
      | SwaggerV2.IDocument
      | OpenApiV3.IDocument
      | OpenApiV3_1.IDocument,
  ): IHttpMigrateApplication =>
    HttpMigrateApplicationComposer.compose(OpenApi.convert(document));

  /** Properties for the request to the HTTP server. */
  export 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;
  }

  /* -----------------------------------------------------------
    FETCHERS
  ----------------------------------------------------------- */
  /**
   * 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.
   */
  export const execute = (props: IFetchProps): Promise<unknown> =>
    HttpMigrateRouteFetcher.execute(props);

  /**
   * 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.
   */
  export const propagate = (props: IFetchProps): Promise<IHttpResponse> =>
    HttpMigrateRouteFetcher.propagate(props);
}