@typia/core 12.0.0-dev.20260225

package/src/schemas/metadata/MetadataSet.ts

@@ -0,0 +1,48 @@
+import {
+  ClassProperties,
+  IMetadataSchema,
+  IMetadataTypeTag,
+} from "@typia/interface";
+
+import { MetadataSchema } from "./MetadataSchema";
+
+export class MetadataSet {
+  public readonly value: MetadataSchema;
+  public readonly tags: IMetadataTypeTag[][];
+  private name_?: string;
+
+  private constructor(props: ClassProperties<MetadataSet>) {
+    this.value = props.value;
+    this.tags = props.tags;
+  }
+
+  /** @internal */
+  public static create(props: ClassProperties<MetadataSet>): MetadataSet {
+    return new MetadataSet(props);
+  }
+
+  public getName(): string {
+    return (this.name_ ??= (() => {
+      const symbol: string = `Set<${this.value.getName()}>`;
+      if (this.tags.length === 0) return symbol;
+      else if (this.tags.length === 1) {
+        const str: string = [symbol, ...this.tags[0]!.map((t) => t.name)].join(
+          " & ",
+        );
+        return `(${str})`;
+      }
+      const rows: string[] = this.tags.map((row) => {
+        const str: string = row.map((t) => t.name).join(" & ");
+        return row.length === 1 ? str : `(${str})`;
+      });
+      return `(${symbol} & (${rows.join(" | ")}))`;
+    })());
+  }
+
+  public toJSON(): IMetadataSchema.ISet {
+    return {
+      value: this.value.toJSON(),
+      tags: this.tags,
+    };
+  }
+}

package/src/schemas/metadata/MetadataStorage.ts

@@ -0,0 +1,275 @@
+import { IMetadataComponents } from "@typia/interface";
+import { MapUtil } from "@typia/utils";
+import ts from "typescript";
+
+import { CommentFactory } from "../../factories/CommentFactory";
+import { TypeFactory } from "../../factories/TypeFactory";
+import { Writable } from "../../typings/Writable";
+import { MetadataAliasType } from "./MetadataAliasType";
+import { MetadataArrayType } from "./MetadataArrayType";
+import { MetadataObjectType } from "./MetadataObjectType";
+import { MetadataSchema } from "./MetadataSchema";
+import { MetadataTupleType } from "./MetadataTupleType";
+
+/**
+ * Storage for collected metadata during type analysis.
+ *
+ * Caches analyzed types (objects, aliases, arrays, tuples) to handle recursive
+ * types and avoid redundant analysis.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export class MetadataStorage {
+  private objects_: Map<ts.Type, MetadataObjectType>;
+  private object_unions_: Map<string, MetadataObjectType[]>;
+  private aliases_: Map<ts.Type, MetadataAliasType>;
+  private arrays_: Map<ts.Type, MetadataArrayType>;
+  private tuples_: Map<ts.Type, MetadataTupleType>;
+
+  private names_: Map<string, Map<ts.Type, string>>;
+  private object_index_: number;
+  private recursive_array_index_: number;
+  private recursive_tuple_index_: number;
+
+  public constructor(private options?: Partial<MetadataStorage.IOptions>) {
+    this.objects_ = new Map();
+    this.object_unions_ = new Map();
+    this.aliases_ = new Map();
+    this.arrays_ = new Map();
+    this.tuples_ = new Map();
+
+    this.names_ = new Map();
+    this.object_index_ = 0;
+    this.recursive_array_index_ = 0;
+    this.recursive_tuple_index_ = 0;
+  }
+
+  public clone(): MetadataStorage {
+    const output: MetadataStorage = new MetadataStorage(this.options);
+    output.objects_ = new Map(this.objects_);
+    output.object_unions_ = new Map(this.object_unions_);
+    output.aliases_ = new Map(this.aliases_);
+    output.arrays_ = new Map(this.arrays_);
+    output.tuples_ = new Map(this.tuples_);
+    output.names_ = new Map(this.names_);
+    output.object_index_ = this.object_index_;
+    output.recursive_array_index_ = this.recursive_array_index_;
+    output.recursive_tuple_index_ = this.recursive_tuple_index_;
+    return output;
+  }
+
+  /* -----------------------------------------------------------
+        ACCESSORS
+    ----------------------------------------------------------- */
+  public aliases(): MetadataAliasType[] {
+    return [...this.aliases_.values()];
+  }
+
+  public objects(): MetadataObjectType[] {
+    return [...this.objects_.values()];
+  }
+
+  public unions(): MetadataObjectType[][] {
+    return [...this.object_unions_.values()];
+  }
+
+  public arrays(): MetadataArrayType[] {
+    return [...this.arrays_.values()];
+  }
+
+  public tuples(): MetadataTupleType[] {
+    return [...this.tuples_.values()];
+  }
+
+  private getName(checker: ts.TypeChecker, type: ts.Type): string {
+    const name: string = (() => {
+      const str: string = TypeFactory.getFullName({
+        checker,
+        type,
+      });
+      return this.options?.replace ? this.options.replace(str) : str;
+    })();
+
+    const duplicates: Map<ts.Type, string> = MapUtil.take(
+      this.names_,
+      name,
+      () => new Map(),
+    );
+    const oldbie: string | undefined = duplicates.get(type);
+    if (oldbie !== undefined) return oldbie;
+
+    const addicted: string = duplicates.size
+      ? `${name}.o${duplicates.size}`
+      : name;
+    duplicates.set(type, addicted);
+    return addicted;
+  }
+
+  /** @internal */
+  public getUnionIndex(meta: MetadataSchema): number {
+    const key: string = meta.objects.map((obj) => obj.type.name).join(" | ");
+    MapUtil.take(this.object_unions_, key, () =>
+      meta.objects.map((o) => o.type),
+    );
+    return [...this.object_unions_.keys()].indexOf(key);
+  }
+
+  /* -----------------------------------------------------------
+        INSTANCES
+    ----------------------------------------------------------- */
+  public emplace(
+    checker: ts.TypeChecker,
+    type: ts.Type,
+  ): [MetadataObjectType, boolean] {
+    const oldbie = this.objects_.get(type);
+    if (oldbie !== undefined) return [oldbie, false];
+
+    const id: string = this.getName(checker, type);
+    const obj: MetadataObjectType = MetadataObjectType.create({
+      name: id,
+      properties: [],
+      description:
+        (type.aliasSymbol && CommentFactory.description(type.aliasSymbol)) ??
+        (type.symbol && CommentFactory.description(type.symbol)) ??
+        undefined,
+      jsDocTags:
+        type.aliasSymbol?.getJsDocTags() ?? type.symbol?.getJsDocTags() ?? [],
+      validated: false,
+      index: this.object_index_++,
+      recursive: null!,
+      nullables: [],
+    });
+    this.objects_.set(type, obj);
+    return [obj, true];
+  }
+
+  public emplaceAlias(
+    checker: ts.TypeChecker,
+    type: ts.Type,
+    symbol: ts.Symbol,
+  ): [MetadataAliasType, boolean, (meta: MetadataSchema) => void] {
+    const oldbie = this.aliases_.get(type);
+    if (oldbie !== undefined) return [oldbie, false, () => {}];
+
+    const id: string = this.getName(checker, type);
+    const alias: MetadataAliasType = MetadataAliasType.create({
+      name: id,
+      value: null!,
+      description: CommentFactory.description(symbol) ?? null,
+      recursive: null!,
+      nullables: [],
+      jsDocTags: symbol.getJsDocTags() ?? [],
+    });
+    this.aliases_.set(type, alias);
+    return [alias, true, (meta) => (Writable(alias).value = meta)];
+  }
+
+  public emplaceArray(
+    checker: ts.TypeChecker,
+    type: ts.Type,
+  ): [MetadataArrayType, boolean, (meta: MetadataSchema) => void] {
+    const oldbie = this.arrays_.get(type);
+    if (oldbie !== undefined) return [oldbie, false, () => {}];
+
+    const id = this.getName(checker, type);
+    const array: MetadataArrayType = MetadataArrayType.create({
+      name: id,
+      value: null!,
+      index: null,
+      recursive: null!,
+      nullables: [],
+    });
+    this.arrays_.set(type, array);
+    return [array, true, (meta) => (Writable(array).value = meta)];
+  }
+
+  public emplaceTuple(
+    checker: ts.TypeChecker,
+    type: ts.TupleType,
+  ): [MetadataTupleType, boolean, (elements: MetadataSchema[]) => void] {
+    const oldbie = this.tuples_.get(type);
+    if (oldbie !== undefined) return [oldbie, false, () => {}];
+
+    const id = this.getName(checker, type);
+    const tuple: MetadataTupleType = MetadataTupleType.create({
+      name: id,
+      elements: null!,
+      index: null,
+      recursive: null!,
+      nullables: [],
+    });
+    this.tuples_.set(type, tuple);
+    return [tuple, true, (elements) => (Writable(tuple).elements = elements)];
+  }
+
+  /** @internal */
+  public setObjectRecursive(obj: MetadataObjectType, recursive: boolean): void {
+    Writable(obj).recursive = recursive;
+  }
+
+  /** @internal */
+  public setAliasRecursive(alias: MetadataAliasType, recursive: boolean): void {
+    Writable(alias).recursive = recursive;
+  }
+
+  /** @internal */
+  public setArrayRecursive(array: MetadataArrayType, recursive: boolean): void {
+    Writable(array).recursive = recursive;
+    if (recursive) Writable(array).index = this.recursive_array_index_++;
+  }
+
+  public setTupleRecursive(tuple: MetadataTupleType, recursive: boolean): void {
+    Writable(tuple).recursive = recursive;
+    if (recursive) Writable(tuple).index = this.recursive_tuple_index_++;
+  }
+
+  public toJSON(): IMetadataComponents {
+    return {
+      objects: this.objects().map((o) => o.toJSON()),
+      aliases: this.aliases().map((d) => d.toJSON()),
+      arrays: [...this.arrays_.values()].map((a) => a.toJSON()),
+      tuples: [...this.tuples_.values()].map((t) => t.toJSON()),
+    };
+  }
+}
+export namespace MetadataStorage {
+  export interface IOptions {
+    replace?(str: string): string;
+  }
+
+  export const replace = (str: string): string => {
+    let replaced: string = str;
+    for (const [before] of REPLACERS)
+      replaced = replaced.split(before).join("");
+    if (replaced.length !== 0) return replaced;
+
+    for (const [before, after] of REPLACERS)
+      str = str.split(before).join(after);
+    return str;
+  };
+
+  export const escape = (str: string): string => {
+    for (const [before, after] of REPLACERS)
+      if (after !== "") str = str.split(after).join(before);
+    return str;
+  };
+}
+const REPLACERS: [string, string][] = [
+  ["$", "_dollar_"],
+  ["&", "_and_"],
+  ["|", "_or_"],
+  ["{", "_blt_"],
+  ["}", "_bgt_"],
+  ["<", "_lt_"],
+  [">", "_gt_"],
+  ["[", "_alt_"],
+  ["]", "_agt_"],
+  [",", "_comma_"],
+  ["`", "_backquote_"],
+  ["'", "_singlequote_"],
+  ['"', "_doublequote_"],
+  [" ", "_space_"],
+  ["?", "_question_"],
+  [":", "_colon_"],
+  [";", "_semicolon_"],
+];

package/src/schemas/metadata/MetadataTemplate.ts

@@ -0,0 +1,81 @@
+import {
+  ClassProperties,
+  IMetadataSchema,
+  IMetadataTypeTag,
+} from "@typia/interface";
+
+import { IMetadataDictionary } from "./IMetadataDictionary";
+import { MetadataSchema } from "./MetadataSchema";
+
+export class MetadataTemplate {
+  public readonly row: MetadataSchema[];
+  public readonly tags: IMetadataTypeTag[][];
+
+  private name_?: string;
+
+  private constructor(props: ClassProperties<MetadataTemplate>) {
+    this.row = props.row.map(MetadataSchema.create);
+    this.tags = props.tags;
+  }
+
+  /** @internal */
+  public static create(
+    props: ClassProperties<MetadataTemplate>,
+  ): MetadataTemplate {
+    return new MetadataTemplate(props);
+  }
+
+  public static from(
+    json: IMetadataSchema.ITemplate,
+    dict: IMetadataDictionary,
+  ): MetadataTemplate {
+    return new MetadataTemplate({
+      row: json.row.map((m) => MetadataSchema.from(m, dict)),
+      tags: json.tags,
+    });
+  }
+
+  public getName(): string {
+    return (this.name_ ??= getName(this));
+  }
+
+  /** @internal */
+  public getBaseName(): string {
+    return (
+      "`" +
+      this.row
+        .map((child) =>
+          child.isConstant() && child.size() === 1
+            ? child.constants[0]!.values[0]!.value
+            : `$\{${child.getName()}\}`,
+        )
+        .join("")
+        .split("`")
+        .join("\\`") +
+      "`"
+    );
+  }
+
+  public toJSON(): IMetadataSchema.ITemplate {
+    return {
+      row: this.row.map((m) => m.toJSON()),
+      tags: this.tags,
+    };
+  }
+}
+
+const getName = (template: MetadataTemplate): string => {
+  const base: string = template.getBaseName();
+  if (!template.tags?.length) return base;
+  else if (template.tags.length === 1) {
+    const str: string = [base, ...template.tags[0]!.map((t) => t.name)].join(
+      " & ",
+    );
+    return `(${str})`;
+  }
+  const rows: string[] = template.tags.map((row) => {
+    const str: string = row.map((t) => t.name).join(" & ");
+    return row.length === 1 ? str : `(${str})`;
+  });
+  return `(${base} & (${rows.join(" | ")}))`;
+};

package/src/schemas/metadata/MetadataTuple.ts

@@ -0,0 +1,29 @@
+import {
+  ClassProperties,
+  IMetadataSchema,
+  IMetadataTypeTag,
+} from "@typia/interface";
+
+import { MetadataTupleType } from "./MetadataTupleType";
+
+export class MetadataTuple {
+  public readonly type: MetadataTupleType;
+  public readonly tags: IMetadataTypeTag[][];
+
+  private constructor(props: ClassProperties<MetadataTuple>) {
+    this.type = props.type;
+    this.tags = props.tags;
+  }
+
+  /** @internal */
+  public static create(props: ClassProperties<MetadataTuple>): MetadataTuple {
+    return new MetadataTuple(props);
+  }
+
+  public toJSON(): IMetadataSchema.IReference {
+    return {
+      name: this.type.name,
+      tags: this.tags.map((row) => row.slice()),
+    };
+  }
+}

package/src/schemas/metadata/MetadataTupleType.ts

@@ -0,0 +1,59 @@
+import { ClassProperties, IMetadataSchema } from "@typia/interface";
+
+import { MetadataSchema } from "./MetadataSchema";
+
+export class MetadataTupleType {
+  public readonly name: string;
+  public readonly elements: MetadataSchema[];
+
+  public readonly index: number | null;
+  public readonly recursive: boolean;
+  public readonly nullables: boolean[];
+
+  /** @internal */
+  public of_map?: boolean;
+
+  private constructor(props: ClassProperties<MetadataTupleType>) {
+    this.name = props.name;
+    this.elements = props.elements;
+    this.index = props.index;
+    this.recursive = props.recursive;
+    this.nullables = props.nullables;
+  }
+
+  /** @internal */
+  public static _From_without_elements(
+    props: Omit<IMetadataSchema.ITupleType, "elements">,
+  ): MetadataTupleType {
+    return MetadataTupleType.create({
+      name: props.name,
+      index: props.index,
+      elements: null!,
+      recursive: props.recursive,
+      nullables: props.nullables.slice(),
+    });
+  }
+
+  public static create(
+    props: ClassProperties<MetadataTupleType>,
+  ): MetadataTupleType {
+    return new MetadataTupleType(props);
+  }
+
+  public isRest(): boolean {
+    return (
+      this.elements.length > 0 &&
+      this.elements[this.elements.length - 1]!.rest !== null
+    );
+  }
+
+  public toJSON(): IMetadataSchema.ITupleType {
+    return {
+      name: this.name,
+      index: this.index,
+      elements: this.elements.map((elem) => elem.toJSON()),
+      recursive: this.recursive,
+      nullables: this.nullables.slice(),
+    };
+  }
+}

package/src/schemas/metadata/index.ts

@@ -0,0 +1,24 @@
+export * from "./IMetadataDictionary";
+export * from "./MetadataAlias";
+export * from "./MetadataAliasType";
+export * from "./MetadataApplication";
+export * from "./MetadataArray";
+export * from "./MetadataArrayType";
+export * from "./MetadataAtomic";
+export * from "./MetadataComponents";
+export * from "./MetadataConstant";
+export * from "./MetadataConstantValue";
+export * from "./MetadataEscaped";
+export * from "./MetadataFunction";
+export * from "./MetadataMap";
+export * from "./MetadataNative";
+export * from "./MetadataObject";
+export * from "./MetadataObjectType";
+export * from "./MetadataParameter";
+export * from "./MetadataProperty";
+export * from "./MetadataSchema";
+export * from "./MetadataSet";
+export * from "./MetadataStorage";
+export * from "./MetadataTemplate";
+export * from "./MetadataTuple";
+export * from "./MetadataTupleType";

package/src/schemas/protobuf/IProtobufProperty.ts

@@ -0,0 +1,6 @@
+import { IProtobufPropertyType } from "./IProtobufPropertyType";
+
+export interface IProtobufProperty {
+  fixed: boolean;
+  union: IProtobufPropertyType[];
+}

package/src/schemas/protobuf/IProtobufPropertyType.ts

@@ -0,0 +1,37 @@
+import { IProtobufSchema } from "./IProtobufSchema";
+
+export type IProtobufPropertyType =
+  | IProtobufPropertyType.IByte
+  | IProtobufPropertyType.IBoolean
+  | IProtobufPropertyType.IBigint
+  | IProtobufPropertyType.INumber
+  | IProtobufPropertyType.IString
+  | IProtobufPropertyType.IArray
+  | IProtobufPropertyType.IObject
+  | IProtobufPropertyType.IMap;
+export namespace IProtobufPropertyType {
+  export interface IByte extends IProtobufSchema.IByte {
+    index: number;
+  }
+  export interface IBoolean extends IProtobufSchema.IBoolean {
+    index: number;
+  }
+  export interface IBigint extends IProtobufSchema.IBigint {
+    index: number;
+  }
+  export interface INumber extends IProtobufSchema.INumber {
+    index: number;
+  }
+  export interface IString extends IProtobufSchema.IString {
+    index: number;
+  }
+  export interface IArray extends IProtobufSchema.IArray {
+    index: number;
+  }
+  export interface IObject extends IProtobufSchema.IObject {
+    index: number;
+  }
+  export interface IMap extends IProtobufSchema.IMap {
+    index: number;
+  }
+}

package/src/schemas/protobuf/IProtobufSchema.ts

@@ -0,0 +1,50 @@
+import { MetadataArrayType } from "../metadata/MetadataArrayType";
+import { MetadataMap } from "../metadata/MetadataMap";
+import { MetadataObjectType } from "../metadata/MetadataObjectType";
+
+export type IProtobufSchema =
+  | IProtobufSchema.IByte
+  | IProtobufSchema.IBoolean
+  | IProtobufSchema.IBigint
+  | IProtobufSchema.INumber
+  | IProtobufSchema.IString
+  | IProtobufSchema.IArray
+  | IProtobufSchema.IObject
+  | IProtobufSchema.IMap;
+export namespace IProtobufSchema {
+  export interface IByte {
+    type: "bytes";
+  }
+  export interface IBoolean {
+    type: "bool";
+  }
+  export interface IBigint {
+    type: "bigint";
+    name: "int64" | "uint64";
+  }
+  export interface INumber {
+    type: "number";
+    name: "int32" | "int64" | "uint32" | "uint64" | "float" | "double";
+  }
+  export interface IString {
+    type: "string";
+  }
+  export interface IArray {
+    type: "array";
+    array: MetadataArrayType;
+    value: Exclude<IProtobufSchema, IArray | IMap>;
+  }
+  export interface IObject {
+    type: "object";
+    object: MetadataObjectType;
+  }
+  export interface IMap {
+    type: "map";
+    map: MetadataMap | MetadataObjectType;
+    key:
+      | IProtobufSchema.IBoolean
+      | IProtobufSchema.INumber
+      | IProtobufSchema.IString;
+    value: Exclude<IProtobufSchema, IArray | IMap>;
+  }
+}

package/src/schemas/protobuf/index.ts

@@ -0,0 +1,3 @@
+export * from "./IProtobufProperty";
+export * from "./IProtobufPropertyType";
+export * from "./IProtobufSchema";

package/src/typings/Writable.ts

@@ -0,0 +1,11 @@
+import { ClassProperties } from "@typia/interface";
+
+export type Writable<T extends object> = {
+  -readonly [P in keyof T]: T[P];
+};
+
+export function Writable<T extends object>(
+  elem: T,
+): Writable<ClassProperties<T>> {
+  return elem as any;
+}

package/src/utils/PatternUtil.ts

@@ -0,0 +1,29 @@
+export namespace PatternUtil {
+  export const fix = (str: string): string => {
+    const first: number = str.indexOf(STRING);
+    const last: number = str.lastIndexOf(STRING);
+    return [
+      first === -1 || none("(")(str.slice(0, first)) ? "^" : "",
+      str,
+      last === -1 || none(")")(str.slice(last + STRING.length)) ? "$" : "",
+    ].join("");
+  };
+
+  export const escape = (str: string): string => {
+    return str.replace(/[|\\/{}()[\]^$+*?.]/g, "\\$&").replace(/-/g, "\\x2d");
+  };
+
+  export const NUMBER =
+    "[+-]?" + // optional sign
+    "\\d+(?:\\.\\d+)?" + // integer or decimal
+    "(?:[eE][+-]?\\d+)?"; // optional exponent
+  export const BOOLEAN = "true|false";
+  export const STRING = "(.*)";
+}
+
+const none =
+  (parenthesis: string) =>
+  (str: string): boolean => {
+    for (const ch of str) if (ch !== parenthesis) return true;
+    return false;
+  };

package/src/utils/ProtobufNameEncoder.ts

@@ -0,0 +1,32 @@
+export namespace ProtobufNameEncoder {
+  export const encode = (str: string): string => {
+    for (const [before, after] of REPLACERS)
+      str = str.split(before).join(after);
+    return str;
+  };
+
+  export const decode = (str: string): string => {
+    for (const [before, after] of REPLACERS)
+      if (after !== "") str = str.split(after).join(before);
+    return str;
+  };
+}
+
+const REPLACERS: [string, string][] = [
+  ["$", "_dollar_"],
+  ["&", "_and_"],
+  ["|", "_or_"],
+  ["{", "_blt_"],
+  ["}", "_bgt_"],
+  ["<", "_lt_"],
+  [">", "_gt_"],
+  ["(", "_lp_"],
+  [")", "_rp_"],
+  ["[", "_alt_"],
+  ["]", "_agt_"],
+  [",", "_comma_"],
+  ["`", "_backquote_"],
+  ["'", "_singlequote_"],
+  ['"', "_doublequote_"],
+  [" ", "_space_"],
+];