@typia/utils 12.0.1 → 12.1.0-dev.20260325

package/src/http/HttpError.ts

@@ -1,114 +1,114 @@
-/**
- * Error thrown when HTTP request fails with non-2xx status.
- *
- * `HttpError` is thrown by {@link HttpLlm.execute} and
- * {@link HttpMigration.execute} when the server returns a non-2xx status code.
- * Contains the full HTTP context: method, path, status, headers, and response
- * body.
- *
- * The response body is available via {@link message} (raw string) or
- * {@link toJSON} (parsed JSON). For non-throwing behavior, use
- * {@link HttpLlm.propagate} or {@link HttpMigration.propagate} instead.
- *
- * @author Jeongho Nam - https://github.com/samchon
- */
-export class HttpError extends Error {
-  /** HTTP method used for the request. */
-  public readonly method:
-    | "GET"
-    | "QUERY"
-    | "DELETE"
-    | "POST"
-    | "PUT"
-    | "PATCH"
-    | "HEAD";
-
-  /** Request path or URL. */
-  public readonly path: string;
-
-  /** HTTP status code from server. */
-  public readonly status: number;
-
-  /** Response headers from server. */
-  public readonly headers: Record<string, string | string[]>;
-
-  /** @internal */
-  private body_: any = NOT_YET;
-
-  /**
-   * @param method HTTP method
-   * @param path Request path or URL
-   * @param status HTTP status code
-   * @param headers Response headers
-   * @param message Error message (response body)
-   */
-  public constructor(
-    method: "GET" | "QUERY" | "DELETE" | "POST" | "PUT" | "PATCH" | "HEAD",
-    path: string,
-    status: number,
-    headers: Record<string, string | string[]>,
-    message: string,
-  ) {
-    super(message);
-    this.method = method;
-    this.path = path;
-    this.status = status;
-    this.headers = headers;
-
-    // INHERITANCE POLYFILL
-    const proto: HttpError = new.target.prototype;
-    if (Object.setPrototypeOf) Object.setPrototypeOf(this, proto);
-    else (this as any).__proto__ = proto;
-  }
-
-  /**
-   * Serialize to JSON-compatible object.
-   *
-   * Lazily parses JSON message body on first call. If parsing fails, returns
-   * the original string.
-   *
-   * @template T Expected response body type
-   * @returns Structured HTTP error information
-   */
-  public toJSON<T>(): HttpError.IProps<T> {
-    if (this.body_ === NOT_YET)
-      try {
-        this.body_ = JSON.parse(this.message);
-      } catch {
-        this.body_ = this.message;
-      }
-    return {
-      method: this.method,
-      path: this.path,
-      status: this.status,
-      headers: this.headers,
-      message: this.body_,
-    };
-  }
-}
-export namespace HttpError {
-  /**
-   * JSON representation of HttpError.
-   *
-   * @template T Response body type
-   */
-  export interface IProps<T> {
-    /** HTTP method. */
-    method: "GET" | "QUERY" | "DELETE" | "POST" | "PUT" | "PATCH" | "HEAD";
-
-    /** Request path or URL. */
-    path: string;
-
-    /** HTTP status code. */
-    status: number;
-
-    /** Response headers. */
-    headers: Record<string, string | string[]>;
-
-    /** Response body (parsed JSON or original string). */
-    message: T;
-  }
-}
-
-/** @internal */
-const NOT_YET = {} as any;
+/**
+ * Error thrown when HTTP request fails with non-2xx status.
+ *
+ * `HttpError` is thrown by {@link HttpLlm.execute} and
+ * {@link HttpMigration.execute} when the server returns a non-2xx status code.
+ * Contains the full HTTP context: method, path, status, headers, and response
+ * body.
+ *
+ * The response body is available via {@link message} (raw string) or
+ * {@link toJSON} (parsed JSON). For non-throwing behavior, use
+ * {@link HttpLlm.propagate} or {@link HttpMigration.propagate} instead.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export class HttpError extends Error {
+  /** HTTP method used for the request. */
+  public readonly method:
+    | "GET"
+    | "QUERY"
+    | "DELETE"
+    | "POST"
+    | "PUT"
+    | "PATCH"
+    | "HEAD";
+
+  /** Request path or URL. */
+  public readonly path: string;
+
+  /** HTTP status code from server. */
+  public readonly status: number;
+
+  /** Response headers from server. */
+  public readonly headers: Record<string, string | string[]>;
+
+  /** @internal */
+  private body_: any = NOT_YET;
+
+  /**
+   * @param method HTTP method
+   * @param path Request path or URL
+   * @param status HTTP status code
+   * @param headers Response headers
+   * @param message Error message (response body)
+   */
+  public constructor(
+    method: "GET" | "QUERY" | "DELETE" | "POST" | "PUT" | "PATCH" | "HEAD",
+    path: string,
+    status: number,
+    headers: Record<string, string | string[]>,
+    message: string,
+  ) {
+    super(message);
+    this.method = method;
+    this.path = path;
+    this.status = status;
+    this.headers = headers;
+
+    // INHERITANCE POLYFILL
+    const proto: HttpError = new.target.prototype;
+    if (Object.setPrototypeOf) Object.setPrototypeOf(this, proto);
+    else (this as any).__proto__ = proto;
+  }
+
+  /**
+   * Serialize to JSON-compatible object.
+   *
+   * Lazily parses JSON message body on first call. If parsing fails, returns
+   * the original string.
+   *
+   * @template T Expected response body type
+   * @returns Structured HTTP error information
+   */
+  public toJSON<T>(): HttpError.IProps<T> {
+    if (this.body_ === NOT_YET)
+      try {
+        this.body_ = JSON.parse(this.message);
+      } catch {
+        this.body_ = this.message;
+      }
+    return {
+      method: this.method,
+      path: this.path,
+      status: this.status,
+      headers: this.headers,
+      message: this.body_,
+    };
+  }
+}
+export namespace HttpError {
+  /**
+   * JSON representation of HttpError.
+   *
+   * @template T Response body type
+   */
+  export interface IProps<T> {
+    /** HTTP method. */
+    method: "GET" | "QUERY" | "DELETE" | "POST" | "PUT" | "PATCH" | "HEAD";
+
+    /** Request path or URL. */
+    path: string;
+
+    /** HTTP status code. */
+    status: number;
+
+    /** Response headers. */
+    headers: Record<string, string | string[]>;
+
+    /** Response body (parsed JSON or original string). */
+    message: T;
+  }
+}
+
+/** @internal */
+const NOT_YET = {} as any;

package/src/http/HttpLlm.ts

@@ -1,169 +1,169 @@
-import {
-  IHttpConnection,
-  IHttpLlmApplication,
-  IHttpLlmController,
-  IHttpLlmFunction,
-  IHttpMigrateApplication,
-  IHttpResponse,
-  OpenApi,
-  OpenApiV3,
-  OpenApiV3_1,
-  OpenApiV3_2,
-  SwaggerV2,
-} from "@typia/interface";
-
-import { HttpMigration } from "./HttpMigration";
-import { HttpLlmApplicationComposer } from "./internal/HttpLlmApplicationComposer";
-import { HttpLlmFunctionFetcher } from "./internal/HttpLlmFunctionFetcher";
-
-/**
- * LLM function calling utilities for OpenAPI documents.
- *
- * `HttpLlm` converts OpenAPI documents into LLM function calling applications
- * and executes them. Supports all OpenAPI versions (Swagger 2.0, OpenAPI 3.0,
- * 3.1) through automatic conversion to {@link OpenApi} format.
- *
- * Main functions:
- *
- * - {@link controller}: Create {@link IHttpLlmController} from OpenAPI document
- * - {@link application}: Convert OpenAPI document to {@link IHttpLlmApplication}
- * - {@link execute}: Call an LLM function and return the response body
- * - {@link propagate}: Call an LLM function and return full HTTP response
- * - {@link mergeParameters}: Merge LLM-filled and human-filled parameters
- *
- * Typical workflow:
- *
- * 1. Load OpenAPI document (JSON/YAML)
- * 2. Call `HttpLlm.application()` to get function schemas
- * 3. Send function schemas to LLM for function selection
- * 4. Call `HttpLlm.execute()` with LLM's chosen function and arguments
- *
- * @author Jeongho Nam - https://github.com/samchon
- */
-export namespace HttpLlm {
-  /* -----------------------------------------------------------
-    COMPOSERS
-  ----------------------------------------------------------- */
-  /**
-   * Create HTTP LLM controller from OpenAPI document.
-   *
-   * Composes {@link IHttpLlmController} from OpenAPI document with connection
-   * info. The controller can be used with {@link registerMcpControllers} to
-   * register all API operations as MCP tools at once.
-   *
-   * @param props Controller properties
-   * @returns HTTP LLM controller
-   */
-  export const controller = (props: {
-    /** Identifier name of the controller. */
-    name: string;
-
-    /** OpenAPI document to convert. */
-    document:
-      | OpenApi.IDocument
-      | SwaggerV2.IDocument
-      | OpenApiV3.IDocument
-      | OpenApiV3_1.IDocument
-      | OpenApiV3_2.IDocument;
-
-    /** Connection to the API server. */
-    connection: IHttpConnection;
-
-    /** LLM schema conversion configuration. */
-    config?: Partial<IHttpLlmApplication.IConfig>;
-
-    /**
-     * Custom executor of the API function.
-     *
-     * Default executor is {@link HttpLlm.execute} function.
-     */
-    execute?: IHttpLlmController["execute"];
-  }): IHttpLlmController => ({
-    protocol: "http",
-    name: props.name,
-    application: application({
-      document: props.document,
-      config: props.config,
-    }),
-    connection: props.connection,
-    execute: props.execute,
-  });
-
-  /**
-   * Convert OpenAPI document to LLM function calling application.
-   *
-   * Converts API operations to LLM-callable functions.
-   *
-   * @param props Composition properties
-   * @returns LLM function calling application
-   */
-  export const application = (props: {
-    /** OpenAPI document to convert. */
-    document:
-      | OpenApi.IDocument
-      | SwaggerV2.IDocument
-      | OpenApiV3.IDocument
-      | OpenApiV3_1.IDocument
-      | OpenApiV3_2.IDocument;
-
-    /** LLM schema conversion configuration. */
-    config?: Partial<IHttpLlmApplication.IConfig>;
-  }): IHttpLlmApplication => {
-    // MIGRATE
-    const migrate: IHttpMigrateApplication = HttpMigration.application(
-      props.document,
-    );
-    return HttpLlmApplicationComposer.application({
-      migrate,
-      config: {
-        strict: props.config?.strict ?? false,
-        maxLength: props.config?.maxLength ?? 64,
-        equals: props.config?.equals ?? false,
-      },
-    });
-  };
-
-  /* -----------------------------------------------------------
-    FETCHERS
-  ----------------------------------------------------------- */
-  /** Properties for LLM function call. */
-  export interface IFetchProps {
-    /** LLM function calling application. */
-    application: IHttpLlmApplication;
-
-    /** Function to call. */
-    function: IHttpLlmFunction;
-
-    /** HTTP connection info. */
-    connection: IHttpConnection;
-
-    /** Function arguments. */
-    input: object;
-  }
-
-  /**
-   * Execute LLM function call.
-   *
-   * Calls API endpoint and returns response body. Throws {@link HttpError} on
-   * non-2xx status.
-   *
-   * @param props Function call properties
-   * @returns Response body
-   * @throws HttpError on non-2xx status
-   */
-  export const execute = (props: IFetchProps): Promise<unknown> =>
-    HttpLlmFunctionFetcher.execute(props);
-
-  /**
-   * Propagate LLM function call.
-   *
-   * Calls API endpoint and returns full response including non-2xx. Use when
-   * you need to handle error responses yourself.
-   *
-   * @param props Function call properties
-   * @returns Full HTTP response
-   * @throws Error only on connection failure
-   */
-  export const propagate = (props: IFetchProps): Promise<IHttpResponse> =>
-    HttpLlmFunctionFetcher.propagate(props);
-}
+import {
+  IHttpConnection,
+  IHttpLlmApplication,
+  IHttpLlmController,
+  IHttpLlmFunction,
+  IHttpMigrateApplication,
+  IHttpResponse,
+  OpenApi,
+  OpenApiV3,
+  OpenApiV3_1,
+  OpenApiV3_2,
+  SwaggerV2,
+} from "@typia/interface";
+
+import { HttpMigration } from "./HttpMigration";
+import { HttpLlmApplicationComposer } from "./internal/HttpLlmApplicationComposer";
+import { HttpLlmFunctionFetcher } from "./internal/HttpLlmFunctionFetcher";
+
+/**
+ * LLM function calling utilities for OpenAPI documents.
+ *
+ * `HttpLlm` converts OpenAPI documents into LLM function calling applications
+ * and executes them. Supports all OpenAPI versions (Swagger 2.0, OpenAPI 3.0,
+ * 3.1) through automatic conversion to {@link OpenApi} format.
+ *
+ * Main functions:
+ *
+ * - {@link controller}: Create {@link IHttpLlmController} from OpenAPI document
+ * - {@link application}: Convert OpenAPI document to {@link IHttpLlmApplication}
+ * - {@link execute}: Call an LLM function and return the response body
+ * - {@link propagate}: Call an LLM function and return full HTTP response
+ * - {@link mergeParameters}: Merge LLM-filled and human-filled parameters
+ *
+ * Typical workflow:
+ *
+ * 1. Load OpenAPI document (JSON/YAML)
+ * 2. Call `HttpLlm.application()` to get function schemas
+ * 3. Send function schemas to LLM for function selection
+ * 4. Call `HttpLlm.execute()` with LLM's chosen function and arguments
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export namespace HttpLlm {
+  /* -----------------------------------------------------------
+    COMPOSERS
+  ----------------------------------------------------------- */
+  /**
+   * Create HTTP LLM controller from OpenAPI document.
+   *
+   * Composes {@link IHttpLlmController} from OpenAPI document with connection
+   * info. The controller can be used with {@link registerMcpControllers} to
+   * register all API operations as MCP tools at once.
+   *
+   * @param props Controller properties
+   * @returns HTTP LLM controller
+   */
+  export const controller = (props: {
+    /** Identifier name of the controller. */
+    name: string;
+
+    /** OpenAPI document to convert. */
+    document:
+      | OpenApi.IDocument
+      | SwaggerV2.IDocument
+      | OpenApiV3.IDocument
+      | OpenApiV3_1.IDocument
+      | OpenApiV3_2.IDocument;
+
+    /** Connection to the API server. */
+    connection: IHttpConnection;
+
+    /** LLM schema conversion configuration. */
+    config?: Partial<IHttpLlmApplication.IConfig>;
+
+    /**
+     * Custom executor of the API function.
+     *
+     * Default executor is {@link HttpLlm.execute} function.
+     */
+    execute?: IHttpLlmController["execute"];
+  }): IHttpLlmController => ({
+    protocol: "http",
+    name: props.name,
+    application: application({
+      document: props.document,
+      config: props.config,
+    }),
+    connection: props.connection,
+    execute: props.execute,
+  });
+
+  /**
+   * Convert OpenAPI document to LLM function calling application.
+   *
+   * Converts API operations to LLM-callable functions.
+   *
+   * @param props Composition properties
+   * @returns LLM function calling application
+   */
+  export const application = (props: {
+    /** OpenAPI document to convert. */
+    document:
+      | OpenApi.IDocument
+      | SwaggerV2.IDocument
+      | OpenApiV3.IDocument
+      | OpenApiV3_1.IDocument
+      | OpenApiV3_2.IDocument;
+
+    /** LLM schema conversion configuration. */
+    config?: Partial<IHttpLlmApplication.IConfig>;
+  }): IHttpLlmApplication => {
+    // MIGRATE
+    const migrate: IHttpMigrateApplication = HttpMigration.application(
+      props.document,
+    );
+    return HttpLlmApplicationComposer.application({
+      migrate,
+      config: {
+        strict: props.config?.strict ?? false,
+        maxLength: props.config?.maxLength ?? 64,
+        equals: props.config?.equals ?? false,
+      },
+    });
+  };
+
+  /* -----------------------------------------------------------
+    FETCHERS
+  ----------------------------------------------------------- */
+  /** Properties for LLM function call. */
+  export interface IFetchProps {
+    /** LLM function calling application. */
+    application: IHttpLlmApplication;
+
+    /** Function to call. */
+    function: IHttpLlmFunction;
+
+    /** HTTP connection info. */
+    connection: IHttpConnection;
+
+    /** Function arguments. */
+    input: object;
+  }
+
+  /**
+   * Execute LLM function call.
+   *
+   * Calls API endpoint and returns response body. Throws {@link HttpError} on
+   * non-2xx status.
+   *
+   * @param props Function call properties
+   * @returns Response body
+   * @throws HttpError on non-2xx status
+   */
+  export const execute = (props: IFetchProps): Promise<unknown> =>
+    HttpLlmFunctionFetcher.execute(props);
+
+  /**
+   * Propagate LLM function call.
+   *
+   * Calls API endpoint and returns full response including non-2xx. Use when
+   * you need to handle error responses yourself.
+   *
+   * @param props Function call properties
+   * @returns Full HTTP response
+   * @throws Error only on connection failure
+   */
+  export const propagate = (props: IFetchProps): Promise<IHttpResponse> =>
+    HttpLlmFunctionFetcher.propagate(props);
+}