@typia/interface 12.0.0-dev.20260225

package/src/http/IHttpResponse.ts

@@ -0,0 +1,42 @@
+/**
+ * HTTP response structure returned from server communication.
+ *
+ * `IHttpResponse` represents the complete HTTP response received from a remote
+ * server, containing the status code, response headers, and body. This
+ * interface is used by `@nestia/fetcher` to return structured response data
+ * from API calls.
+ *
+ * The {@link status} property contains the HTTP status code (e.g., 200, 404),
+ * {@link headers} contains all response headers (some may have multiple values),
+ * and {@link body} contains the parsed response body (typically JSON-decoded).
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface IHttpResponse {
+  /**
+   * HTTP status code of the response.
+   *
+   * Standard HTTP status codes indicating the result of the request. Common
+   * values: 200 (OK), 201 (Created), 400 (Bad Request), 401 (Unauthorized), 404
+   * (Not Found), 500 (Internal Server Error).
+   */
+  status: number;
+
+  /**
+   * Response headers from the server.
+   *
+   * Contains all HTTP headers returned by the server. Header values can be
+   * either a single string or an array of strings for headers that appear
+   * multiple times (e.g., `Set-Cookie`).
+   */
+  headers: Record<string, string | string[]>;
+
+  /**
+   * Parsed body content of the response.
+   *
+   * The response body after parsing. For JSON responses, this is the decoded
+   * JavaScript object. The actual type depends on the endpoint and response
+   * content-type.
+   */
+  body: unknown;
+}

package/src/http/index.ts

@@ -0,0 +1,7 @@
+export * from "./IHttpConnection";
+export * from "./IHttpLlmController";
+export * from "./IHttpLlmApplication";
+export * from "./IHttpLlmFunction";
+export * from "./IHttpMigrateApplication";
+export * from "./IHttpMigrateRoute";
+export * from "./IHttpResponse";

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from "./http/index";
+export * from "./schema/index";
+export * from "./openapi/index";
+export * from "./typings/index";
+export * from "./utils/index";
+export * from "./metadata/index";
+export * from "./protobuf/index";
+
+export * as tags from "./tags/index";

package/src/metadata/IJsDocTagInfo.ts

@@ -0,0 +1,25 @@
+/**
+ * JSDoc tag information extracted from TypeScript source.
+ *
+ * Represents a single JSDoc tag like `@param`, `@returns`, `@deprecated`, etc.
+ * Used throughout typia's metadata system to preserve documentation.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface IJsDocTagInfo {
+  /** Tag name without `@` prefix (e.g., `"param"`, `"returns"`). */
+  name: string;
+
+  /** Tag text content, if any. */
+  text?: IJsDocTagInfo.IText[];
+}
+export namespace IJsDocTagInfo {
+  /** Text segment within a JSDoc tag. */
+  export interface IText {
+    /** Text content. */
+    text: string;
+
+    /** Text kind (e.g., `"text"`, `"parameterName"`). */
+    kind: string;
+  }
+}

package/src/metadata/IMetadataComponents.ts

@@ -0,0 +1,24 @@
+import { IMetadataSchema } from "./IMetadataSchema";
+
+/**
+ * Shared type definitions for metadata schemas.
+ *
+ * `IMetadataComponents` stores reusable type definitions that can be referenced
+ * from {@link IMetadataSchema} via {@link IMetadataSchema.IReference}. This
+ * enables deduplication of complex types across multiple schemas.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface IMetadataComponents {
+  /** Object type definitions. */
+  objects: IMetadataSchema.IObjectType[];
+
+  /** Type alias definitions. */
+  aliases: IMetadataSchema.IAliasType[];
+
+  /** Array type definitions. */
+  arrays: IMetadataSchema.IArrayType[];
+
+  /** Tuple type definitions. */
+  tuples: IMetadataSchema.ITupleType[];
+}

package/src/metadata/IMetadataSchema.ts

@@ -0,0 +1,293 @@
+import { Atomic } from "../typings/Atomic";
+import { IJsDocTagInfo } from "./IJsDocTagInfo";
+import { IMetadataTypeTag } from "./IMetadataTypeTag";
+
+/**
+ * Metadata schema representing a TypeScript type's structure.
+ *
+ * `IMetadataSchema` is typia's internal type representation, capturing full
+ * TypeScript type information including unions, optionality, nullability, and
+ * type constraints. Used by `typia.reflect.schema<T>()` for runtime type
+ * introspection.
+ *
+ * Type categories:
+ *
+ * - Primitives: {@link atomics} (boolean, bigint, number, string)
+ * - Literals: {@link constants} (literal values like `"hello"` or `42`)
+ * - Templates: {@link templates} (template literal types)
+ * - Collections: {@link arrays}, {@link tuples}, {@link sets}, {@link maps}
+ * - Objects: {@link objects} (named object types)
+ * - Aliases: {@link aliases} (type aliases)
+ * - Natives: {@link natives} (built-in classes like Date, Uint8Array)
+ * - Functions: {@link functions} (function types)
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface IMetadataSchema {
+  /** Whether the type is `any`. */
+  any: boolean;
+
+  /** Whether the type is required (not `undefined`). */
+  required: boolean;
+
+  /** Whether the type is optional (`?` modifier). */
+  optional: boolean;
+
+  /** Whether the type is nullable (`null` included). */
+  nullable: boolean;
+
+  /** Function types in the union. */
+  functions: IMetadataSchema.IFunction[];
+
+  /** Primitive types (boolean, bigint, number, string) in the union. */
+  atomics: IMetadataSchema.IAtomic[];
+
+  /** Literal constant values in the union. */
+  constants: IMetadataSchema.IConstant[];
+
+  /** Template literal types in the union. */
+  templates: IMetadataSchema.ITemplate[];
+
+  /** Escaped type info (original and transformed). */
+  escaped: IMetadataSchema.IEscaped | null;
+
+  /** Rest element type for variadic tuples. */
+  rest: IMetadataSchema | null;
+
+  /** Array type references in the union. */
+  arrays: IMetadataSchema.IReference[];
+
+  /** Tuple type references in the union. */
+  tuples: IMetadataSchema.IReference[];
+
+  /** Object type references in the union. */
+  objects: IMetadataSchema.IReference[];
+
+  /** Type alias references in the union. */
+  aliases: IMetadataSchema.IReference[];
+
+  /** Native class references (Date, Uint8Array, etc.) in the union. */
+  natives: IMetadataSchema.IReference[];
+
+  /** Set types in the union. */
+  sets: IMetadataSchema.ISet[];
+
+  /** Map types in the union. */
+  maps: IMetadataSchema.IMap[];
+}
+export namespace IMetadataSchema {
+  /** Function type metadata. */
+  export interface IFunction {
+    /** Whether the function is async. */
+    async: boolean;
+
+    /** Function parameters. */
+    parameters: IParameter[];
+
+    /** Return type schema. */
+    output: IMetadataSchema;
+  }
+
+  /** Function parameter metadata. */
+  export interface IParameter {
+    /** Parameter name. */
+    name: string;
+
+    /** Parameter type schema. */
+    type: IMetadataSchema;
+
+    /** JSDoc description. */
+    description: string | null;
+
+    /** JSDoc tags. */
+    jsDocTags: IJsDocTagInfo[];
+  }
+
+  /** Primitive atomic type metadata. */
+  export interface IAtomic {
+    /** Primitive type kind. */
+    type: "boolean" | "bigint" | "number" | "string";
+
+    /** Type constraint tags (e.g., `@minimum`, `@format`). */
+    tags: IMetadataTypeTag[][];
+  }
+
+  /** Literal constant type metadata. */
+  export type IConstant =
+    | IConstant.IBase<"boolean">
+    | IConstant.IBase<"number">
+    | IConstant.IBase<"string">
+    | IConstant.IBase<"bigint">;
+  export namespace IConstant {
+    /** Base interface for constant types. */
+    export interface IBase<Type extends Atomic.Literal> {
+      /** Constant type kind. */
+      type: Type;
+
+      /** Literal values in the union. */
+      values: IValue<Atomic.Mapper[Type]>[];
+    }
+
+    /** Single constant value metadata. */
+    export interface IValue<T extends Atomic.Type> {
+      /** The literal value. */
+      value: T;
+
+      /** Type constraint tags. */
+      tags: IMetadataTypeTag[][];
+
+      /** JSDoc description. */
+      description?: string | null;
+
+      /** JSDoc tags. */
+      jsDocTags?: IJsDocTagInfo[];
+    }
+  }
+
+  /** Template literal type metadata. */
+  export interface ITemplate {
+    /** Template parts as schemas. */
+    row: IMetadataSchema[];
+
+    /** Type constraint tags. */
+    tags: IMetadataTypeTag[][];
+  }
+
+  /** Escaped type metadata (for special transformations). */
+  export interface IEscaped {
+    /** Original type before escaping. */
+    original: IMetadataSchema;
+
+    /** Transformed return type. */
+    returns: IMetadataSchema;
+  }
+
+  /** Type alias definition. */
+  export interface IAliasType {
+    /** Alias name. */
+    name: string;
+
+    /** Underlying type schema. */
+    value: IMetadataSchema;
+
+    /** Nullability per reference site. */
+    nullables: boolean[];
+
+    /** JSDoc description. */
+    description: string | null;
+
+    /** JSDoc tags. */
+    jsDocTags: IJsDocTagInfo[];
+
+    /** Whether the alias is recursive. */
+    recursive: boolean;
+  }
+
+  /** Array type definition. */
+  export interface IArrayType {
+    /** Array type name. */
+    name: string;
+
+    /** Element type schema. */
+    value: IMetadataSchema;
+
+    /** Nullability per reference site. */
+    nullables: boolean[];
+
+    /** Whether the array type is recursive. */
+    recursive: boolean;
+
+    /** Index in components (for deduplication). */
+    index: number | null;
+  }
+
+  /** Tuple type definition. */
+  export interface ITupleType {
+    /** Tuple type name. */
+    name: string;
+
+    /** Element schemas in order. */
+    elements: IMetadataSchema[];
+
+    /** Index in components (for deduplication). */
+    index: number | null;
+
+    /** Whether the tuple type is recursive. */
+    recursive: boolean;
+
+    /** Nullability per reference site. */
+    nullables: boolean[];
+  }
+
+  /** Object type definition. */
+  export interface IObjectType {
+    /** Object type name. */
+    name: string;
+
+    /** Object properties. */
+    properties: IProperty[];
+
+    /** JSDoc description. */
+    description?: undefined | string;
+
+    /** JSDoc tags. */
+    jsDocTags: IJsDocTagInfo[];
+
+    /** Index in components (for deduplication). */
+    index: number;
+
+    /** Whether the object type is recursive. */
+    recursive: boolean;
+
+    /** Nullability per reference site. */
+    nullables: boolean[];
+  }
+
+  /** Object property metadata. */
+  export interface IProperty {
+    /** Property key schema (string or symbol). */
+    key: IMetadataSchema;
+
+    /** Property value schema. */
+    value: IMetadataSchema;
+
+    /** JSDoc description. */
+    description: string | null;
+
+    /** JSDoc tags. */
+    jsDocTags: IJsDocTagInfo[];
+
+    /** Property mutability (`readonly` or mutable). */
+    mutability?: "readonly" | null | undefined;
+  }
+
+  /** Map type metadata. */
+  export interface IMap {
+    /** Key type schema. */
+    key: IMetadataSchema;
+
+    /** Value type schema. */
+    value: IMetadataSchema;
+
+    /** Type constraint tags. */
+    tags: IMetadataTypeTag[][];
+  }
+
+  /** Set type metadata. */
+  export interface ISet {
+    /** Element type schema. */
+    value: IMetadataSchema;
+
+    /** Type constraint tags. */
+    tags: IMetadataTypeTag[][];
+  }
+
+  /** Reference to a named type in components. */
+  export interface IReference {
+    /** Referenced type name. */
+    name: string;
+
+    /** Type constraint tags. */
+    tags: IMetadataTypeTag[][];
+  }
+}

package/src/metadata/IMetadataSchemaCollection.ts

@@ -0,0 +1,20 @@
+import { IMetadataComponents } from "./IMetadataComponents";
+import { IMetadataSchema } from "./IMetadataSchema";
+
+/**
+ * Collection of metadata schemas for multiple types.
+ *
+ * `IMetadataSchemaCollection` contains metadata schemas generated from multiple
+ * TypeScript types via `typia.reflect.schemas<[T1, T2, ...]>()`. Each schema in
+ * {@link schemas} corresponds to one input type, while shared type definitions
+ * (objects, aliases, arrays, tuples) are stored in {@link components}.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface IMetadataSchemaCollection {
+  /** Array of metadata schemas, one per input type. */
+  schemas: IMetadataSchema[];
+
+  /** Shared type definitions referenced by schemas. */
+  components: IMetadataComponents;
+}

package/src/metadata/IMetadataSchemaUnit.ts

@@ -0,0 +1,20 @@
+import { IMetadataComponents } from "./IMetadataComponents";
+import { IMetadataSchema } from "./IMetadataSchema";
+
+/**
+ * Single unit of metadata schema for one type.
+ *
+ * `IMetadataSchemaUnit` contains a metadata schema generated from a single
+ * TypeScript type via `typia.reflect.schema<T>()`. The main schema is in
+ * {@link schema}, while shared type definitions (objects, aliases, arrays,
+ * tuples) are stored in {@link components}.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface IMetadataSchemaUnit {
+  /** Metadata schema for the target type. */
+  schema: IMetadataSchema;
+
+  /** Shared type definitions referenced by the schema. */
+  components: IMetadataComponents;
+}

package/src/metadata/IMetadataTypeTag.ts

@@ -0,0 +1,39 @@
+import type ts from "typescript";
+
+/**
+ * Type constraint tag metadata.
+ *
+ * Represents constraint tags like `@minimum`, `@format`, `@pattern` that are
+ * applied to types via typia's tag system. Used for validation and JSON schema
+ * generation.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface IMetadataTypeTag {
+  /** Target type this tag applies to. */
+  target: "boolean" | "bigint" | "number" | "string" | "array" | "object";
+
+  /** Full tag name (e.g., `"@typia/tag/Minimum"`). */
+  name: string;
+
+  /** Tag kind identifier (e.g., `"minimum"`, `"format"`). */
+  kind: string;
+
+  /**
+   * Exclusivity: `true` for unique tags, or array of mutually exclusive tag
+   * kinds.
+   */
+  exclusive: boolean | string[];
+
+  /** Tag value (e.g., `0` for `Minimum<0>`, `"email"` for `Format<"email">`). */
+  value?: any;
+
+  /** Validation expression template. */
+  validate?: string | undefined;
+
+  /** JSON schema fragment to merge. */
+  schema?: object | undefined;
+
+  /** @internal */
+  predicate?: (input: ts.Expression) => ts.Expression;
+}

package/src/metadata/index.ts

@@ -0,0 +1,6 @@
+export * from "./IJsDocTagInfo";
+export * from "./IMetadataComponents";
+export * from "./IMetadataSchema";
+export * from "./IMetadataSchemaCollection";
+export * from "./IMetadataSchemaUnit";
+export * from "./IMetadataTypeTag";