typia 5.3.7 → 5.3.8-dev.20240104

package/src/json.ts

@@ -20,19 +20,23 @@ import { Primitive } from "./Primitive";
  * JSON Schema Application.
  *
  * Creates a JSON schema application which contains both main JSON schemas and
- * components. Note that, all of the object types are stored in the
+ * components. Note that, all of the named types are stored in the
  * {@link IJsonApplication.components} property for the `$ref` referencing.
  *
- * Also, `typia.json.application()` has additional generic arguments, *Purpose*.
- * As JSON schema definitions used by `swagger` and `ajv` are different a little bit,
- * you should configure the *Purpose* appropriately.
+ * Also, `typia.json.application()` has two additional generic arguments.
  *
- * For an example, `ajv` has an extra property "$recursiveRef" that are not exists
- * in the standard JSON schema definition spec. Otherwise, `swagger` can't identify
- * the tuple definition.
+ * The 1st *Purpose* means the purpose determines the JSON schema definition spec.
+ * For an example, `ajv` has an extra property "$recursiveRef"  that are not
+ * exists in the standard JSON schema definition spec. Otherwise, `swagger`
+ * can't identify the tuple definition.
+ *
+ * The next *Surplus* means whether to allow surplus properties starting with
+ * `x-typia-` or not. If `true`, the surplus properties like `x-typia-jsDocTags`
+ * would be registered into the JSON schema, otherwise, not.
  *
  * @template Types Tuple of target types
- * @template Purpose Purpose of the JSON schema`
+ * @template Purpose Purpose of the JSON schema
+ * @template Surplus Allow surplus properties starting with `x-typia-` or not
  * @return JSON schema application
  *
  * @author Jeongho Nam - https://github.com/samchon
@@ -43,19 +47,23 @@ export function application(): never;
  * JSON Schema Application.
  *
  * Creates a JSON schema application which contains both main JSON schemas and
- * components. Note that, all of the object types are stored in the
+ * components. Note that, all of the named types are stored in the
  * {@link IJsonApplication.components} property for the `$ref` referencing.
  *
- * Also, `typia.json.application()` has additional generic arguments, *Purpose*.
- * As JSON schema definitions used by `swagger` and `ajv` are different a little bit,
- * you should configure the *Purpose* appropriately.
+ * Also, `typia.json.application()` has two additional generic arguments.
+ *
+ * The 1st *Purpose* means the purpose determines the JSON schema definition spec.
+ * For an example, `ajv` has an extra property "$recursiveRef"  that are not
+ * exists in the standard JSON schema definition spec. Otherwise, `swagger`
+ * can't identify the tuple definition.
  *
- * For an example, `ajv` has an extra property "$recursiveRef" that are not exists
- * in the standard JSON schema definition spec. Otherwise, `swagger` can't identify
- * the tuple definition.
+ * The next *Surplus* means whether to allow surplus properties starting with
+ * `x-typia-` or not. If `true`, the surplus properties like `x-typia-jsDocTags`
+ * would be registered into the JSON schema, otherwise, 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
  *
  * @author Jeongho Nam - https://github.com/samchon
@@ -63,6 +71,7 @@ export function application(): never;
 export function application<
   Types extends unknown[],
   Purpose extends "ajv" | "swagger" = "swagger",
+  Surplus extends boolean = false,
 >(): IJsonApplication;
 
 /**

package/src/programmers/internal/application_array.ts

@@ -12,14 +12,12 @@ import { application_schema } from "./application_schema";
 export const application_array =
   (options: JsonApplicationProgrammer.IOptions) =>
   (components: IJsonComponents) =>
-  (array: MetadataArray) =>
-  (attribute: IJsonSchema.IAttribute): IJsonSchema.IArray[] => {
+  (array: MetadataArray): IJsonSchema.IArray[] => {
     // BASE SCHEMA
     const items: IJsonSchema = application_schema(options)(false)(components)(
       array.type.value,
-    )(attribute);
+    )({});
     const base: IJsonSchema.IArray = {
-      ...attribute,
       type: "array",
       items: null!,
     };
@@ -31,7 +29,7 @@ export const application_array =
 
     // CONSIDER TYPE TAGS
     const union: IJsonSchema.IArray[] = array.tags.map(
-      (row) => application_array_tags({ ...base })(row)!,
+      (row) => application_array_tags(options)({ ...base })(row)!,
     );
     const map: Map<string, IJsonSchema.IArray> = new Map(
       union.map((u) => [JSON.stringify(u), u]),
@@ -40,6 +38,7 @@ export const application_array =
   };
 
 const application_array_tags =
+  (options: JsonApplicationProgrammer.IOptions) =>
   (schema: IJsonSchema.IArray) =>
   (row: IMetadataTypeTag[]): IJsonSchema.IArray => {
     for (const tag of row.slice().sort((a, b) => a.kind.localeCompare(b.kind)))
@@ -47,13 +46,14 @@ const application_array_tags =
         schema.minItems = tag.value;
       else if (tag.kind === "maxItems" && typeof tag.value === "number")
         schema.maxItems = tag.value;
-    schema["x-typia-typeTags"] = row.map((tag) => ({
-      target: tag.target,
-      name: tag.name,
-      kind: tag.kind,
-      value: tag.value,
-      validate: tag.validate,
-      exclusive: tag.exclusive,
-    }));
+    if (options.surplus)
+      schema["x-typia-typeTags"] = row.map((tag) => ({
+        target: tag.target,
+        name: tag.name,
+        kind: tag.kind,
+        value: tag.value,
+        validate: tag.validate,
+        exclusive: tag.exclusive,
+      }));
     return schema;
   };

package/src/programmers/internal/application_boolean.ts

@@ -2,16 +2,17 @@ import { IMetadataTypeTag } from "../../schemas/metadata/IMetadataTypeTag";
 import { MetadataAtomic } from "../../schemas/metadata/MetadataAtomic";
 
 import { IJsonSchema } from "../../module";
+import { JsonApplicationProgrammer } from "../json/JsonApplicationProgrammer";
 import { application_default } from "./application_default";
 
 /**
  * @internal
  */
 export const application_boolean =
+  (options: JsonApplicationProgrammer.IOptions) =>
   (atomic: MetadataAtomic) =>
   (attribute: IJsonSchema.IAttribute): IJsonSchema.IBoolean[] => {
     const base: IJsonSchema.IBoolean = {
-      ...attribute,
       default: application_default(attribute)(
         (alias) => alias === "true" || alias === "false",
       )((str) => Boolean(str)),
@@ -25,6 +26,10 @@ export const application_boolean =
     return defaultTags.map((tag) => ({
       ...base,
       default: tag.value,
-      "x-typia-typeTags": defaultTags,
+      ...(options.surplus
+        ? {
+            "x-typia-typeTags": defaultTags,
+          }
+        : {}),
     }));
   };

package/src/programmers/internal/application_constant.ts

@@ -9,7 +9,6 @@ import { application_default } from "./application_default";
 export const application_constant =
   (constant: MetadataConstant) =>
   (attribute: IJsonSchema.IAttribute): IJsonSchema.IEnumeration<any> => ({
-    ...attribute,
     type: constant.type,
     enum: constant.values as any,
     default: application_default(attribute)((alias) =>

package/src/programmers/internal/application_escaped.ts

@@ -9,11 +9,10 @@ export const application_escaped =
   (options: JsonApplicationProgrammer.IOptions) =>
   <BlockNever extends boolean>(blockNever: BlockNever) =>
   (components: IJsonComponents) =>
-  (resolved: MetadataEscaped) =>
-  (attribute: IJsonSchema.IAttribute): IJsonSchema[] => {
+  (resolved: MetadataEscaped): IJsonSchema[] => {
     const output = application_schema(options)(blockNever)(components)(
       resolved.returns,
-    )(attribute);
+    )({});
     if (output === null) return [];
 
     if (is_date(new Set())(resolved.original)) {

package/src/programmers/internal/application_native.ts

@@ -11,14 +11,11 @@ export const application_native =
   (options: JsonApplicationProgrammer.IOptions) =>
   (components: IJsonComponents) =>
   (name: string) =>
-  (props: {
-    nullable: boolean;
-    attribute: IJsonSchema.IAttribute;
-  }): IJsonSchema.IReference => {
+  (nullable: boolean): IJsonSchema.IReference => {
     const key: string =
       options.purpose === "ajv"
         ? name
-        : `${name}${props.nullable ? ".Nullable" : ""}`;
+        : `${name}${nullable ? ".Nullable" : ""}`;
     if (components.schemas?.[key] === undefined) {
       components.schemas ??= {};
       components.schemas[key] ??= {
@@ -28,11 +25,10 @@ export const application_native =
             ? `${JSON_COMPONENTS_PREFIX}/objects/${key}`
             : undefined,
         properties: {},
-        nullable: options.purpose === "swagger" ? props.nullable : undefined,
+        nullable: options.purpose === "swagger" ? nullable : undefined,
       };
     }
     return {
-      ...props.attribute,
       $ref: `${JSON_COMPONENTS_PREFIX}/objects/${key}`,
     };
   };

package/src/programmers/internal/application_number.ts

@@ -2,6 +2,7 @@ import { IMetadataTypeTag } from "../../schemas/metadata/IMetadataTypeTag";
 import { MetadataAtomic } from "../../schemas/metadata/MetadataAtomic";
 
 import { IJsonSchema } from "../../module";
+import { JsonApplicationProgrammer } from "../json/JsonApplicationProgrammer";
 import { application_default } from "./application_default";
 
 type Schema = IJsonSchema.INumber | IJsonSchema.IInteger;
@@ -10,11 +11,11 @@ type Schema = IJsonSchema.INumber | IJsonSchema.IInteger;
  * @internal
  */
 export const application_number =
+  (options: JsonApplicationProgrammer.IOptions) =>
   (atomic: MetadataAtomic) =>
   (attribute: IJsonSchema.IAttribute): Array<Schema> => {
     // BASE CONFIGURATION
     const base: Schema = {
-      ...attribute,
       type: "number",
     };
     const out = (schema: Schema) => {
@@ -39,7 +40,7 @@ export const application_number =
 
     // CONSIDER TYPE TAGS
     const union: Schema[] = atomic.tags.map(
-      (row) => application_number_tags({ ...base })(row)!,
+      (row) => application_number_tags(options)({ ...base })(row)!,
     );
     const map: Map<string, Schema> = new Map(
       union.map((u) => [JSON.stringify(u), u]),
@@ -48,6 +49,7 @@ export const application_number =
   };
 
 const application_number_tags =
+  (options: JsonApplicationProgrammer.IOptions) =>
   (base: Schema) =>
   (row: IMetadataTypeTag[]): Schema => {
     for (const tag of row
@@ -82,13 +84,14 @@ const application_number_tags =
       else if (tag.kind === "default" && typeof tag.value === "number")
         base.default = tag.value;
     }
-    base["x-typia-typeTags"] = row.map((tag) => ({
-      target: tag.target,
-      name: tag.name,
-      kind: tag.kind,
-      value: tag.value,
-      validate: tag.validate,
-      exclusive: tag.exclusive,
-    }));
+    if (options.surplus)
+      base["x-typia-typeTags"] = row.map((tag) => ({
+        target: tag.target,
+        name: tag.name,
+        kind: tag.kind,
+        value: tag.value,
+        validate: tag.validate,
+        exclusive: tag.exclusive,
+      }));
     return base;
   };

package/src/programmers/internal/application_object.ts

@@ -84,11 +84,15 @@ const create_object_schema =
             : undefined;
         })(),
         description: property.description ?? undefined,
-        "x-typia-jsDocTags": property.jsDocTags.length
-          ? property.jsDocTags
-          : undefined,
-        "x-typia-required": property.value.required,
-        "x-typia-optional": property.value.optional,
+        ...(options.surplus
+          ? {
+              "x-typia-jsDocTags": property.jsDocTags.length
+                ? property.jsDocTags
+                : undefined,
+              "x-typia-required": property.value.required,
+              "x-typia-optional": property.value.optional,
+            }
+          : {}),
       });
 
       if (schema === null) continue;
@@ -125,12 +129,14 @@ const create_object_schema =
       "x-typia-jsDocTags": obj.jsDocTags,
       ...(options.purpose === "ajv"
         ? extraProps
-        : {
+        : options.surplus
+        ? {
             // swagger can't express patternProperties
             "x-typia-additionalProperties": extraProps.additionalProperties,
             "x-typia-patternProperties": extraProps.patternProperties,
             additionalProperties: join(options)(components)(extraMeta),
-          }),
+          }
+        : {}),
     };
   };
 
@@ -153,9 +159,13 @@ const join =
       .map((tuple) => tuple[0])
       .reduce((x, y) => Metadata.merge(x, y));
     return (
-      application_schema(options)(true)(components)(meta)({
-        "x-typia-required": false,
-      }) ?? undefined
+      application_schema(options)(true)(components)(meta)(
+        options.surplus
+          ? {
+              "x-typia-required": false,
+            }
+          : {},
+      ) ?? undefined
     );
   };
 

package/src/programmers/internal/application_schema.ts

@@ -49,10 +49,10 @@ export const application_schema =
 
     const insert =
       meta.nullable && options.purpose === "swagger"
-        ? (s: IJsonSchema) =>
+        ? (schema: IJsonSchema) =>
             union.push({
-              ...s,
-              nullable: (s as IJsonSchema.ISignificant<any>).type
+              ...schema,
+              nullable: (schema as IJsonSchema.ISignificant<any>).type
                 ? true
                 : undefined,
             } as IJsonSchema)
@@ -61,9 +61,7 @@ export const application_schema =
     // toJSON() METHOD
     if (meta.escaped !== null)
       union.push(
-        ...application_escaped(options)(blockNever)(components)(meta.escaped)(
-          attribute,
-        ),
+        ...application_escaped(options)(blockNever)(components)(meta.escaped),
       );
 
     // ATOMIC TYPES
@@ -80,17 +78,15 @@ export const application_schema =
     for (const a of meta.atomics)
       if (a.type === "bigint") throw new TypeError(NO_BIGINT);
       else if (a.type === "boolean")
-        application_boolean(a)(attribute).forEach(insert);
+        application_boolean(options)(a)(attribute).forEach(insert);
       else if (a.type === "number")
-        application_number(a)(attribute).forEach(insert);
+        application_number(options)(a)(attribute).forEach(insert);
       else if (a.type === "string")
-        application_string(meta)(a)(attribute).forEach(insert);
+        application_string(options)(meta)(a)(attribute).forEach(insert);
 
     // ARRAY
     for (const array of meta.arrays)
-      application_array(options)(components)(array)(attribute).forEach((s) =>
-        insert(s),
-      );
+      application_array(options)(components)(array).forEach(insert);
 
     // TUPLE
     for (const tuple of meta.tuples)
@@ -104,7 +100,7 @@ export const application_schema =
         else if (type === "bigint") throw new TypeError(NO_BIGINT);
         else if (type === "boolean")
           insert(
-            application_boolean(
+            application_boolean(options)(
               MetadataAtomic.create({
                 type: "boolean",
                 tags: [],
@@ -113,7 +109,7 @@ export const application_schema =
           );
         else if (type === "number")
           insert(
-            application_number(
+            application_number(options)(
               MetadataAtomic.create({
                 type: "number",
                 tags: [],
@@ -122,7 +118,7 @@ export const application_schema =
           );
         else if (type === "string")
           insert(
-            application_string(meta)(
+            application_string(options)(meta)(
               MetadataAtomic.create({
                 type: "string",
                 tags: [],
@@ -130,26 +126,11 @@ export const application_schema =
             )(attribute)[0]!,
           );
       } else
-        insert(
-          application_native(options)(components)(native)({
-            nullable: meta.nullable,
-            attribute,
-          }),
-        );
+        insert(application_native(options)(components)(native)(meta.nullable));
     if (meta.sets.length)
-      insert(
-        application_native(options)(components)(`Set`)({
-          nullable: meta.nullable,
-          attribute,
-        }),
-      );
+      insert(application_native(options)(components)(`Set`)(meta.nullable));
     if (meta.maps.length)
-      insert(
-        application_native(options)(components)(`Map`)({
-          nullable: meta.nullable,
-          attribute,
-        }),
-      );
+      insert(application_native(options)(components)(`Map`)(meta.nullable));
 
     // OBJECT
     for (const obj of meta.objects)
@@ -173,7 +154,11 @@ export const application_schema =
             ...attribute,
             type: undefined,
           };
-    else if (union.length === 1) return union[0]!;
+    else if (union.length === 1)
+      return {
+        ...union[0]!,
+        ...attribute,
+      };
     return { oneOf: union, ...attribute };
   };
 

package/src/programmers/internal/application_string.ts

@@ -3,18 +3,19 @@ import { IMetadataTypeTag } from "../../schemas/metadata/IMetadataTypeTag";
 import { Metadata } from "../../schemas/metadata/Metadata";
 import { MetadataAtomic } from "../../schemas/metadata/MetadataAtomic";
 
+import { JsonApplicationProgrammer } from "../json/JsonApplicationProgrammer";
 import { application_default_string } from "./application_default_string";
 
 /**
  * @internal
  */
 export const application_string =
+  (options: JsonApplicationProgrammer.IOptions) =>
   (meta: Metadata) =>
   (atomic: MetadataAtomic) =>
   (attribute: IJsonSchema.IAttribute): IJsonSchema.IString[] => {
     // DEFAULT CONFIGURATION
     const base: IJsonSchema.IString = {
-      ...attribute,
       type: "string",
     };
     const out = (schema: IJsonSchema.IString) => {
@@ -25,7 +26,7 @@ export const application_string =
 
     // CONSIDER TYPE TAGS
     const union: IJsonSchema.IString[] = atomic.tags.map(
-      (row) => application_string_tags({ ...base })(row)!,
+      (row) => application_string_tags(options)({ ...base })(row)!,
     );
     const map: Map<string, IJsonSchema.IString> = new Map(
       union.map((u) => [JSON.stringify(u), u]),
@@ -34,6 +35,7 @@ export const application_string =
   };
 
 const application_string_tags =
+  (options: JsonApplicationProgrammer.IOptions) =>
   (base: IJsonSchema.IString) =>
   (row: IMetadataTypeTag[]): IJsonSchema.IString | null => {
     for (const tag of row.slice().sort((a, b) => a.kind.localeCompare(b.kind)))
@@ -46,13 +48,14 @@ const application_string_tags =
       else if (tag.kind === "pattern") base.pattern = tag.value;
       else if (tag.kind === "default" && typeof tag.value === "string")
         base.default = tag.value;
-    base["x-typia-typeTags"] = row.map((tag) => ({
-      target: tag.target,
-      name: tag.name,
-      kind: tag.kind,
-      value: tag.value,
-      validate: tag.validate,
-      exclusive: tag.exclusive,
-    }));
+    if (options.surplus)
+      base["x-typia-typeTags"] = row.map((tag) => ({
+        target: tag.target,
+        name: tag.name,
+        kind: tag.kind,
+        value: tag.value,
+        validate: tag.validate,
+        exclusive: tag.exclusive,
+      }));
     return base;
   };

package/src/programmers/internal/application_templates.ts

@@ -13,7 +13,6 @@ export const application_templates =
     // CONSTRUCT PATTERN
     const output: IJsonSchema.IString = {
       type: "string",
-      ...attribute,
     };
     output.pattern = metadata_to_pattern(true)(meta);
 

package/src/programmers/internal/application_tuple.ts

@@ -20,7 +20,6 @@ export const application_tuple =
       type: "array",
       items: tuple.type.elements.map((meta, i) =>
         application_schema(options)(false)(components)(meta.rest ?? meta)({
-          ...attribute,
           "x-typia-rest":
             i === tuple.type.elements.length - 1 && meta.rest !== null,
           "x-typia-required": meta.required,

package/src/programmers/json/JsonApplicationProgrammer.ts

@@ -10,18 +10,17 @@ import { application_schema } from "../internal/application_schema";
 export namespace JsonApplicationProgrammer {
   export interface IOptions {
     purpose: "ajv" | "swagger";
+    surplus: boolean;
   }
 
   /**
    * @internal
    */
   export namespace IOptions {
-    export const complement = (options?: Partial<IOptions>): IOptions => {
-      const purpose: "swagger" | "ajv" = options?.purpose ?? "swagger";
-      return {
-        purpose,
-      };
-    };
+    export const complement = (options?: Partial<IOptions>): IOptions => ({
+      purpose: options?.purpose ?? "swagger",
+      surplus: options?.surplus ?? false,
+    });
   }
 
   export const write =

package/src/schemas/json/IJsonApplication.ts

@@ -5,4 +5,5 @@ export interface IJsonApplication {
   schemas: IJsonSchema[];
   components: IJsonComponents;
   purpose: "swagger" | "ajv";
+  surplus: boolean;
 }

package/src/transformers/features/json/JsonApplicationTransformer.ts

@@ -45,13 +45,20 @@ export namespace JsonApplicationTransformer {
         });
 
       // ADDITIONAL PARAMETERS
-      const purpose: "swagger" | "ajv" = get_parameter(
-        project.checker,
-        "Purpose",
-        expression.typeArguments[1],
-        (str) => str === "swagger" || str === "ajv",
-        () => "swagger",
-      );
+      const purpose: "swagger" | "ajv" = get_parameter<"swagger" | "ajv">({
+        checker: project.checker,
+        name: "Purpose",
+        is: (str) => str === "swagger" || str === "ajv",
+        cast: (str) => str as "swagger" | "ajv",
+        default: () => "swagger",
+      })(expression.typeArguments[1]);
+      const surplus: boolean = get_parameter<boolean>({
+        checker: project.checker,
+        name: "Surplus",
+        is: (str) => str === "true" || str === "false",
+        cast: (str) => str === "true",
+        default: () => false,
+      })(expression.typeArguments[2]);
 
       //----
       // GENERATORS
@@ -86,36 +93,42 @@ export namespace JsonApplicationTransformer {
       // APPLICATION
       const app: IJsonApplication = JsonApplicationProgrammer.write({
         purpose,
+        surplus,
       })(metadatas);
-
-      // RETURNS WITH LITERAL EXPRESSION
       return LiteralFactory.generate(app);
     };
 
-  const get_parameter = <T extends string>(
-    checker: ts.TypeChecker,
-    name: string,
-    node: ts.TypeNode | undefined,
-    predicator: (value: string) => boolean,
-    defaulter: () => T,
-  ): T => {
-    if (!node) return defaulter();
-
-    // CHECK LITERAL TYPE
-    const type: ts.Type = checker.getTypeFromTypeNode(node);
-    if (!type.isLiteral())
-      throw new TransformerError({
-        code: "typia.json.application",
-        message: `generic argument "${name}" must be constant.`,
-      });
+  const get_parameter =
+    <Value>(props: {
+      checker: ts.TypeChecker;
+      name: string;
+      is: (value: string) => boolean;
+      cast: (value: string) => Value;
+      default: () => Value;
+    }) =>
+    (node: ts.TypeNode | undefined): Value => {
+      if (!node) return props.default();
+
+      // CHECK LITERAL TYPE
+      const type: ts.Type = props.checker.getTypeFromTypeNode(node);
+      if (
+        !type.isLiteral() &&
+        (type.getFlags() & ts.TypeFlags.BooleanLiteral) === 0
+      )
+        throw new TransformerError({
+          code: "typia.json.application",
+          message: `generic argument "${props.name}" must be constant.`,
+        });
 
-    // GET VALUE AND VALIDATE IT
-    const value = type.value;
-    if (typeof value !== "string" || predicator(value) === false)
-      throw new TransformerError({
-        code: "typia.json.application",
-        message: `invalid value on generic argument "${name}".`,
-      });
-    return value as T;
-  };
+      // GET VALUE AND VALIDATE IT
+      const value = type.isLiteral()
+        ? type.value
+        : props.checker.typeToString(type);
+      if (typeof value !== "string" || props.is(value) === false)
+        throw new TransformerError({
+          code: "typia.json.application",
+          message: `invalid value on generic argument "${props.name}".`,
+        });
+      return props.cast(value);
+    };
 }