Merge branch 'master' of https://github.com/samchon/typia into featur…

…e/keyword

debug/src/llm.ts

@@ -0,0 +1,19 @@
+import { ILlmApplication } from "@samchon/openapi";
+import typia from "typia";
+
+interface ICalculator {
+  /**
+   * @deprecated
+   */
+  plus(x: number, y: number): number;
+
+  /**
+   * @tag arithmetic
+   * @tag mathmatics
+   * @tag something for nothing
+   */
+  minus(x: number, y: number): number;
+}
+
+const app: ILlmApplication = typia.llm.application<ICalculator>();
+console.log(app.functions[1]?.tags);

package.json

@@ -67,7 +67,7 @@
   },
   "homepage": "https://typia.io",
   "dependencies": {
-    "@samchon/openapi": "^1.0.2",
+    "@samchon/openapi": "^1.0.6",
     "commander": "^10.0.0",
     "comment-json": "^4.2.3",
     "inquirer": "^8.2.5",

src/programmers/llm/LlmApplicationProgrammer.ts

@@ -104,38 +104,57 @@ export namespace LlmApplicationProgrammer {
     function: MetadataFunction;
     description: string | null;
     jsDocTags: IJsDocTagInfo[];
-  }): ILlmFunction => ({
-    name: props.name,
-    parameters: props.function.parameters.map((p) => {
-      const jsDocTagDescription = writeDescriptionFromJsDocTag({
-        jsDocTags: p.jsDocTags,
-        tag: "param",
-        parameter: p.name,
-      });
-      return writeSchema({
-        metadata: p.type,
-        description: jsDocTagDescription ?? p.description,
-        jsDocTags: jsDocTagDescription ? [] : p.jsDocTags,
-      });
-    }),
-    output:
-      props.function.output.size() || props.function.output.nullable
-        ? writeSchema({
-            metadata: props.function.output,
-            description:
-              writeDescriptionFromJsDocTag({
-                jsDocTags: props.jsDocTags,
-                tag: "return",
-              }) ??
-              writeDescriptionFromJsDocTag({
-                jsDocTags: props.jsDocTags,
-                tag: "returns",
-              }),
-            jsDocTags: [],
-          })
-        : undefined,
-    description: props.description ?? undefined,
-  });
+  }): ILlmFunction => {
+    const deprecated: boolean = props.jsDocTags.some(
+      (tag) => tag.name === "deprecated",
+    );
+    const tags: string[] = props.jsDocTags
+      .map((tag) =>
+        tag.name === "tag"
+          ? (tag.text?.filter((elem) => elem.kind === "text") ?? [])
+          : [],
+      )
+      .flat()
+      .map((elem) => elem.text)
+      .map((str) => str.trim().split(" ")[0] ?? "")
+      .filter((str) => !!str.length);
+    return {
+      name: props.name,
+      parameters: props.function.parameters.map((p) => {
+        const jsDocTagDescription: string | null = writeDescriptionFromJsDocTag(
+          {
+            jsDocTags: p.jsDocTags,
+            tag: "param",
+            parameter: p.name,
+          },
+        );
+        return writeSchema({
+          metadata: p.type,
+          description: jsDocTagDescription ?? p.description,
+          jsDocTags: jsDocTagDescription ? [] : p.jsDocTags,
+        });
+      }),
+      output:
+        props.function.output.size() || props.function.output.nullable
+          ? writeSchema({
+              metadata: props.function.output,
+              description:
+                writeDescriptionFromJsDocTag({
+                  jsDocTags: props.jsDocTags,
+                  tag: "return",
+                }) ??
+                writeDescriptionFromJsDocTag({
+                  jsDocTags: props.jsDocTags,
+                  tag: "returns",
+                }),
+              jsDocTags: [],
+            })
+          : undefined,
+      description: props.description ?? undefined,
+      deprecated: deprecated || undefined,
+      tags: tags.length ? tags : undefined,
+    };
+  };
 
   const writeSchema = (props: {
     metadata: Metadata;

src/tags/Example.ts

@@ -0,0 +1,17 @@
+import { TagBase } from "./TagBase";
+
+export type Example<
+  Value extends boolean | bigint | number | string | Array<unknown> | null,
+> = TagBase<{
+  target: "boolean" | "bigint" | "number" | "string" | "array";
+  kind: "example";
+  value: Value;
+  exclusive: true;
+  schema: Value extends bigint
+    ? { example: Numeric<Value> }
+    : { example: Value };
+}>;
+
+type Numeric<T extends bigint> = `${T}` extends `${infer N extends number}`
+  ? N
+  : never;

src/tags/Examples.ts

@@ -0,0 +1,16 @@
+import { TagBase } from "./TagBase";
+
+export type Examples<
+  Dict extends Record<
+    string,
+    boolean | bigint | number | string | Array<unknown> | null
+  >,
+> = TagBase<{
+  target: "boolean" | "bigint" | "number" | "string" | "array";
+  kind: "examples";
+  value: Dict;
+  exclusive: true;
+  schema: {
+    examples: Dict;
+  };
+}>;

src/tags/index.ts

@@ -1,6 +1,8 @@
 export * from "./Constant";
 export * from "./ContentMediaType";
 export * from "./Default";
+export * from "./Example";
+export * from "./Examples";
 export * from "./ExclusiveMaximum";
 export * from "./ExclusiveMinimum";
 export * from "./Format";

test/schemas/json/v3_0/UltimateUnion.json

@@ -137,6 +137,15 @@
             "type": "boolean",
             "title": "Whether the type is deprecated or not",
             "description": "Whether the type is deprecated or not."
+          },
+          "example": {
+            "title": "Example value",
+            "description": "Example value."
+          },
+          "examples": {
+            "$ref": "#/components/schemas/Recordstringany",
+            "title": "List of example values as key-value pairs",
+            "description": "List of example values as key-value pairs."
           }
         },
         "nullable": false,
@@ -145,6 +154,13 @@
         ],
         "description": "Constant value type."
       },
+      "Recordstringany": {
+        "type": "object",
+        "properties": {},
+        "nullable": false,
+        "description": "Construct a type with a set of properties K of type T",
+        "additionalProperties": {}
+      },
       "OpenApi.IJsonSchema.IBoolean": {
         "type": "object",
         "properties": {
@@ -175,6 +191,15 @@
             "type": "boolean",
             "title": "Whether the type is deprecated or not",
             "description": "Whether the type is deprecated or not."
+          },
+          "example": {
+            "title": "Example value",
+            "description": "Example value."
+          },
+          "examples": {
+            "$ref": "#/components/schemas/Recordstringany",
+            "title": "List of example values as key-value pairs",
+            "description": "List of example values as key-value pairs."
           }
         },
         "nullable": false,
@@ -240,6 +265,15 @@
             "type": "boolean",
             "title": "Whether the type is deprecated or not",
             "description": "Whether the type is deprecated or not."
+          },
+          "example": {
+            "title": "Example value",
+            "description": "Example value."
+          },
+          "examples": {
+            "$ref": "#/components/schemas/Recordstringany",
+            "title": "List of example values as key-value pairs",
+            "description": "List of example values as key-value pairs."
           }
         },
         "nullable": false,
@@ -305,6 +339,15 @@
             "type": "boolean",
             "title": "Whether the type is deprecated or not",
             "description": "Whether the type is deprecated or not."
+          },
+          "example": {
+            "title": "Example value",
+            "description": "Example value."
+          },
+          "examples": {
+            "$ref": "#/components/schemas/Recordstringany",
+            "title": "List of example values as key-value pairs",
+            "description": "List of example values as key-value pairs."
           }
         },
         "nullable": false,
@@ -368,6 +411,15 @@
             "type": "boolean",
             "title": "Whether the type is deprecated or not",
             "description": "Whether the type is deprecated or not."
+          },
+          "example": {
+            "title": "Example value",
+            "description": "Example value."
+          },
+          "examples": {
+            "$ref": "#/components/schemas/Recordstringany",
+            "title": "List of example values as key-value pairs",
+            "description": "List of example values as key-value pairs."
           }
         },
         "nullable": false,
@@ -421,6 +473,15 @@
             "type": "boolean",
             "title": "Whether the type is deprecated or not",
             "description": "Whether the type is deprecated or not."
+          },
+          "example": {
+            "title": "Example value",
+            "description": "Example value."
+          },
+          "examples": {
+            "$ref": "#/components/schemas/Recordstringany",
+            "title": "List of example values as key-value pairs",
+            "description": "List of example values as key-value pairs."
           }
         },
         "nullable": false,
@@ -523,6 +584,15 @@
             "type": "boolean",
             "title": "Whether the type is deprecated or not",
             "description": "Whether the type is deprecated or not."
+          },
+          "example": {
+            "title": "Example value",
+            "description": "Example value."
+          },
+          "examples": {
+            "$ref": "#/components/schemas/Recordstringany",
+            "title": "List of example values as key-value pairs",
+            "description": "List of example values as key-value pairs."
           }
         },
         "nullable": false,
@@ -615,6 +685,15 @@
             "type": "boolean",
             "title": "Whether the type is deprecated or not",
             "description": "Whether the type is deprecated or not."
+          },
+          "example": {
+            "title": "Example value",
+            "description": "Example value."
+          },
+          "examples": {
+            "$ref": "#/components/schemas/Recordstringany",
+            "title": "List of example values as key-value pairs",
+            "description": "List of example values as key-value pairs."
           }
         },
         "nullable": false,
@@ -645,6 +724,15 @@
             "type": "boolean",
             "title": "Whether the type is deprecated or not",
             "description": "Whether the type is deprecated or not."
+          },
+          "example": {
+            "title": "Example value",
+            "description": "Example value."
+          },
+          "examples": {
+            "$ref": "#/components/schemas/Recordstringany",
+            "title": "List of example values as key-value pairs",
+            "description": "List of example values as key-value pairs."
           }
         },
         "nullable": false,
@@ -717,6 +805,15 @@
             "type": "boolean",
             "title": "Whether the type is deprecated or not",
             "description": "Whether the type is deprecated or not."
+          },
+          "example": {
+            "title": "Example value",
+            "description": "Example value."
+          },
+          "examples": {
+            "$ref": "#/components/schemas/Recordstringany",
+            "title": "List of example values as key-value pairs",
+            "description": "List of example values as key-value pairs."
           }
         },
         "nullable": false,
@@ -755,6 +852,15 @@
             "type": "boolean",
             "title": "Whether the type is deprecated or not",
             "description": "Whether the type is deprecated or not."
+          },
+          "example": {
+            "title": "Example value",
+            "description": "Example value."
+          },
+          "examples": {
+            "$ref": "#/components/schemas/Recordstringany",
+            "title": "List of example values as key-value pairs",
+            "description": "List of example values as key-value pairs."
           }
         },
         "nullable": false,
@@ -780,6 +886,15 @@
             "type": "boolean",
             "title": "Whether the type is deprecated or not",
             "description": "Whether the type is deprecated or not."
+          },
+          "example": {
+            "title": "Example value",
+            "description": "Example value."
+          },
+          "examples": {
+            "$ref": "#/components/schemas/Recordstringany",
+            "title": "List of example values as key-value pairs",
+            "description": "List of example values as key-value pairs."
           }
         },
         "nullable": false,