Merge pull request #1182 from samchon/feature/enum

Close #1181: support enumeration level description comment in JSON schema.

benchmark/package.json

@@ -72,6 +72,6 @@
     "suppress-warnings": "^1.0.2",
     "tstl": "^3.0.0",
     "uuid": "^9.0.1",
-    "typia": "../typia-6.5.5.tgz"
+    "typia": "../typia-6.6.0.tgz"
   }
 }

debug/features/enum.ts

@@ -0,0 +1,39 @@
+import typia from "typia";
+
+import { TestValidator } from "./internal/TestValidator";
+
+const app = typia.json.application<[ConstEnum]>();
+console.log(app.components.schemas?.ConstEnum);
+
+TestValidator.equals("enum-description")(app.components.schemas?.ConstEnum)({
+  oneOf: [
+    {
+      const: 1,
+      title: "The value one",
+      description:
+        "The value one.\n\nThe value one defined in the constant enumeration.",
+    },
+    {
+      const: 2,
+      title: "The value two",
+      description:
+        "The value two.\n\nThe value two defined in the constant enumeration.",
+    },
+  ],
+});
+
+const enum ConstEnum {
+  /**
+   * The value one.
+   *
+   * The value one defined in the constant enumeration.
+   */
+  ONE = 1,
+
+  /**
+   * The value two.
+   *
+   * The value two defined in the constant enumeration.
+   */
+  TWO = 2,
+}

debug/features/internal/TestValidator.ts

@@ -0,0 +1,47 @@
+export namespace TestValidator {
+  export const equals =
+    (title: string, exception: (key: string) => boolean = () => false) =>
+    <T>(x: T) =>
+    (y: T) => {
+      const diff: string[] = json_equal_to(exception)(x)(y);
+      if (diff.length)
+        throw new Error(
+          `Bug on ${title}: found different values - [${diff.join(", ")}]`,
+        );
+    };
+}
+
+const json_equal_to =
+  (exception: (key: string) => boolean) =>
+  <T>(x: T) =>
+  (y: T): string[] => {
+    const container: string[] = [];
+    const iterate =
+      (accessor: string) =>
+      (x: any) =>
+      (y: any): void => {
+        if (typeof x !== typeof y) container.push(accessor);
+        else if (x instanceof Array)
+          if (!(y instanceof Array)) container.push(accessor);
+          else array(accessor)(x)(y);
+        else if (x instanceof Object) object(accessor)(x)(y);
+        else if (x !== y) container.push(accessor);
+      };
+    const array =
+      (accessor: string) =>
+      (x: any[]) =>
+      (y: any[]): void => {
+        if (x.length !== y.length) container.push(`${accessor}.length`);
+        x.forEach((xItem, i) => iterate(`${accessor}[${i}]`)(xItem)(y[i]));
+      };
+    const object =
+      (accessor: string) =>
+      (x: any) =>
+      (y: any): void =>
+        Object.keys(x)
+          .filter((key) => x[key] !== undefined && !exception(key))
+          .forEach((key) => iterate(`${accessor}.${key}`)(x[key])(y[key]));
+
+    iterate("")(x)(y);
+    return container;
+  };

debug/package.json

@@ -16,6 +16,6 @@
     "typescript": "^5.4.2"
   },
   "dependencies": {
-    "typia": "../typia-6.5.5.tgz"
+    "typia": "../typia-6.6.0-dev.20240727.tgz"
   }
 }

errors/package.json

@@ -32,6 +32,6 @@
     "typescript": "^5.3.2"
   },
   "dependencies": {
-    "typia": "../typia-6.5.5.tgz"
+    "typia": "../typia-6.6.0.tgz"
   }
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "typia",
-  "version": "6.5.5",
+  "version": "6.6.0",
   "description": "Superfast runtime validators with only one line",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",

packages/typescript-json/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typescript-json",
-  "version": "6.5.5",
+  "version": "6.6.0",
   "description": "Superfast runtime validators with only one line",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -63,7 +63,7 @@
   },
   "homepage": "https://typia.io",
   "dependencies": {
-    "typia": "6.5.5"
+    "typia": "6.6.0"
   },
   "peerDependencies": {
     "typescript": ">=4.8.0 <5.6.0"

src/factories/internal/metadata/iterate_metadata_constant.ts

@@ -6,6 +6,7 @@ import { MetadataConstantValue } from "../../../schemas/metadata/MetadataConstan
 
 import { ArrayUtil } from "../../../utils/ArrayUtil";
 
+import { CommentFactory } from "../../CommentFactory";
 import { MetadataFactory } from "../../MetadataFactory";
 
 export const iterate_metadata_constant =
@@ -15,6 +16,15 @@ export const iterate_metadata_constant =
     if (!options.constant) return false;
 
     const filter = (flag: ts.TypeFlags) => (type.getFlags() & flag) !== 0;
+    const comment = () => {
+      if (!filter(ts.TypeFlags.EnumLiteral)) return {};
+      return {
+        jsDocTags: type.symbol?.getJsDocTags(),
+        description: type.symbol
+          ? CommentFactory.description(type.symbol) ?? null
+          : undefined,
+      };
+    };
     if (type.isLiteral()) {
       const value: string | number | bigint =
         typeof type.value === "object"
@@ -34,11 +44,13 @@ export const iterate_metadata_constant =
         MetadataConstantValue.create({
           value,
           tags: [],
+          ...comment(),
         }),
         (a, b) => a.value === b.value,
       );
       return true;
     } else if (filter(ts.TypeFlags.BooleanLiteral)) {
+      comment();
       const value: boolean = checker.typeToString(type) === "true";
       const constant: MetadataConstant = ArrayUtil.take(
         meta.constants,
@@ -54,6 +66,7 @@ export const iterate_metadata_constant =
         MetadataConstantValue.create({
           value,
           tags: [],
+          ...comment(),
         }),
         (a, b) => a.value === b.value,
       );

src/programmers/internal/application_description.ts

@@ -1,11 +1,11 @@
 import { IJsDocTagInfo } from "../../module";
 
 export const application_description = (props: {
-  description: string | null | undefined;
-  jsDocTags: IJsDocTagInfo[];
+  description?: string | null | undefined;
+  jsDocTags?: IJsDocTagInfo[];
 }): string | undefined =>
   props.jsDocTags
-    .find((tag) => tag.name === "description")
+    ?.find((tag) => tag.name === "description")
     ?.text?.[0]?.text?.split("\r\n")
     .join("\n") ??
   props.description ??

src/programmers/internal/application_title.ts

@@ -0,0 +1,20 @@
+import { CommentFactory } from "../../factories/CommentFactory";
+
+import { IJsDocTagInfo } from "../../module";
+
+export const application_title = (schema: {
+  description?: string | null | undefined;
+  jsDocTags?: IJsDocTagInfo[] | undefined;
+}): string | undefined => {
+  const info: IJsDocTagInfo | undefined = schema.jsDocTags?.find(
+    (tag) => tag.name === "title",
+  );
+  if (info?.text?.length) return CommentFactory.merge(info.text);
+  else if (!schema.description?.length) return undefined;
+
+  const index: number = schema.description.indexOf("\n");
+  const top: string = (
+    index === -1 ? schema.description : schema.description.substring(0, index)
+  ).trim();
+  return top.endsWith(".") ? top.substring(0, top.length - 1) : undefined;
+};

src/programmers/internal/application_v31_alias.ts

@@ -1,11 +1,9 @@
 import { OpenApi } from "@samchon/openapi";
 
-import { CommentFactory } from "../../factories/CommentFactory";
-
-import { IJsDocTagInfo } from "../../schemas/metadata/IJsDocTagInfo";
 import { MetadataAlias } from "../../schemas/metadata/MetadataAlias";
 
 import { application_description } from "./application_description";
+import { application_title } from "./application_title";
 import { application_v31_object } from "./application_v31_object";
 import { application_v31_schema } from "./application_v31_schema";
 
@@ -33,14 +31,7 @@ export const application_v31_alias =
       )(components)({
         deprecated:
           alias.jsDocTags.some((tag) => tag.name === "deprecated") || undefined,
-        title: (() => {
-          const info: IJsDocTagInfo | undefined = alias.jsDocTags.find(
-            (tag) => tag.name === "title",
-          );
-          return info?.text?.length
-            ? CommentFactory.merge(info.text)
-            : undefined;
-        })(),
+        title: application_title(alias),
         description: application_description(alias),
       })(alias.value);
       if (schema !== null)

src/programmers/internal/application_v31_constant.ts

@@ -2,7 +2,9 @@ import { OpenApi } from "@samchon/openapi";
 
 import { MetadataConstant } from "../../schemas/metadata/MetadataConstant";
 
+import { application_description } from "./application_description";
 import { application_plugin } from "./application_plugin";
+import { application_title } from "./application_title";
 
 /**
  * @internal
@@ -15,6 +17,8 @@ export const application_v31_constant = (
       application_plugin(
         {
           const: value.value as boolean | number | string,
+          title: application_title(value),
+          description: application_description(value),
         } satisfies OpenApi.IJsonSchema.IConstant,
         value.tags ?? [],
       ),

src/programmers/internal/application_v31_object.ts

@@ -9,6 +9,7 @@ import { MetadataObject } from "../../schemas/metadata/MetadataObject";
 import { PatternUtil } from "../../utils/PatternUtil";
 
 import { application_description } from "./application_description";
+import { application_title } from "./application_title";
 import { application_v31_schema } from "./application_v31_schema";
 import { metadata_to_pattern } from "./metadata_to_pattern";
 
@@ -67,23 +68,7 @@ const create_object_schema =
         deprecated:
           property.jsDocTags.some((tag) => tag.name === "deprecated") ||
           undefined,
-        title: (() => {
-          const info: IJsDocTagInfo | undefined = property.jsDocTags.find(
-            (tag) => tag.name === "title",
-          );
-          if (info?.text?.length) return CommentFactory.merge(info.text);
-          else if (!property.description?.length) return undefined;
-
-          const index: number = property.description.indexOf("\n");
-          const top: string = (
-            index === -1
-              ? property.description
-              : property.description.substring(0, index)
-          ).trim();
-          return top.endsWith(".")
-            ? top.substring(0, top.length - 1)
-            : undefined;
-        })(),
+        title: application_title(property),
         description: application_description(property),
       })(property.value);
 

src/schemas/metadata/IMetadataConstantValue.ts

@@ -1,8 +1,11 @@
 import { Atomic } from "../../typings/Atomic";
 
+import { IJsDocTagInfo } from "./IJsDocTagInfo";
 import { IMetadataTypeTag } from "./IMetadataTypeTag";
 
 export interface IMetadataConstantValue<T extends Atomic.Type> {
   value: T;
   tags: IMetadataTypeTag[][] | undefined;
+  description?: string | null;
+  jsDocTags?: IJsDocTagInfo[];
 }

src/schemas/metadata/MetadataConstantValue.ts

@@ -1,16 +1,21 @@
 import { ClassProperties } from "../../typings/ClassProperties";
 
+import { IJsDocTagInfo } from "./IJsDocTagInfo";
 import { IMetadataConstantValue } from "./IMetadataConstantValue";
 import { IMetadataTypeTag } from "./IMetadataTypeTag";
 
 export class MetadataConstantValue {
   public readonly value: boolean | bigint | number | string;
   public tags: IMetadataTypeTag[][] | undefined;
+  public readonly description?: string | null;
+  public readonly jsDocTags?: IJsDocTagInfo[];
   private name_?: string;
 
   private constructor(props: ClassProperties<MetadataConstantValue>) {
     this.value = props.value;
     this.tags = props.tags;
+    this.description = props.description;
+    this.jsDocTags = props.jsDocTags;
   }
 
   public static create(

test-esm/package.json

@@ -36,6 +36,6 @@
     "typescript": "^5.4.5"
   },
   "dependencies": {
-    "typia": "../typia-6.5.5.tgz"
+    "typia": "../typia-6.6.0.tgz"
   }
 }

test/package.json

@@ -51,6 +51,6 @@
     "suppress-warnings": "^1.0.2",
     "tstl": "^3.0.0",
     "uuid": "^9.0.1",
-    "typia": "../typia-6.5.5.tgz"
+    "typia": "../typia-6.6.0.tgz"
   }
 }

test/schemas/json/v3_1/UltimateUnion.json

@@ -93,6 +93,7 @@
             "$ref": "#/components/schemas/OpenApi.IJsonSchema.IUnknown"
           }
         ],
+        "title": "Type schema info",
         "description": "Type schema info.\n\n`OpenApi.IJsonSchema` is a type schema info of the OpenAPI.\n\n`OpenApi.IJsonSchema` basically follows the JSON schema definition of\nOpenAPI v3.1, but a little bit shrinked to remove ambiguous and duplicated\nexpressions of OpenAPI v3.1 for the convenience and clarity.\n\n- Decompose mixed type: {@link OpenApiV3_1.IJsonSchema.IMixed}\n- Resolve nullable property: {@link OpenApiV3_1.IJsonSchema.__ISignificant.nullable}\n- Array type utilizes only single {@link OpenAPI.IJsonSchema.IArray.items}\n- Tuple type utilizes only {@link OpenApi.IJsonSchema.ITuple.prefixItems}\n- Merge {@link OpenApiV3_1.IJsonSchema.IAnyOf} to {@link OpenApi.IJsonSchema.IOneOf}\n- Merge {@link OpenApiV3_1.IJsonSchema.IRecursiveReference} to {@link OpenApi.IJsonSchema.IReference}\n- Merge {@link OpenApiV3_1.IJsonSchema.IAllOf} to {@link OpenApi.IJsonSchema.IObject}"
       },
       "OpenApi.IJsonSchema.IConstant": {
@@ -787,6 +788,7 @@
             "$ref": "#/components/schemas/OpenApi.ISecurityScheme.IOpenId"
           }
         ],
+        "title": "Security scheme of Swagger Documents",
         "description": "Security scheme of Swagger Documents.\n\n`OpenApi.ISecurityScheme` is a data structure representing content of\n`securitySchemes` in `swagger.json` file. It is composed with 5 types of\nsecurity schemes as an union type like below."
       },
       "OpenApi.ISecurityScheme.IApiKey": {

test/src/features/issues/test_issue_1179_tuple_type_in_dynamic_object.ts

@@ -1,10 +1,16 @@
 import typia from "typia";
 
 export const test_issue_1179_tuple_type_in_dynamic_object = (): void => {
-  new Array(100).forEach(() => {
-    const foo: Foo = typia.random<Foo>();
-    typia.assert(foo);
-  });
+  const foo: Foo = typia.random<Foo>();
+  typia.assert(foo);
+
+  const bar: Foo = {
+    paths: {
+      "/": ["home"],
+      "/about": ["about"],
+    },
+  };
+  typia.assert(bar);
 };
 
 interface Foo {