typia 7.0.0-dev.20241010 → 7.0.0-dev.20241011

package/src/json.ts

@@ -1,4 +1,5 @@
 import { IJsonApplication } from "./schemas/json/IJsonApplication";
+import { IJsonSchemaCollection } from "./schemas/json/IJsonSchemaList";
 
 import { IValidation } from "./IValidation";
 import { Primitive } from "./Primitive";
@@ -6,41 +7,86 @@ import { TypeGuardError } from "./TypeGuardError";
 
 /* ===========================================================
     JSON
-      - SCHEMA
+      - METADATA
       - PARSE
       - STRINGIFY
       - FACTORY FUNCTIONS
 ==============================================================
-    SCHEMA
+    METADATA
 ----------------------------------------------------------- */
+/**
+ * > You must configure the generic argument `App`.
+ *
+ * TypeScript functions to JSON schema based application schema.
+ *
+ * Creates an application schema collecting the functions' schema based on the
+ * JSON schema specification.
+ *
+ * The default version of the OpenAPI specification is `"3.1"`, but you can
+ * specify the version by configuring the second generic argument `Version`.
+ *
+ * @template App Target class or interface type collecting the functions
+ * @template Version Version of OpenAPI specification. Default is 3.1
+ * @returns Application schema of JSON schema based
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export function application(): never;
+
+/**
+ * TypeScript functions to JSON schema based application schema.
+ *
+ * Creates an application schema collecting the functions' schema based on the
+ * JSON schema specification.
+ *
+ * The default version of the OpenAPI specification is `"3.1"`, but you can
+ * specify the version by configuring the second generic argument `Version`.
+ *
+ * @template App Target class or interface type collecting the functions
+ * @template Version Version of OpenAPI specification. Default is 3.1
+ * @returns Application schema of JSON schema based
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export function application<
+  App extends object,
+  Version extends "3.0" | "3.1" = "3.1",
+>(): IJsonApplication<Version, App>;
+
+/**
+ * @internal
+ */
+export function application(): never {
+  halt("application");
+}
+
 /**
  * > You must configure the generic argument `Types`.
  *
- * JSON Schema Application.
+ * JSON Schema List.
  *
- * Creates a JSON schema application which contains both main JSON schemas and
- * components. Note that, all of the named types are stored in the
- * {@link IJsonApplication.components} property for the `$ref` referencing.
+ * Creates a JSON schema list which contains both main JSON schemas
+ * and components. Note that, all of the named types are stored in the
+ * {@link IJsonSchemaCollection.components} property for the `$ref` referencing.
  *
  * Also, you can specify the OpenAPI version by configuring the second generic
  * argument `Version`. For reference, the default version is `"3.1"`, and key
  * different of `"3.0"` and `"3.1"` is whether supporting the tuple type or not.
  *
  * @template Types Tuple of target types
- * @template Purpose Purpose of the JSON schema
- * @template Surplus Allow surplus properties starting with `x-typia-` or not
- * @return JSON schema application
+ * @template Version Version of OpenAPI specification. Default is 3.1
+ * @return JSON schema list
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function application(): never;
+export function schemas(): never;
 
 /**
  * JSON Schema Application.
  *
- * Creates a JSON schema application which contains both main JSON schemas and
- * components. Note that, all of the named types are stored in the
- * {@link IJsonApplication.components} property for the `$ref` referencing.
+ * Creates a JSON schema list which contains both main JSON schemas
+ * and components. Note that, all of the named types are stored in the
+ * {@link IJsonSchemaCollection.components} property for the `$ref` referencing.
  *
  * Also, you can specify the OpenAPI version by configuring the second generic
  * argument `Version`. For reference, the default version is `"3.1"`, and key
@@ -48,19 +94,19 @@ export function application(): never;
  *
  * @template Types Tuple of target types
  * @template Version Version of OpenAPI specification. Default is 3.1
- * @return JSON schema application
+ * @return JSON schema list
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function application<
+export function schemas<
   Types extends unknown[],
   Version extends "3.0" | "3.1" = "3.1",
->(): IJsonApplication<Version, Types>;
+>(): IJsonSchemaCollection<Version, Types>;
 
 /**
  * @internal
  */
-export function application(): never {
+export function schemas(): never {
   halt("application");
 }
 

package/src/module.ts

@@ -16,6 +16,7 @@ export * as tags from "./tags";
 
 export * from "./schemas/metadata/IJsDocTagInfo";
 export * from "./schemas/json/IJsonApplication";
+export * from "./schemas/json/IJsonSchemaList";
 export * from "./AssertionGuard";
 export * from "./IRandomGenerator";
 export * from "./IValidation";

package/src/programmers/json/JsonApplicationProgrammer.ts

@@ -1,92 +1,269 @@
-import { OpenApi, OpenApiV3 } from "@samchon/openapi";
+import { MetadataFactory } from "../../factories/MetadataFactory";
 
 import { IJsonApplication } from "../../schemas/json/IJsonApplication";
 import { Metadata } from "../../schemas/metadata/Metadata";
+import { MetadataFunction } from "../../schemas/metadata/MetadataFunction";
+import { MetadataObject } from "../../schemas/metadata/MetadataObject";
 
-import { TransformerError } from "../../transformers/TransformerError";
-
-import { AtomicPredicator } from "../helpers/AtomicPredicator";
-import { application_v30_schema } from "../internal/application_v30_schema";
-import { application_v31_schema } from "../internal/application_v31_schema";
+import { IJsDocTagInfo } from "../../module";
+import { JsonSchemasProgrammer } from "./JsonSchemasProgrammer";
 
 export namespace JsonApplicationProgrammer {
-  export const validate = (meta: Metadata): string[] => {
+  export const validate = (
+    metadata: Metadata,
+    explore: MetadataFactory.IExplore,
+  ): string[] => {
+    if (explore.top === false) return JsonSchemasProgrammer.validate(metadata);
+
     const output: string[] = [];
-    if (
-      meta.atomics.some((a) => a.type === "bigint") ||
-      meta.constants.some((c) => c.type === "bigint")
-    )
-      output.push("JSON schema does not support bigint type.");
-    if (
-      meta.tuples.some((t) =>
-        t.type.elements.some((e) => e.isRequired() === false),
-      ) ||
-      meta.arrays.some((a) => a.type.value.isRequired() === false)
-    )
-      output.push("JSON schema does not support undefined type in array.");
-    if (meta.maps.length) output.push("JSON schema does not support Map type.");
-    if (meta.sets.length) output.push("JSON schema does not support Set type.");
-    for (const native of meta.natives)
-      if (
-        AtomicPredicator.native(native) === false &&
-        native !== "Date" &&
-        native !== "Blob" &&
-        native !== "File"
-      )
-        output.push(`JSON schema does not support ${native} type.`);
+    const valid: boolean =
+      metadata.size() === 1 &&
+      metadata.objects.length === 1 &&
+      metadata.isRequired() === true &&
+      metadata.nullable === false;
+    if (valid === false)
+      output.push(
+        "JSON application's generic arugment must be a class/interface type.",
+      );
+
+    const object: MetadataObject | undefined = metadata.objects[0];
+    if (object !== undefined) {
+      if (object.properties.some((p) => p.key.isSoleLiteral() === false))
+        output.push("JSON application does not allow dynamic keys.");
+      let least: boolean = false;
+      for (const p of object.properties) {
+        const value: Metadata = p.value;
+        if (value.functions.length) {
+          least ||= true;
+          if (valid === false) {
+            if (value.functions.length !== 1 || value.size() !== 1)
+              output.push(
+                "JSON application's function type does not allow union type.",
+              );
+            if (value.isRequired() === false)
+              output.push("JSON application's function type must be required.");
+            if (value.nullable === true)
+              output.push(
+                "JSON application's function type must not be nullable.",
+              );
+          }
+        }
+      }
+      if (least === false)
+        output.push(
+          "JSON application's target type must have at least a function type.",
+        );
+    }
     return output;
   };
 
-  export const write = <Version extends "3.0" | "3.1">(version: Version) =>
-    version === "3.0" ? v30 : v31;
+  export const write = <Version extends "3.0" | "3.1">(props: {
+    version: Version;
+    metadata: Metadata;
+  }): IJsonApplication<Version> => {
+    const errors: string[] = validate(props.metadata, {
+      top: true,
+      object: null,
+      property: null,
+      parameter: null,
+      nested: null,
+      aliased: false,
+      escaped: false,
+      output: false,
+    });
+    if (errors.length)
+      throw new Error("Failed to write LLM application: " + errors.join("\n"));
+
+    const object: MetadataObject = props.metadata.objects[0]!;
+    const definitions: Metadata[] = [];
+    const setters: Array<(schema: IJsonApplication.Schema<Version>) => void> =
+      [];
+    const collect = (
+      metadata: Metadata,
+      setter: (schema: IJsonApplication.Schema<Version>) => void,
+    ): void => {
+      definitions.push(metadata);
+      setters.push(setter);
+    };
 
-  const v30 = (metadatas: Array<Metadata>): IJsonApplication<"3.0"> => {
-    const components: OpenApiV3.IComponents = {};
-    const generator = (meta: Metadata): OpenApiV3.IJsonSchema | null =>
-      application_v30_schema({
-        blockNever: true,
-        components,
-        attribute: {},
-        metadata: meta,
-      });
+    const functions: IJsonApplication.IFunction<
+      IJsonApplication.Schema<Version>
+    >[] = object.properties
+      .filter(
+        (p) =>
+          p.key.isSoleLiteral() &&
+          p.value.size() === 1 &&
+          p.value.nullable === false &&
+          p.value.isRequired() === true &&
+          p.value.functions.length === 1,
+      )
+      .map((r) =>
+        collectFunction({
+          version: props.version,
+          name: r.key.getSoleLiteral()!,
+          function: r.value.functions[0]!,
+          description: r.description,
+          jsDocTags: r.jsDocTags,
+          collect,
+        }),
+      );
+    const { components, schemas } = JsonSchemasProgrammer.write(props.version)(
+      definitions,
+    );
+    schemas.forEach((s, i) =>
+      setters[i]?.(s as IJsonApplication.Schema<Version>),
+    );
     return {
-      version: "3.0",
-      components,
-      schemas: metadatas.map((meta, i) => {
-        const schema: OpenApiV3.IJsonSchema | null = generator(meta);
-        if (schema === null)
-          throw new TransformerError({
-            code: "typia.json.application",
-            message: `invalid type on argument - (${meta.getName()}, ${i})`,
-          });
-        return schema;
-      }),
+      version: props.version,
+      components: components as any,
+      functions,
     };
   };
 
-  const v31 = (metadatas: Array<Metadata>): IJsonApplication<"3.1"> => {
-    const components: OpenApi.IComponents = {
-      schemas: {},
-    };
-    const generator = (meta: Metadata): OpenApi.IJsonSchema | null =>
-      application_v31_schema({
-        blockNever: true,
-        components,
-        attribute: {},
-        metadata: meta,
-      });
+  const collectFunction = <Version extends "3.0" | "3.1">(props: {
+    version: Version;
+    name: string;
+    function: MetadataFunction;
+    description: string | null;
+    jsDocTags: IJsDocTagInfo[];
+    collect: (
+      metadata: Metadata,
+      setter: (schema: IJsonApplication.Schema<Version>) => void,
+    ) => void;
+  }): IJsonApplication.IFunction<IJsonApplication.Schema<Version>> => {
+    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 {
-      version: "3.1",
-      components,
-      schemas: metadatas.map((meta, i) => {
-        const schema: OpenApi.IJsonSchema | null = generator(meta);
-        if (schema === null)
-          throw new TransformerError({
-            code: "typia.json.application",
-            message: `invalid type on argument - (${meta.getName()}, ${i})`,
-          });
-        return schema;
+      name: props.name,
+      async: props.function.async,
+      parameters: props.function.parameters.map((param) => {
+        const appParam: IJsonApplication.IParameter<
+          IJsonApplication.Schema<Version>
+        > = {
+          name: param.name,
+          ...writeDescription({
+            description:
+              param.description ??
+              param.jsDocTags.find((tag) => tag.name === "description")
+                ?.text?.[0]?.text ??
+              props.jsDocTags
+                .find(
+                  (tag) =>
+                    tag.name === "param" && tag.text?.[0]?.text === param.name,
+                )
+                ?.text?.map((e) => e.text)
+                .join("")
+                .substring(param.name.length) ??
+              null,
+            jsDocTags: props.jsDocTags,
+            kind: "title",
+          }),
+          required: param.type.isRequired(),
+          schema: null!,
+        };
+        props.collect(param.type, (schema) => (appParam.schema = schema));
+        return appParam;
       }),
+      output: props.function.output.size()
+        ? (() => {
+            const appOutput: IJsonApplication.IOutput<
+              IJsonApplication.Schema<Version>
+            > = {
+              schema: null!,
+              required: props.function.output.isRequired(),
+              description:
+                writeDescriptionFromJsDocTag({
+                  jsDocTags: props.jsDocTags,
+                  name: "return",
+                }) ??
+                writeDescriptionFromJsDocTag({
+                  jsDocTags: props.jsDocTags,
+                  name: "returns",
+                }) ??
+                undefined,
+            };
+            props.collect(
+              props.function.output,
+              (schema) => (appOutput.schema = schema),
+            );
+            return appOutput;
+          })()
+        : undefined,
+      description: props.description ?? undefined,
+      deprecated: deprecated || undefined,
+      tags: tags.length ? tags : undefined,
     };
   };
 }
+
+const writeDescription = <Kind extends "summary" | "title">(props: {
+  description: string | null;
+  jsDocTags: IJsDocTagInfo[];
+  kind: Kind;
+}): Kind extends "summary"
+  ? { summary?: string; description?: string }
+  : { title?: string; description?: string } => {
+  const title: string | undefined = (() => {
+    const [explicit] = getJsDocTexts({
+      jsDocTags: props.jsDocTags,
+      name: props.kind,
+    });
+    if (explicit?.length) return explicit;
+    else if (!props.description?.length) return undefined;
+
+    const index: number = props.description.indexOf("\n");
+    const top: string = (
+      index === -1 ? props.description : props.description.substring(0, index)
+    ).trim();
+    return top.endsWith(".") ? top.substring(0, top.length - 1) : undefined;
+  })();
+  return {
+    [props.kind]: title,
+    description: props.description?.length ? props.description : undefined,
+  } as any;
+};
+
+const writeDescriptionFromJsDocTag = (props: {
+  jsDocTags: IJsDocTagInfo[];
+  name: string;
+  parameter?: string;
+}): string | null => {
+  const parametric: (elem: IJsDocTagInfo) => boolean = props.parameter
+    ? (tag) =>
+        tag.text!.find(
+          (elem) =>
+            elem.kind === "parameterName" && elem.text === props.parameter,
+        ) !== undefined
+    : () => true;
+  const tag: IJsDocTagInfo | undefined = props.jsDocTags.find(
+    (tag) => tag.name === props.name && tag.text && parametric(tag),
+  );
+  return tag && tag.text
+    ? (tag.text.find((elem) => elem.kind === "text")?.text ?? null)
+    : null;
+};
+
+const getJsDocTexts = (props: {
+  jsDocTags: IJsDocTagInfo[];
+  name: string;
+}): string[] =>
+  props.jsDocTags
+    .filter(
+      (tag) =>
+        tag.name === props.name &&
+        tag.text &&
+        tag.text.find((elem) => elem.kind === "text" && elem.text.length) !==
+          undefined,
+    )
+    .map((tag) => tag.text!.find((elem) => elem.kind === "text")!.text);

package/src/programmers/json/JsonSchemasProgrammer.ts

@@ -0,0 +1,94 @@
+import { OpenApi, OpenApiV3 } from "@samchon/openapi";
+
+import { IJsonSchemaCollection } from "../../schemas/json/IJsonSchemaList";
+import { Metadata } from "../../schemas/metadata/Metadata";
+
+import { TransformerError } from "../../transformers/TransformerError";
+
+import { AtomicPredicator } from "../helpers/AtomicPredicator";
+import { application_v30_schema } from "../internal/application_v30_schema";
+import { application_v31_schema } from "../internal/application_v31_schema";
+
+export namespace JsonSchemasProgrammer {
+  export const validate = (metadata: Metadata): string[] => {
+    const output: string[] = [];
+    if (
+      metadata.atomics.some((a) => a.type === "bigint") ||
+      metadata.constants.some((c) => c.type === "bigint")
+    )
+      output.push("JSON schema does not support bigint type.");
+    if (
+      metadata.tuples.some((t) =>
+        t.type.elements.some((e) => e.isRequired() === false),
+      ) ||
+      metadata.arrays.some((a) => a.type.value.isRequired() === false)
+    )
+      output.push("JSON schema does not support undefined type in array.");
+    if (metadata.maps.length)
+      output.push("JSON schema does not support Map type.");
+    if (metadata.sets.length)
+      output.push("JSON schema does not support Set type.");
+    for (const native of metadata.natives)
+      if (
+        AtomicPredicator.native(native) === false &&
+        native !== "Date" &&
+        native !== "Blob" &&
+        native !== "File"
+      )
+        output.push(`JSON schema does not support ${native} type.`);
+    return output;
+  };
+
+  export const write = <Version extends "3.0" | "3.1">(version: Version) =>
+    version === "3.0" ? v30 : v31;
+
+  const v30 = (medadataList: Array<Metadata>): IJsonSchemaCollection<"3.0"> => {
+    const components: OpenApiV3.IComponents = {};
+    const generator = (metadata: Metadata): OpenApiV3.IJsonSchema | null =>
+      application_v30_schema({
+        blockNever: true,
+        components,
+        attribute: {},
+        metadata,
+      });
+    return {
+      version: "3.0",
+      components,
+      schemas: medadataList.map((meta, i) => {
+        const schema: OpenApiV3.IJsonSchema | null = generator(meta);
+        if (schema === null)
+          throw new TransformerError({
+            code: "typia.json.application",
+            message: `invalid type on argument - (${meta.getName()}, ${i})`,
+          });
+        return schema;
+      }),
+    };
+  };
+
+  const v31 = (metadataList: Array<Metadata>): IJsonSchemaCollection<"3.1"> => {
+    const components: OpenApi.IComponents = {
+      schemas: {},
+    };
+    const generator = (metadata: Metadata): OpenApi.IJsonSchema | null =>
+      application_v31_schema({
+        blockNever: true,
+        components,
+        attribute: {},
+        metadata,
+      });
+    return {
+      version: "3.1",
+      components,
+      schemas: metadataList.map((meta, i) => {
+        const schema: OpenApi.IJsonSchema | null = generator(meta);
+        if (schema === null)
+          throw new TransformerError({
+            code: "typia.json.application",
+            message: `invalid type on argument - (${meta.getName()}, ${i})`,
+          });
+        return schema;
+      }),
+    };
+  };
+}