@typia/core 12.0.0-dev.20260225

package/src/programmers/iterate/json_schema_description.ts

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

package/src/programmers/iterate/json_schema_discriminator.ts

@@ -0,0 +1,34 @@
+import { OpenApi } from "@typia/interface";
+
+import { MetadataSchema } from "../../schemas/metadata/MetadataSchema";
+import { UnionPredicator } from "../helpers/UnionPredicator";
+
+export const json_schema_discriminator = (
+  metadata: MetadataSchema,
+): OpenApi.IJsonSchema.IOneOf.IDiscriminator | undefined => {
+  if (
+    metadata.size() === 0 ||
+    metadata.size() !== metadata.objects.length ||
+    metadata.objects.some((o) => o.type.isLiteral()) === true
+  )
+    return undefined;
+  const specialized: UnionPredicator.ISpecialized[] = UnionPredicator.object(
+    metadata.objects.map((o) => o.type),
+  );
+  const meet: boolean =
+    specialized.length === metadata.objects.length &&
+    specialized.every(
+      (s) => s.property.key.isSoleLiteral() && s.property.value.isSoleLiteral(),
+    ) &&
+    new Set(specialized.map((s) => s.property.key.getSoleLiteral())).size === 1;
+  if (meet === false) return undefined;
+  return {
+    propertyName: specialized[0]!.property.key.getSoleLiteral()!,
+    mapping: Object.fromEntries(
+      specialized.map((s) => [
+        s.property.value.getSoleLiteral()!,
+        `#/components/schemas/${s.object.name}`,
+      ]),
+    ),
+  };
+};

package/src/programmers/iterate/json_schema_escaped.ts

@@ -0,0 +1,78 @@
+import { OpenApi } from "@typia/interface";
+import { OpenApiTypeChecker } from "@typia/utils";
+
+import { MetadataEscaped } from "../../schemas/metadata/MetadataEscaped";
+import { MetadataSchema } from "../../schemas/metadata/MetadataSchema";
+import { json_schema_station } from "./json_schema_station";
+
+/** @internal */
+export const json_schema_escaped = (props: {
+  components: OpenApi.IComponents;
+  escaped: MetadataEscaped;
+}): OpenApi.IJsonSchema[] => {
+  const output: OpenApi.IJsonSchema | null = json_schema_station({
+    blockNever: false,
+    components: props.components,
+    metadata: props.escaped.returns,
+    attribute: {},
+  });
+  if (output === null) return [];
+
+  if (
+    is_date({
+      visited: new Set(),
+      metadata: props.escaped.original,
+    })
+  ) {
+    const string: OpenApi.IJsonSchema.IString | undefined =
+      OpenApiTypeChecker.isString(output)
+        ? output
+        : OpenApiTypeChecker.isOneOf(output)
+          ? (output.oneOf.find(
+              OpenApiTypeChecker.isString,
+            ) as OpenApi.IJsonSchema.IString)
+          : undefined;
+    if (
+      string !== undefined &&
+      string.format !== "date" &&
+      string.format !== "date-time"
+    )
+      string.format = "date-time";
+  }
+  return OpenApiTypeChecker.isOneOf(output)
+    ? (output.oneOf as OpenApi.IJsonSchema[])
+    : [output];
+};
+
+/** @internal */
+const is_date = (props: {
+  visited: Set<MetadataSchema>;
+  metadata: MetadataSchema;
+}): boolean => {
+  if (props.visited.has(props.metadata)) return false;
+  props.visited.add(props.metadata);
+
+  return (
+    props.metadata.natives.some((native) => native.name === "Date") ||
+    props.metadata.arrays.some((array) =>
+      is_date({
+        visited: props.visited,
+        metadata: array.type.value,
+      }),
+    ) ||
+    props.metadata.tuples.some((tuple) =>
+      tuple.type.elements.some((e) =>
+        is_date({
+          visited: props.visited,
+          metadata: e,
+        }),
+      ),
+    ) ||
+    props.metadata.aliases.some((alias) =>
+      is_date({
+        visited: props.visited,
+        metadata: alias.type.value,
+      }),
+    )
+  );
+};

package/src/programmers/iterate/json_schema_jsDocTags.ts

@@ -0,0 +1,25 @@
+import { IJsDocTagInfo, OpenApi } from "@typia/interface";
+
+export const json_schema_jsDocTags = <Schema extends OpenApi.IJsonSchema>(
+  schema: Schema,
+  jsDocTags: IJsDocTagInfo[],
+): Schema => {
+  for (const tag of jsDocTags) {
+    if (tag.name.startsWith("x-") === false) continue;
+
+    const value: string | undefined = tag.text
+      ?.filter((s) => s.kind === "text")
+      .map((s) => s.text.trim().split("\r\n").join("\n"))[0];
+    if (value === undefined) continue;
+    else (schema as any)[tag.name] = cast(value);
+  }
+  return schema;
+};
+
+const cast = (value: string): string | number | boolean | null => {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  const num: number = Number(value);
+  if (Number.isNaN(num) === false) return num;
+  return value === "null" ? null : value;
+};

package/src/programmers/iterate/json_schema_native.ts

@@ -0,0 +1,32 @@
+import { OpenApi } from "@typia/interface";
+
+import { MetadataNative } from "../../schemas/metadata/MetadataNative";
+import { json_schema_plugin } from "./json_schema_plugin";
+
+export const json_schema_native = (props: {
+  components: OpenApi.IComponents;
+  native: MetadataNative;
+}): OpenApi.IJsonSchema[] => {
+  if (props.native.name === "Blob" || props.native.name === "File")
+    return json_schema_plugin({
+      schema: {
+        type: "string",
+        format: "binary",
+      },
+      tags: props.native.tags,
+    });
+  if (props.components.schemas?.[props.native.name] === undefined) {
+    props.components.schemas ??= {};
+    props.components.schemas[props.native.name] ??= {
+      type: "object",
+      properties: {},
+      required: [],
+    };
+  }
+  return json_schema_plugin({
+    schema: {
+      $ref: `#/components/schemas/${props.native.name}`,
+    },
+    tags: props.native.tags,
+  });
+};

package/src/programmers/iterate/json_schema_number.ts

@@ -0,0 +1,14 @@
+import { OpenApi } from "@typia/interface";
+
+import { MetadataAtomic } from "../../schemas/metadata/MetadataAtomic";
+import { json_schema_plugin } from "./json_schema_plugin";
+
+export const json_schema_number = (
+  atomic: MetadataAtomic,
+): Array<OpenApi.IJsonSchema.IInteger | OpenApi.IJsonSchema.INumber> =>
+  json_schema_plugin({
+    schema: {
+      type: "number",
+    } satisfies OpenApi.IJsonSchema.INumber,
+    tags: atomic.tags,
+  });

package/src/programmers/iterate/json_schema_object.ts

@@ -0,0 +1,159 @@
+import { IJsDocTagInfo, OpenApi } from "@typia/interface";
+
+import { CommentFactory } from "../../factories/CommentFactory";
+import { MetadataObject } from "../../schemas/metadata/MetadataObject";
+import { MetadataSchema } from "../../schemas/metadata/MetadataSchema";
+import { PatternUtil } from "../../utils/PatternUtil";
+import { json_schema_description } from "./json_schema_description";
+import { json_schema_jsDocTags } from "./json_schema_jsDocTags";
+import { json_schema_plugin } from "./json_schema_plugin";
+import { json_schema_station } from "./json_schema_station";
+import { json_schema_title } from "./json_schema_title";
+import { metadata_to_pattern } from "./metadata_to_pattern";
+
+/** @internal */
+export const json_schema_object = (props: {
+  components: OpenApi.IComponents;
+  object: MetadataObject;
+}): Array<OpenApi.IJsonSchema.IReference | OpenApi.IJsonSchema.IObject> =>
+  json_schema_plugin({
+    schema: emplace_object(props),
+    tags: props.object.tags,
+  });
+
+const emplace_object = (props: {
+  components: OpenApi.IComponents;
+  object: MetadataObject;
+}): OpenApi.IJsonSchema.IReference | OpenApi.IJsonSchema.IObject => {
+  if (props.object.type.isLiteral() === true)
+    return create_object_schema(props);
+
+  const key: string = props.object.type.name;
+  const $ref: string = `#/components/schemas/${key}`;
+  if (props.components.schemas?.[key] !== undefined) return { $ref };
+
+  const lazy: OpenApi.IJsonSchema = {};
+  props.components.schemas ??= {};
+  props.components.schemas[key] = lazy;
+  Object.assign(lazy, create_object_schema(props));
+  return { $ref };
+};
+
+/** @internal */
+const create_object_schema = (props: {
+  components: OpenApi.IComponents;
+  object: MetadataObject;
+}): OpenApi.IJsonSchema.IObject => {
+  // ITERATE PROPERTIES
+  const properties: Record<string, any> = {};
+  const extraMeta: ISuperfluous = {
+    patternProperties: {},
+    additionalProperties: undefined,
+  };
+  const required: string[] = [];
+
+  for (const property of props.object.type.properties) {
+    if (
+      // FUNCTIONAL TYPE
+      property.value.functions.length &&
+      property.value.nullable === false &&
+      property.value.isRequired() === true &&
+      property.value.size() === 0
+    )
+      continue;
+    else if (
+      property.jsDocTags.find(
+        (tag) =>
+          tag.name === "hidden" ||
+          tag.name === "ignore" ||
+          tag.name === "internal",
+      )
+    )
+      continue; // THE HIDDEN/IGNORE/INTERNAL TAGS
+
+    const value: OpenApi.IJsonSchema | null = json_schema_station({
+      blockNever: true,
+      components: props.components,
+      attribute: {
+        deprecated:
+          property.jsDocTags.some((tag) => tag.name === "deprecated") ||
+          undefined,
+        title: json_schema_title(property),
+        description: json_schema_description(property),
+        readOnly: property.mutability === "readonly" ? true : undefined,
+      },
+      metadata: property.value,
+    });
+    if (value === null) continue;
+    else json_schema_jsDocTags(value, property.jsDocTags);
+
+    const key: string | null = property.key.getSoleLiteral();
+    if (key !== null) {
+      properties[key] = value;
+      if (property.value.isRequired() === true) required.push(key);
+    } else {
+      const pattern: string = metadata_to_pattern({
+        top: true,
+        metadata: property.key,
+      });
+      if (pattern === PatternUtil.STRING)
+        extraMeta.additionalProperties = [property.value, value];
+      else extraMeta.patternProperties[pattern] = [property.value, value];
+    }
+  }
+
+  return json_schema_jsDocTags(
+    {
+      type: "object",
+      properties,
+      required,
+      title: (() => {
+        const info: IJsDocTagInfo | undefined =
+          props.object.type.jsDocTags.find((tag) => tag.name === "title");
+        return info?.text?.length ? CommentFactory.merge(info.text) : undefined;
+      })(),
+      description: json_schema_description(props.object.type),
+      additionalProperties: join({
+        components: props.components,
+        extra: extraMeta,
+      }),
+    },
+    props.object.type.jsDocTags,
+  );
+};
+
+/** @internal */
+const join = (props: {
+  components: OpenApi.IComponents;
+  extra: ISuperfluous;
+}): OpenApi.IJsonSchema | undefined => {
+  // LIST UP METADATA
+  const elements: [MetadataSchema, OpenApi.IJsonSchema][] = Object.values(
+    props.extra.patternProperties || {},
+  );
+  if (props.extra.additionalProperties)
+    elements.push(props.extra.additionalProperties);
+
+  // SHORT RETURN
+  if (elements.length === 0) return undefined;
+  else if (elements.length === 1) return elements[0]![1]!;
+
+  // MERGE METADATA AND GENERATE VULNERABLE SCHEMA
+  const metadata: MetadataSchema = elements
+    .map((tuple) => tuple[0])
+    .reduce((x, y) => MetadataSchema.merge(x, y));
+  return (
+    json_schema_station({
+      blockNever: true,
+      components: props.components,
+      attribute: {},
+      metadata,
+    }) ?? undefined
+  );
+};
+
+/** @internal */
+interface ISuperfluous {
+  additionalProperties?: undefined | [MetadataSchema, OpenApi.IJsonSchema];
+  patternProperties: Record<string, [MetadataSchema, OpenApi.IJsonSchema]>;
+}

package/src/programmers/iterate/json_schema_plugin.ts

@@ -0,0 +1,16 @@
+import { IMetadataTypeTag, OpenApi } from "@typia/interface";
+
+export const json_schema_plugin = <Schema extends OpenApi.IJsonSchema>(props: {
+  schema: Schema;
+  tags: IMetadataTypeTag[][];
+}): Schema[] => {
+  const plugins: IMetadataTypeTag[][] = props.tags
+    .map((row) => row.filter((t) => t.schema !== undefined))
+    .filter((row) => row.length !== 0);
+  if (plugins.length === 0) return [props.schema];
+  return plugins.map((row) => {
+    const base: Schema = { ...props.schema };
+    for (const tag of row) Object.assign(base, tag.schema);
+    return base;
+  });
+};

package/src/programmers/iterate/json_schema_station.ts

@@ -0,0 +1,183 @@
+import { IJsonSchemaAttribute, OpenApi } from "@typia/interface";
+import { OpenApiExclusiveEmender } from "@typia/utils";
+
+import { MetadataAtomic } from "../../schemas/metadata/MetadataAtomic";
+import { MetadataNative } from "../../schemas/metadata/MetadataNative";
+import { MetadataSchema } from "../../schemas/metadata/MetadataSchema";
+import { AtomicPredicator } from "../helpers/AtomicPredicator";
+import { json_schema_alias } from "./json_schema_alias";
+import { json_schema_array } from "./json_schema_array";
+import { json_schema_bigint } from "./json_schema_bigint";
+import { json_schema_boolean } from "./json_schema_boolean";
+import { json_schema_constant } from "./json_schema_constant";
+import { json_schema_discriminator } from "./json_schema_discriminator";
+import { json_schema_escaped } from "./json_schema_escaped";
+import { json_schema_native } from "./json_schema_native";
+import { json_schema_number } from "./json_schema_number";
+import { json_schema_object } from "./json_schema_object";
+import { json_schema_string } from "./json_schema_string";
+import { json_schema_templates } from "./json_schema_template";
+import { json_schema_tuple } from "./json_schema_tuple";
+
+export const json_schema_station = <BlockNever extends boolean>(props: {
+  blockNever: BlockNever;
+  components: OpenApi.IComponents;
+  attribute: IJsonSchemaAttribute;
+  metadata: MetadataSchema;
+}): BlockNever extends true
+  ? OpenApi.IJsonSchema | null
+  : OpenApi.IJsonSchema => {
+  if (props.metadata.any === true)
+    return {
+      ...props.attribute,
+      type: undefined,
+    };
+
+  //----
+  // GATHER UNION SCHEMAS
+  //----
+  const union: OpenApi.IJsonSchema[] = [];
+  const insert = (schema: OpenApi.IJsonSchema) => union.push(schema);
+
+  // NULLABLE
+  if (props.metadata.nullable === true)
+    insert({
+      type: "null",
+    });
+
+  // toJSON() METHOD
+  if (props.metadata.escaped !== null)
+    json_schema_escaped({
+      components: props.components,
+      escaped: props.metadata.escaped,
+    }).forEach(insert);
+
+  // ATOMIC TYPES
+  if (
+    props.metadata.templates.length &&
+    AtomicPredicator.template(props.metadata)
+  )
+    json_schema_templates(props.metadata).forEach(insert);
+  for (const constant of props.metadata.constants)
+    if (
+      AtomicPredicator.constant({
+        metadata: props.metadata,
+        name: constant.type,
+      }) === false
+    )
+      continue;
+    else json_schema_constant(constant).forEach(insert);
+  for (const a of props.metadata.atomics)
+    if (a.type === "boolean") json_schema_boolean(a).forEach(insert);
+    else if (a.type === "bigint") json_schema_bigint(a).forEach(insert);
+    else if (a.type === "number")
+      json_schema_number(a).map(OpenApiExclusiveEmender.emend).forEach(insert);
+    else if (a.type === "string") json_schema_string(a).forEach(insert);
+
+  // ARRAY
+  for (const array of props.metadata.arrays)
+    json_schema_array({
+      components: props.components,
+      array,
+    }).forEach(insert);
+
+  // TUPLE
+  for (const tuple of props.metadata.tuples)
+    insert(
+      json_schema_tuple({
+        components: props.components,
+        tuple,
+      }),
+    );
+
+  // NATIVES
+  for (const native of props.metadata.natives)
+    if (AtomicPredicator.native(native.name)) {
+      const type: string = native.name.toLowerCase();
+      if (props.metadata.atomics.some((a) => a.type === type)) continue;
+      else if (type === "boolean")
+        json_schema_boolean(
+          MetadataAtomic.create({
+            type: "boolean",
+            tags: [],
+          }),
+        ).map(insert);
+      else if (type === "bigint")
+        json_schema_bigint(
+          MetadataAtomic.create({
+            type: "bigint",
+            tags: [],
+          }),
+        ).map(insert);
+      else if (type === "number")
+        json_schema_number(
+          MetadataAtomic.create({
+            type: "number",
+            tags: [],
+          }),
+        ).map(insert);
+      else if (type === "string")
+        json_schema_string(
+          MetadataAtomic.create({
+            type: "string",
+            tags: [],
+          }),
+        ).map(insert);
+    } else
+      json_schema_native({
+        components: props.components,
+        native,
+      }).forEach(insert);
+  if (props.metadata.sets.length)
+    json_schema_native({
+      native: MetadataNative.create({
+        name: "Set",
+        tags: [],
+      }),
+      components: props.components,
+    }).forEach(insert);
+  if (props.metadata.maps.length)
+    json_schema_native({
+      native: MetadataNative.create({
+        name: "Map",
+        tags: [],
+      }),
+      components: props.components,
+    }).forEach(insert);
+
+  // OBJECT
+  for (const object of props.metadata.objects)
+    json_schema_object({
+      components: props.components,
+      object,
+    }).forEach(insert);
+
+  // ALIASES
+  for (const alias of props.metadata.aliases)
+    json_schema_alias({
+      alias,
+      blockNever: props.blockNever,
+      components: props.components,
+    }).forEach(insert);
+
+  //----
+  // RETURNS
+  //----
+  if (union.length === 0 && props.blockNever === true) return null!;
+  const schema: OpenApi.IJsonSchema =
+    union.length === 0
+      ? { type: undefined }
+      : union.length === 1
+        ? union[0]!
+        : {
+            oneOf: union,
+            discriminator: json_schema_discriminator(props.metadata),
+          };
+  return {
+    ...schema,
+    ...props.attribute,
+    title: props.attribute.title ?? schema.title,
+    description: props.attribute.description ?? schema.description,
+    deprecated: props.attribute.deprecated ?? schema.deprecated,
+  };
+};

package/src/programmers/iterate/json_schema_string.ts

@@ -0,0 +1,14 @@
+import { OpenApi } from "@typia/interface";
+
+import { MetadataAtomic } from "../../schemas/metadata/MetadataAtomic";
+import { json_schema_plugin } from "./json_schema_plugin";
+
+export const json_schema_string = (
+  atomic: MetadataAtomic,
+): OpenApi.IJsonSchema[] =>
+  json_schema_plugin({
+    schema: {
+      type: "string",
+    } satisfies OpenApi.IJsonSchema,
+    tags: atomic.tags,
+  });

package/src/programmers/iterate/json_schema_template.ts

@@ -0,0 +1,53 @@
+import { IMetadataTypeTag, OpenApi } from "@typia/interface";
+
+import { MetadataSchema } from "../../schemas/metadata/MetadataSchema";
+import { MetadataTemplate } from "../../schemas/metadata/MetadataTemplate";
+import { json_schema_plugin } from "./json_schema_plugin";
+import { metadata_to_pattern } from "./metadata_to_pattern";
+
+export const json_schema_templates = (
+  metadata: MetadataSchema,
+): OpenApi.IJsonSchema[] => {
+  const pureTemplates: MetadataTemplate[] = metadata.templates.filter(
+    (t) => isPure(t.tags ?? []) === true,
+  );
+  const taggedTemplates: MetadataTemplate[] = metadata.templates.filter(
+    (t) => isPure(t.tags ?? []) === false,
+  );
+
+  const output: OpenApi.IJsonSchema[] = [];
+  if (pureTemplates.length)
+    output.push({
+      type: "string",
+      pattern: metadata_to_pattern({
+        top: true,
+        metadata: MetadataSchema.create({
+          ...MetadataSchema.initialize(),
+          templates: pureTemplates,
+        }),
+      }),
+    });
+  for (const tpl of taggedTemplates)
+    output.push(
+      ...json_schema_plugin({
+        schema: {
+          type: "string",
+          pattern: metadata_to_pattern({
+            top: false,
+            metadata: MetadataSchema.create({
+              ...MetadataSchema.initialize(),
+              templates: [tpl],
+            }),
+          }),
+        },
+        tags: tpl.tags ?? [],
+      }),
+    );
+  return output;
+};
+
+const isPure = (matrix: IMetadataTypeTag[][]) =>
+  matrix.every((tags) => filter(tags).length === 0);
+
+const filter = (tags: IMetadataTypeTag[]) =>
+  tags.filter((t) => t.schema !== undefined);

package/src/programmers/iterate/json_schema_title.ts

@@ -0,0 +1,13 @@
+import { IJsDocTagInfo } from "@typia/interface";
+
+import { CommentFactory } from "../../factories/CommentFactory";
+
+export const json_schema_title = (schema: {
+  description?: string | null | undefined;
+  jsDocTags?: IJsDocTagInfo[] | undefined;
+}): string | undefined => {
+  const info: IJsDocTagInfo | undefined = schema.jsDocTags?.find(
+    (tag) => tag.name === "title",
+  );
+  return !!info?.text?.length ? CommentFactory.merge(info.text) : undefined;
+};

package/src/programmers/iterate/json_schema_tuple.ts

@@ -0,0 +1,35 @@
+import { OpenApi } from "@typia/interface";
+
+import { MetadataSchema } from "../../schemas/metadata/MetadataSchema";
+import { MetadataTuple } from "../../schemas/metadata/MetadataTuple";
+import { json_schema_station } from "./json_schema_station";
+
+export const json_schema_tuple = (props: {
+  components: OpenApi.IComponents;
+  tuple: MetadataTuple;
+}): OpenApi.IJsonSchema.ITuple => {
+  const tail: MetadataSchema | null =
+    props.tuple.type.elements.at(-1)?.rest ?? null;
+  const prefixItems: MetadataSchema[] = props.tuple.type.isRest()
+    ? props.tuple.type.elements.slice(0, -1)
+    : props.tuple.type.elements;
+  return {
+    type: "array",
+    prefixItems: prefixItems.map((metadata) =>
+      json_schema_station({
+        blockNever: false,
+        components: props.components,
+        metadata,
+        attribute: {},
+      }),
+    ),
+    additionalItems: tail
+      ? json_schema_station({
+          blockNever: false,
+          components: props.components,
+          metadata: tail,
+          attribute: {},
+        })
+      : false,
+  };
+};