typia 7.0.2 → 7.1.0-dev.20241209

package/src/reflect.ts

@@ -1,57 +1,57 @@
-import { IMetadataApplication } from "./schemas/metadata/IMetadataApplication";
-
-/**
- * > You must configure the generic argument `Types`.
- *
- * Metadata Application.
- *
- * Creates a Metadata application which contains the metadata and components.
- *
- * Note that, all of the collection types like Array, Tuple and Objects are
- * stored in the {@link IMetadataApplication.components} property. Also, alias
- * types are stored in the {@link IMetadataApplication.aliases} property, too.
- *
- * @template Types Tuple of target types
- * @returns Metadata application
- *
- * @author Jeongho Nam - https://github.com/samchon
- */
-export function metadata(): never;
-
-/**
- * Metadata Application.
- *
- * Creates a Metadata application which contains the metadata and components.
- *
- * Note that, all of the collection types like Array, Tuple and Objects are
- * stored in the {@link IMetadataApplication.components} property. Also, alias
- * types are stored in the {@link IMetadataApplication.aliases} property, too.
- *
- * @template Types Tuple of target types
- * @returns Metadata application
- *
- * @author Jeongho Nam - https://github.com/samchon
- */
-export function metadata<Types extends unknown[]>(): IMetadataApplication;
-
-/**
- * @internal
- */
-export function metadata(): never {
-  halt("metadata");
-}
-
-export function name<T, Regular extends boolean = false>(): string;
-export function name(): never;
-export function name(): never {
-  halt("name");
-}
-
-/**
- * @internal
- */
-function halt(name: string): never {
-  throw new Error(
-    `Error on typia.reflect.${name}(): no transform has been configured. Read and follow https://typia.io/docs/setup please.`,
-  );
-}
+import { IMetadataApplication } from "./schemas/metadata/IMetadataApplication";
+
+/**
+ * > You must configure the generic argument `Types`.
+ *
+ * Metadata Application.
+ *
+ * Creates a Metadata application which contains the metadata and components.
+ *
+ * Note that, all of the collection types like Array, Tuple and Objects are
+ * stored in the {@link IMetadataApplication.components} property. Also, alias
+ * types are stored in the {@link IMetadataApplication.aliases} property, too.
+ *
+ * @template Types Tuple of target types
+ * @returns Metadata application
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export function metadata(): never;
+
+/**
+ * Metadata Application.
+ *
+ * Creates a Metadata application which contains the metadata and components.
+ *
+ * Note that, all of the collection types like Array, Tuple and Objects are
+ * stored in the {@link IMetadataApplication.components} property. Also, alias
+ * types are stored in the {@link IMetadataApplication.aliases} property, too.
+ *
+ * @template Types Tuple of target types
+ * @returns Metadata application
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export function metadata<Types extends unknown[]>(): IMetadataApplication;
+
+/**
+ * @internal
+ */
+export function metadata(): never {
+  halt("metadata");
+}
+
+export function name<T, Regular extends boolean = false>(): string;
+export function name(): never;
+export function name(): never {
+  halt("name");
+}
+
+/**
+ * @internal
+ */
+function halt(name: string): never {
+  throw new Error(
+    `Error on typia.reflect.${name}(): no transform has been configured. Read and follow https://typia.io/docs/setup please.`,
+  );
+}

package/src/schemas/json/IJsonApplication.ts

@@ -1,73 +1,73 @@
-import { IJsonSchemaCollection } from "./IJsonSchemaCollection";
-
-/**
- * Collection of JSON schemas.
- *
- * @deprecated Use {@link IJsonSchemaCollection} instead please.
- *             This interface type would be changed to {@link ILlmApplication} like
- *             structure in the future version (maybe next v8 major update).
- * @template Version Version of the OpenAPI specification.
- * @template Types Original TypeScript types used in the JSON schemas.
- * @author Jeongho Nam - https://github.com/samchon
- */
-export import IJsonApplication = IJsonSchemaCollection;
-
-// export interface IJsonApplication<
-//   Version extends "3.0" | "3.1" = "3.1",
-//   App extends any = object,
-// > {
-//   version: Version;
-//   components: IJsonApplication.IComponents<IJsonApplication.Schema<Version>>;
-//   functions: IJsonApplication.IFunction<IJsonApplication.Schema<Version>>[];
-//   __application?: App | undefined;
-// }
-// export namespace IJsonApplication {
-//   export type Schema<Version extends "3.0" | "3.1"> = Version extends "3.1"
-//     ? OpenApi.IJsonSchema
-//     : OpenApiV3.IJsonSchema;
-
-//   export interface IComponents<
-//     Schema extends
-//       | OpenApi.IJsonSchema
-//       | OpenApiV3.IJsonSchema = OpenApi.IJsonSchema,
-//   > {
-//     schemas?: Record<string, Schema>;
-//   }
-
-//   export interface IFunction<
-//     Schema extends
-//       | OpenApi.IJsonSchema
-//       | OpenApiV3.IJsonSchema = OpenApi.IJsonSchema,
-//   > {
-//     async: boolean;
-//     name: string;
-//     parameters: IParameter<Schema>[];
-//     output: IOutput<Schema> | undefined;
-//     summary?: string | undefined;
-//     description?: string | undefined;
-//     deprecated?: boolean;
-//     tags?: string[];
-//   }
-
-//   export interface IParameter<
-//     Schema extends
-//       | OpenApi.IJsonSchema
-//       | OpenApiV3.IJsonSchema = OpenApi.IJsonSchema,
-//   > {
-//     name: string;
-//     required: boolean;
-//     schema: Schema;
-//     title?: string | undefined;
-//     description?: string | undefined;
-//   }
-
-//   export interface IOutput<
-//     Schema extends
-//       | OpenApi.IJsonSchema
-//       | OpenApiV3.IJsonSchema = OpenApi.IJsonSchema,
-//   > {
-//     schema: Schema;
-//     required: boolean;
-//     description?: string | undefined;
-//   }
-// }
+import { IJsonSchemaCollection } from "./IJsonSchemaCollection";
+
+/**
+ * Collection of JSON schemas.
+ *
+ * @deprecated Use {@link IJsonSchemaCollection} instead please.
+ *             This interface type would be changed to {@link ILlmApplication} like
+ *             structure in the future version (maybe next v8 major update).
+ * @template Version Version of the OpenAPI specification.
+ * @template Types Original TypeScript types used in the JSON schemas.
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export import IJsonApplication = IJsonSchemaCollection;
+
+// export interface IJsonApplication<
+//   Version extends "3.0" | "3.1" = "3.1",
+//   App extends any = object,
+// > {
+//   version: Version;
+//   components: IJsonApplication.IComponents<IJsonApplication.Schema<Version>>;
+//   functions: IJsonApplication.IFunction<IJsonApplication.Schema<Version>>[];
+//   __application?: App | undefined;
+// }
+// export namespace IJsonApplication {
+//   export type Schema<Version extends "3.0" | "3.1"> = Version extends "3.1"
+//     ? OpenApi.IJsonSchema
+//     : OpenApiV3.IJsonSchema;
+
+//   export interface IComponents<
+//     Schema extends
+//       | OpenApi.IJsonSchema
+//       | OpenApiV3.IJsonSchema = OpenApi.IJsonSchema,
+//   > {
+//     schemas?: Record<string, Schema>;
+//   }
+
+//   export interface IFunction<
+//     Schema extends
+//       | OpenApi.IJsonSchema
+//       | OpenApiV3.IJsonSchema = OpenApi.IJsonSchema,
+//   > {
+//     async: boolean;
+//     name: string;
+//     parameters: IParameter<Schema>[];
+//     output: IOutput<Schema> | undefined;
+//     summary?: string | undefined;
+//     description?: string | undefined;
+//     deprecated?: boolean;
+//     tags?: string[];
+//   }
+
+//   export interface IParameter<
+//     Schema extends
+//       | OpenApi.IJsonSchema
+//       | OpenApiV3.IJsonSchema = OpenApi.IJsonSchema,
+//   > {
+//     name: string;
+//     required: boolean;
+//     schema: Schema;
+//     title?: string | undefined;
+//     description?: string | undefined;
+//   }
+
+//   export interface IOutput<
+//     Schema extends
+//       | OpenApi.IJsonSchema
+//       | OpenApiV3.IJsonSchema = OpenApi.IJsonSchema,
+//   > {
+//     schema: Schema;
+//     required: boolean;
+//     description?: string | undefined;
+//   }
+// }

package/src/schemas/json/IJsonSchemaCollection.ts

@@ -1,29 +1,29 @@
-import type { OpenApi, OpenApiV3 } from "@samchon/openapi";
-
-/**
- * Collection of JSON schemas.
- *
- * @template Version Version of the OpenAPI specification.
- * @template Types Original TypeScript types used in the JSON schemas.
- * @author Jeongho Nam - https://github.com/samchon
- */
-export type IJsonSchemaCollection<
-  Version extends "3.0" | "3.1" = "3.1",
-  Types = unknown[],
-> = Version extends "3.0"
-  ? IJsonSchemaCollection.IV3_0<Types>
-  : IJsonSchemaCollection.IV3_1<Types>;
-export namespace IJsonSchemaCollection {
-  export interface IV3_0<Types = unknown[]> {
-    version: "3.0";
-    schemas: OpenApiV3.IJsonSchema[];
-    components: OpenApiV3.IComponents;
-    __types?: Types | undefined;
-  }
-  export interface IV3_1<Types = unknown[]> {
-    version: "3.1";
-    components: OpenApi.IComponents;
-    schemas: OpenApi.IJsonSchema[];
-    __types?: Types | undefined;
-  }
-}
+import type { OpenApi, OpenApiV3 } from "@samchon/openapi";
+
+/**
+ * Collection of JSON schemas.
+ *
+ * @template Version Version of the OpenAPI specification.
+ * @template Types Original TypeScript types used in the JSON schemas.
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export type IJsonSchemaCollection<
+  Version extends "3.0" | "3.1" = "3.1",
+  Types = unknown[],
+> = Version extends "3.0"
+  ? IJsonSchemaCollection.IV3_0<Types>
+  : IJsonSchemaCollection.IV3_1<Types>;
+export namespace IJsonSchemaCollection {
+  export interface IV3_0<Types = unknown[]> {
+    version: "3.0";
+    schemas: OpenApiV3.IJsonSchema[];
+    components: OpenApiV3.IComponents;
+    __types?: Types | undefined;
+  }
+  export interface IV3_1<Types = unknown[]> {
+    version: "3.1";
+    components: OpenApi.IComponents;
+    schemas: OpenApi.IJsonSchema[];
+    __types?: Types | undefined;
+  }
+}

package/src/schemas/json/__IJsonApplication.ts

@@ -1,63 +1,63 @@
-import { OpenApi, OpenApiV3 } from "@samchon/openapi";
-
-export interface __IJsonApplication<
-  Version extends "3.0" | "3.1" = "3.1",
-  App extends any = object,
-> {
-  version: Version;
-  components: __IJsonApplication.IComponents<
-    __IJsonApplication.Schema<Version>
-  >;
-  functions: __IJsonApplication.IFunction<__IJsonApplication.Schema<Version>>[];
-  __application?: App | undefined;
-}
-export namespace __IJsonApplication {
-  export type Schema<Version extends "3.0" | "3.1"> = Version extends "3.1"
-    ? OpenApi.IJsonSchema
-    : OpenApiV3.IJsonSchema;
-
-  export interface IComponents<
-    Schema extends
-      | OpenApi.IJsonSchema
-      | OpenApiV3.IJsonSchema = OpenApi.IJsonSchema,
-  > {
-    schemas?: Record<string, Schema>;
-  }
-
-  export interface IFunction<
-    Schema extends
-      | OpenApi.IJsonSchema
-      | OpenApiV3.IJsonSchema = OpenApi.IJsonSchema,
-  > {
-    async: boolean;
-    name: string;
-    parameters: IParameter<Schema>[];
-    output: IOutput<Schema> | undefined;
-    summary?: string | undefined;
-    description?: string | undefined;
-    deprecated?: boolean;
-    tags?: string[];
-  }
-
-  export interface IParameter<
-    Schema extends
-      | OpenApi.IJsonSchema
-      | OpenApiV3.IJsonSchema = OpenApi.IJsonSchema,
-  > {
-    name: string;
-    required: boolean;
-    schema: Schema;
-    title?: string | undefined;
-    description?: string | undefined;
-  }
-
-  export interface IOutput<
-    Schema extends
-      | OpenApi.IJsonSchema
-      | OpenApiV3.IJsonSchema = OpenApi.IJsonSchema,
-  > {
-    schema: Schema;
-    required: boolean;
-    description?: string | undefined;
-  }
-}
+import { OpenApi, OpenApiV3 } from "@samchon/openapi";
+
+export interface __IJsonApplication<
+  Version extends "3.0" | "3.1" = "3.1",
+  App extends any = object,
+> {
+  version: Version;
+  components: __IJsonApplication.IComponents<
+    __IJsonApplication.Schema<Version>
+  >;
+  functions: __IJsonApplication.IFunction<__IJsonApplication.Schema<Version>>[];
+  __application?: App | undefined;
+}
+export namespace __IJsonApplication {
+  export type Schema<Version extends "3.0" | "3.1"> = Version extends "3.1"
+    ? OpenApi.IJsonSchema
+    : OpenApiV3.IJsonSchema;
+
+  export interface IComponents<
+    Schema extends
+      | OpenApi.IJsonSchema
+      | OpenApiV3.IJsonSchema = OpenApi.IJsonSchema,
+  > {
+    schemas?: Record<string, Schema>;
+  }
+
+  export interface IFunction<
+    Schema extends
+      | OpenApi.IJsonSchema
+      | OpenApiV3.IJsonSchema = OpenApi.IJsonSchema,
+  > {
+    async: boolean;
+    name: string;
+    parameters: IParameter<Schema>[];
+    output: IOutput<Schema> | undefined;
+    summary?: string | undefined;
+    description?: string | undefined;
+    deprecated?: boolean;
+    tags?: string[];
+  }
+
+  export interface IParameter<
+    Schema extends
+      | OpenApi.IJsonSchema
+      | OpenApiV3.IJsonSchema = OpenApi.IJsonSchema,
+  > {
+    name: string;
+    required: boolean;
+    schema: Schema;
+    title?: string | undefined;
+    description?: string | undefined;
+  }
+
+  export interface IOutput<
+    Schema extends
+      | OpenApi.IJsonSchema
+      | OpenApiV3.IJsonSchema = OpenApi.IJsonSchema,
+  > {
+    schema: Schema;
+    required: boolean;
+    description?: string | undefined;
+  }
+}

package/src/schemas/llm/ILlmApplicationOfValidate.ts

@@ -0,0 +1,55 @@
+import { ILlmApplication, ILlmSchema } from "@samchon/openapi";
+
+import { ILlmFunctionOfValidate } from "./ILlmFunctionOfValidate";
+
+/**
+ * Application of LLM function calling with validators.
+ *
+ * `ILlmApplication` is a data structure representing a collection of
+ * {@link ILlmFunctionOfValidate LLM function calling schemas}, composed from a native
+ * TypeScript class (or interface) type by the `typia.llm.applicationOfValidate<App, Model>()`
+ * function.
+ *
+ * If you put the returned {@link ILlmApplicationOfValidate.functions} objects to the
+ * LLM provider like [OpenAI (ChatGPT)](https://openai.com/), the LLM will automatically
+ * select the proper function and fill its arguments from the conversation
+ * (maybe chatting text) with user (human). This is the concept of the LLM function calling.
+ *
+ * Additionally, the LLM function calling sometimes take a mistake that composing wrong typed
+ * {@link ILlmFunctionOfValidate.parameters}. In that case, deliver return value of the
+ * {@link ILlmFunctionOfValidate.validate} function, then LLM provider will correct the
+ * parameters at the next conversation. The {@link ILlmFunctionOfValidate.validate} function
+ * is a validator function reporting the detailed information about the wrong typed parameters.
+ *
+ * By the way, there can be some parameters (or their nested properties) which must be
+ * composed by Human, not by LLM. File uploading feature or some sensitive information
+ * like secrety key (password) are the examples. In that case, you can separate the
+ * function parameters to both LLM and human sides by configuring the
+ * {@link ILlmApplication.IOptions.separate} property. The separated parameters are
+ * assigned to the {@link ILlmFunction.separated} property.
+ *
+ * For reference, when both LLM and Human filled parameter values to call, you can
+ * merge them by calling the {@link HttpLlm.mergeParameters} function. In other words,
+ * if you've configured the {@link ILlmApplication.IOptions.separate} property, you
+ * have to merge the separated parameters before the funtion call execution.
+ *
+ * @reference https://platform.openai.com/docs/guides/function-calling
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface ILlmApplicationOfValidate<Model extends ILlmSchema.Model>
+  extends ILlmApplication<Model> {
+  /**
+   * List of function metadata.
+   *
+   * List of function metadata that can be used for the LLM function call.
+   *
+   * Also, every functions have their own parameters validator
+   * {@link ILlmFunctionOfValidate.validate}. If the LLM function calling composes wrong
+   * typed parameters, then deliver return value of it, then LLM will correct parameters
+   * at the next conversation.
+   */
+  functions: ILlmFunctionOfValidate<Model>[];
+}
+export namespace ILlmApplicationOfValidate {
+  export import IOptions = ILlmApplication.IOptions;
+}

package/src/schemas/llm/ILlmFunctionOfValidate.ts

@@ -0,0 +1,39 @@
+import { ILlmFunction, ILlmSchema } from "@samchon/openapi";
+
+import { IValidation } from "../../IValidation";
+
+/**
+ * LLM function metadata with validator.
+ *
+ * `ILlmFunctionOfValidate` is an interface representing a function metadata,
+ * which has been used for the LLM (Language Large Model) function
+ * calling. Also, it's a function structure containing the function
+ * {@link name}, {@link parameters} and {@link output return type}.
+ *
+ * If you provide this `ILlmFunctionOfValidate` data to the LLM provider like "OpenAI",
+ * the "OpenAI" will compose a function arguments by analyzing conversations
+ * with the user. With the LLM composed arguments, you can execute the function
+ * and get the result.
+ *
+ * If the LLM function calling take s a mistake that composing wrong typed
+ * {@link parameters}, you can correct the parameters by delivering the return
+ * value of the {@link validate} function. The {@link validate} function is a
+ * validator function reporting the detailed information about the wrong typed
+ * {@link parameters}.
+ *
+ * By the way, do not ensure that LLM will always provide the correct arguments.
+ * The LLM of present age is not perfect, and sometimes takes a mistake that composing
+ * wrong typed {@link parameters}. In that case, you can correc the parameters by
+ * delivering the return value of the {@link validate} function. The {@link validate}
+ * function reports the detailed information about the wrong typed {@link parameters},
+ *
+ * @reference https://platform.openai.com/docs/guides/function-calling
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface ILlmFunctionOfValidate<Model extends ILlmSchema.Model>
+  extends ILlmFunction<Model> {
+  validate(props: object): IValidation<unknown>;
+}
+export namespace ILlmFunctionOfValidate {
+  export import ISeparated = ILlmFunction.ISeparated;
+}

package/src/schemas/metadata/IMetadata.ts

@@ -1,35 +1,35 @@
-import { IMetadataAlias } from "./IMetadataAlias";
-import { IMetadataArray } from "./IMetadataArray";
-import { IMetadataAtomic } from "./IMetadataAtomic";
-import { IMetadataConstant } from "./IMetadataConstant";
-import { IMetadataEscaped } from "./IMetadataEscaped";
-import { IMetadataFunction } from "./IMetadataFunction";
-import { IMetadataMap } from "./IMetadataMap";
-import { IMetadataNative } from "./IMetadataNative";
-import { IMetadataObject } from "./IMetadataObject";
-import { IMetadataSet } from "./IMetadataSet";
-import { IMetadataTemplate } from "./IMetadataTemplate";
-import { IMetadataTuple } from "./IMetadataTuple";
-
-export interface IMetadata {
-  any: boolean;
-  required: boolean;
-  optional: boolean;
-  nullable: boolean;
-  functions: IMetadataFunction[];
-
-  atomics: IMetadataAtomic[];
-  constants: IMetadataConstant[];
-  templates: IMetadataTemplate[];
-  escaped: IMetadataEscaped | null;
-
-  rest: IMetadata | null;
-  arrays: IMetadataArray[];
-  tuples: IMetadataTuple[];
-  objects: IMetadataObject[];
-  aliases: IMetadataAlias[];
-
-  natives: IMetadataNative[];
-  sets: IMetadataSet[];
-  maps: IMetadataMap[];
-}
+import { IMetadataAlias } from "./IMetadataAlias";
+import { IMetadataArray } from "./IMetadataArray";
+import { IMetadataAtomic } from "./IMetadataAtomic";
+import { IMetadataConstant } from "./IMetadataConstant";
+import { IMetadataEscaped } from "./IMetadataEscaped";
+import { IMetadataFunction } from "./IMetadataFunction";
+import { IMetadataMap } from "./IMetadataMap";
+import { IMetadataNative } from "./IMetadataNative";
+import { IMetadataObject } from "./IMetadataObject";
+import { IMetadataSet } from "./IMetadataSet";
+import { IMetadataTemplate } from "./IMetadataTemplate";
+import { IMetadataTuple } from "./IMetadataTuple";
+
+export interface IMetadata {
+  any: boolean;
+  required: boolean;
+  optional: boolean;
+  nullable: boolean;
+  functions: IMetadataFunction[];
+
+  atomics: IMetadataAtomic[];
+  constants: IMetadataConstant[];
+  templates: IMetadataTemplate[];
+  escaped: IMetadataEscaped | null;
+
+  rest: IMetadata | null;
+  arrays: IMetadataArray[];
+  tuples: IMetadataTuple[];
+  objects: IMetadataObject[];
+  aliases: IMetadataAlias[];
+
+  natives: IMetadataNative[];
+  sets: IMetadataSet[];
+  maps: IMetadataMap[];
+}

package/src/schemas/metadata/IMetadataAlias.ts

@@ -1,6 +1,6 @@
-import { IMetadataTypeTag } from "./IMetadataTypeTag";
-
-export interface IMetadataAlias {
-  name: string;
-  tags: IMetadataTypeTag[][];
-}
+import { IMetadataTypeTag } from "./IMetadataTypeTag";
+
+export interface IMetadataAlias {
+  name: string;
+  tags: IMetadataTypeTag[][];
+}

package/src/schemas/metadata/IMetadataAliasType.ts

@@ -1,12 +1,12 @@
-import { IJsDocTagInfo } from "./IJsDocTagInfo";
-import { IMetadata } from "./IMetadata";
-
-export interface IMetadataAliasType {
-  name: string;
-  value: IMetadata;
-  nullables: boolean[];
-
-  description: string | null;
-  jsDocTags: IJsDocTagInfo[];
-  recursive: boolean;
-}
+import { IJsDocTagInfo } from "./IJsDocTagInfo";
+import { IMetadata } from "./IMetadata";
+
+export interface IMetadataAliasType {
+  name: string;
+  value: IMetadata;
+  nullables: boolean[];
+
+  description: string | null;
+  jsDocTags: IJsDocTagInfo[];
+  recursive: boolean;
+}