typia 9.7.0 → 9.7.2

package/src/schemas/metadata/Metadata.ts

@@ -51,9 +51,7 @@ export class Metadata {
   /* -----------------------------------------------------------
     CONSTRUCTORS
   ----------------------------------------------------------- */
-  /**
-   * @hidden
-   */
+  /** @ignore */
   private constructor(props: ClassProperties<Metadata>) {
     this.any = props.any;
     this.required = props.required;
@@ -77,16 +75,12 @@ export class Metadata {
     this.maps = props.maps;
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public static create(props: ClassProperties<Metadata>): Metadata {
     return new Metadata(props);
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public static initialize(parentResolved: boolean = false): Metadata {
     const meta: Metadata = Metadata.create({
       any: false,
@@ -262,9 +256,7 @@ export class Metadata {
     );
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public isSequence(): boolean {
     return (this.is_sequence_ ??= (() => {
       const exists = (tags: IMetadataTypeTag[][]): boolean =>
@@ -303,9 +295,7 @@ export class Metadata {
     return this.required === true && this.optional === false;
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public isUnionBucket(): boolean {
     const size: number = this.bucket();
     const emended: number =
@@ -313,9 +303,7 @@ export class Metadata {
     return emended > 1;
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public getSoleLiteral(): string | null {
     if (
       this.size() === 1 &&
@@ -331,9 +319,7 @@ export class Metadata {
     return this.getSoleLiteral() !== null;
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public isParentResolved(): boolean {
     return this.parent_resolved_;
   }
@@ -513,9 +499,7 @@ export namespace Metadata {
     return true;
   };
 
-  /**
-   * @internal
-   */
+  /** @internal */
   export const merge = (x: Metadata, y: Metadata): Metadata => {
     const output: Metadata = Metadata.create({
       any: x.any || y.any,
@@ -595,9 +579,7 @@ export namespace Metadata {
     return output;
   };
 
-  /**
-   * @internal
-   */
+  /** @internal */
   export const unalias = (w: Metadata) => {
     const visited: Set<Metadata> = new Set();
     while (

package/src/schemas/metadata/MetadataAliasType.ts

@@ -15,9 +15,7 @@ export class MetadataAliasType {
   /* -----------------------------------------------------------
         CONSTRUCTORS
     ----------------------------------------------------------- */
-  /**
-   * @hidden
-   */
+  /** @ignore */
   private constructor(props: ClassProperties<MetadataAliasType>) {
     this.name = props.name;
     this.value = props.value;
@@ -27,18 +25,14 @@ export class MetadataAliasType {
     this.nullables = props.nullables;
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public static create(
     props: ClassProperties<MetadataAliasType>,
   ): MetadataAliasType {
     return new MetadataAliasType(props);
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public static _From_without_value(props: Omit<IMetadataAliasType, "value">) {
     return MetadataAliasType.create({
       name: props.name,

package/src/schemas/metadata/MetadataApplication.ts

@@ -8,17 +8,13 @@ export class MetadataApplication {
   public readonly metadatas: Metadata[];
   public readonly components: MetadataComponents;
 
-  /**
-   * @hidden
-   */
+  /** @ignore */
   private constructor(props: ClassProperties<MetadataApplication>) {
     this.metadatas = props.metadatas;
     this.components = props.components;
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public static create(
     props: ClassProperties<MetadataApplication>,
   ): MetadataApplication {

package/src/schemas/metadata/MetadataArray.ts

@@ -10,9 +10,7 @@ export class MetadataArray {
 
   private name_?: string;
 
-  /**
-   * @hidden
-   */
+  /** @ignore */
   private constructor(props: ClassProperties<MetadataArray>) {
     this.type = props.type;
     this.tags = props.tags;

package/src/schemas/metadata/MetadataArrayType.ts

@@ -10,9 +10,7 @@ export class MetadataArrayType {
   public readonly recursive: boolean;
   public readonly index: number | null;
 
-  /**
-   * @hidden
-   */
+  /** @ignore */
   private constructor(props: ClassProperties<MetadataArrayType>) {
     this.name = props.name;
     this.value = props.value;
@@ -21,9 +19,7 @@ export class MetadataArrayType {
     this.nullables = props.nullables;
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public static _From_without_value(
     props: Omit<IMetadataArrayType, "value">,
   ): MetadataArrayType {
@@ -36,9 +32,7 @@ export class MetadataArrayType {
     });
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public static create(
     props: ClassProperties<MetadataArrayType>,
   ): MetadataArrayType {

package/src/schemas/metadata/MetadataAtomic.ts

@@ -9,9 +9,7 @@ export class MetadataAtomic {
 
   private name_?: string;
 
-  /**
-   * @internal
-   */
+  /** @internal */
   private constructor(props: ClassProperties<MetadataAtomic>) {
     this.type = props.type;
     this.tags = props.tags;

package/src/schemas/metadata/MetadataEscaped.ts

@@ -8,17 +8,13 @@ export class MetadataEscaped {
   public readonly original: Metadata;
   public readonly returns: Metadata;
 
-  /**
-   * @hidden
-   */
+  /** @ignore */
   private constructor(props: ClassProperties<MetadataEscaped>) {
     this.original = props.original;
     this.returns = props.returns;
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public static from(
     props: IMetadataEscaped,
     dict: IMetadataDictionary,
@@ -29,9 +25,7 @@ export class MetadataEscaped {
     });
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public static create(
     props: ClassProperties<MetadataEscaped>,
   ): MetadataEscaped {

package/src/schemas/metadata/MetadataFunction.ts

@@ -10,18 +10,14 @@ export class MetadataFunction {
   public output: Metadata;
   public async: boolean;
 
-  /**
-   * @hidden
-   */
+  /** @ignore */
   private constructor(props: ClassProperties<MetadataFunction>) {
     this.parameters = props.parameters;
     this.output = props.output;
     this.async = props.async;
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public static create(
     props: ClassProperties<MetadataFunction>,
   ): MetadataFunction {

package/src/schemas/metadata/MetadataObject.ts

@@ -9,9 +9,7 @@ export class MetadataObject {
   public readonly tags: IMetadataTypeTag[][];
   private name_?: string;
 
-  /**
-   * @hidden
-   */
+  /** @ignore */
   private constructor(props: ClassProperties<MetadataObject>) {
     this.type = props.type;
     this.tags = props.tags;

package/src/schemas/metadata/MetadataObjectType.ts

@@ -15,22 +15,16 @@ export class MetadataObjectType {
   public recursive: boolean;
   public nullables: boolean[] = [];
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public tagged_: boolean = false;
 
-  /**
-   * @internal
-   */
+  /** @internal */
   private literal_?: boolean;
 
   /* -----------------------------------------------------------
         CONSTRUCTORS
     ----------------------------------------------------------- */
-  /**
-   * @hidden
-   */
+  /** @ignore */
   private constructor(
     props: Omit<ClassProperties<MetadataObjectType>, "tagged_">,
   ) {
@@ -47,18 +41,14 @@ export class MetadataObjectType {
     this.tagged_ = false;
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public static create(
     props: Omit<ClassProperties<MetadataObjectType>, "tagged_">,
   ) {
     return new MetadataObjectType(props);
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public static _From_without_properties(
     obj: IMetadataObjectType,
   ): MetadataObjectType {
@@ -120,9 +110,7 @@ export class MetadataObjectType {
   }
 }
 
-/**
- * @internal
- */
+/** @internal */
 export namespace MetadataObjectType {
   export const intersects = (
     x: MetadataObjectType,

package/src/schemas/metadata/MetadataParameter.ts

@@ -22,9 +22,7 @@ export class MetadataParameter {
     this.tsType = props.tsType;
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public static create(
     props: ClassProperties<MetadataParameter>,
   ): MetadataParameter {

package/src/schemas/metadata/MetadataProperty.ts

@@ -17,9 +17,7 @@ export class MetadataProperty {
   /* -----------------------------------------------------------
         CONSTRUCTORS
     ----------------------------------------------------------- */
-  /**
-   * @hidden
-   */
+  /** @ignore */
   private constructor(props: ClassProperties<MetadataProperty>) {
     this.key = props.key;
     this.value = props.value;
@@ -27,18 +25,14 @@ export class MetadataProperty {
     this.jsDocTags = props.jsDocTags;
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public static create(
     props: ClassProperties<MetadataProperty>,
   ): MetadataProperty {
     return new MetadataProperty(props);
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public static from(property: IMetadataProperty, dict: IMetadataDictionary) {
     return MetadataProperty.create({
       key: Metadata.from(property.key, dict),

package/src/schemas/metadata/MetadataTemplate.ts

@@ -36,9 +36,7 @@ export class MetadataTemplate {
     return (this.name_ ??= getName(this));
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public getBaseName(): string {
     return (
       "`" +

package/src/schemas/metadata/MetadataTuple.ts

@@ -8,17 +8,13 @@ export class MetadataTuple {
   public readonly type: MetadataTupleType;
   public readonly tags: IMetadataTypeTag[][];
 
-  /**
-   * @hidden
-   */
+  /** @ignore */
   private constructor(props: ClassProperties<MetadataTuple>) {
     this.type = props.type;
     this.tags = props.tags;
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public static create(props: ClassProperties<MetadataTuple>): MetadataTuple {
     return new MetadataTuple(props);
   }

package/src/schemas/metadata/MetadataTupleType.ts

@@ -11,14 +11,10 @@ export class MetadataTupleType {
   public readonly recursive: boolean;
   public readonly nullables: boolean[];
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public of_map?: boolean;
 
-  /**
-   * @internal
-   */
+  /** @internal */
   private constructor(props: ClassProperties<MetadataTupleType>) {
     this.name = props.name;
     this.elements = props.elements;
@@ -27,9 +23,7 @@ export class MetadataTupleType {
     this.nullables = props.nullables;
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public static _From_without_elements(
     props: Omit<IMetadataTupleType, "elements">,
   ): MetadataTupleType {

package/src/tags/Constant.ts

@@ -1,5 +1,37 @@
 import { TagBase } from "./TagBase";
 
+/**
+ * Constant tag that adds title and description metadata to literal types.
+ *
+ * This tag enhances literal values with human-readable documentation without
+ * changing their runtime type. It's particularly useful for enum-like values
+ * where you want to provide context about what each value represents.
+ *
+ * The metadata appears in generated JSON Schema, making API documentation more
+ * descriptive and helping developers understand the meaning of specific
+ * constant values.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   ```typescript
+ *   type Status =
+ *     | Constant<"active", { title: "Active", description: "User is currently active" }>
+ *     | Constant<"inactive", { title: "Inactive", description: "User account is disabled" }>
+ *     | Constant<"pending", { title: "Pending", description: "Awaiting verification" }>;
+ *   ```;
+ *
+ * @example
+ *   ```typescript
+ *   interface Config {
+ *     debugLevel: Constant<0, { title: "Off", description: "No debug output" }>
+ *               | Constant<1, { title: "Basic", description: "Basic logging" }>
+ *               | Constant<2, { title: "Verbose", description: "Detailed debug info" }>;
+ *   }
+ *   ```;
+ *
+ * @template Value The literal value (boolean, number, string, or bigint)
+ * @template Content Metadata with optional title and description
+ */
 export type Constant<
   Value extends boolean | number | string | bigint,
   Content extends {

package/src/tags/ContentMediaType.ts

@@ -1,5 +1,22 @@
 import { TagBase } from "./TagBase";
 
+/**
+ * String content media type constraint tag.
+ *
+ * Specifies the MIME type of string content for proper interpretation. This tag
+ * serves as metadata to indicate how the string content should be interpreted,
+ * but does not perform validation on the content itself.
+ *
+ * Examples: type JsonData = string & ContentMediaType<"application/json">; //
+ * JSON string type Base64Image = string & ContentMediaType<"image/png">; //
+ * Base64 PNG type XmlContent = string & ContentMediaType<"application/xml">; //
+ * XML data
+ *
+ * Common MIME types: application/json, text/html, image/jpeg, image/png,
+ * application/pdf, text/plain, application/xml, and many more.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export type ContentMediaType<Value extends string> = TagBase<{
   target: "string";
   kind: "contentMediaType";

package/src/tags/Default.ts

@@ -1,5 +1,35 @@
 import { TagBase } from "./TagBase";
 
+/**
+ * Default value tag that specifies a default value for properties.
+ *
+ * When a property is not provided during validation, this tag instructs typia
+ * to use the specified default value. This is useful for optional properties
+ * that should have a specific fallback value.
+ *
+ * Supported types: boolean, bigint, number, and string primitives. Note:
+ * Default values are applied during validation, not at compile time.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   ```typescript
+ *   interface User {
+ *     name: string;
+ *     active: boolean & Default<true>;  // defaults to true if not provided
+ *     retries: number & Default<3>;     // defaults to 3 if not provided
+ *   }
+ *   ```;
+ *
+ * @example
+ *   ```typescript
+ *   interface Config {
+ *     timeout: bigint & Default<5000n>;    // defaults to 5000n
+ *     prefix: string & Default<"user_">;   // defaults to "user_"
+ *   }
+ *   ```;
+ *
+ * @template Value The default value (boolean, bigint, number, or string)
+ */
 export type Default<Value extends boolean | bigint | number | string> =
   TagBase<{
     target: Value extends boolean

package/src/tags/Example.ts

@@ -1,5 +1,37 @@
 import { TagBase } from "./TagBase";
 
+/**
+ * Example value tag that provides a single example value for documentation.
+ *
+ * This tag adds an example value to your JSON Schema, which is useful for API
+ * documentation, client code generation, and helping developers understand
+ * expected data formats. The example doesn't affect runtime validation.
+ *
+ * Use Example for a single representative value. For multiple named examples,
+ * use the Examples tag instead.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   ```typescript
+ *   interface Product {
+ *     name: string & Example<"iPhone 15 Pro">;
+ *     price: number & Example<999.99>;
+ *     inStock: boolean & Example<true>;
+ *   }
+ *   ```;
+ *
+ * @example
+ *   ```typescript
+ *   interface User {
+ *     profile: {
+ *       bio: string;
+ *       tags: string[];
+ *     } & Example<{ bio: "Software engineer", tags: ["typescript", "react"] }>;
+ *   }
+ *   ```;
+ *
+ * @template Value The example value (primitives, objects, arrays, or null)
+ */
 export type Example<
   Value extends
     | boolean

package/src/tags/Examples.ts

@@ -1,5 +1,45 @@
 import { TagBase } from "./TagBase";
 
+/**
+ * Multiple examples tag that provides named example values for documentation.
+ *
+ * Unlike the Example tag which provides a single example, Examples allows you
+ * to provide multiple labeled examples. This is particularly useful when you
+ * want to show different scenarios or use cases for the same type.
+ *
+ * The examples are added to JSON Schema as an object where keys are descriptive
+ * names and values are the example data. This helps in API documentation and
+ * test case generation.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   ```typescript
+ *   interface PaymentRequest {
+ *     amount: number & Examples<{
+ *       small: 10.50,
+ *       medium: 99.99,
+ *       large: 1000.00
+ *     }>;
+ *   }
+ *   ```;
+ *
+ * @example
+ *   ```typescript
+ *   interface UserStatus {
+ *     state: string & Examples<{
+ *       active: "active",
+ *       inactive: "inactive",
+ *       suspended: "suspended"
+ *     }>;
+ *     profile: object & Examples<{
+ *       basic: { name: "John", age: 25 },
+ *       detailed: { name: "Jane", age: 30, bio: "Developer", verified: true }
+ *     }>;
+ *   }
+ *   ```;
+ *
+ * @template Value A record object mapping example names to example values
+ */
 export type Examples<
   Value extends Record<
     string,

package/src/tags/ExclusiveMaximum.ts

@@ -1,5 +1,26 @@
 import { TagBase } from "./TagBase";
 
+/**
+ * Exclusive maximum value constraint tag.
+ *
+ * Enforces that a numeric value must be strictly less than the specified
+ * maximum (not equal). This constraint validates that the input value
+ * satisfies: input < maximum.
+ *
+ * Example usage:
+ *
+ * ```typescript
+ * type Discount = number & tags.ExclusiveMaximum<100>; // Must be < 100
+ * type ByteValue = bigint & tags.ExclusiveMaximum<256n>; // Must be < 256
+ * ```
+ *
+ * Note: This tag is mutually exclusive with Maximum. You cannot apply both
+ * ExclusiveMaximum and Maximum constraints to the same property.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @template Value - The exclusive maximum value constraint (number or bigint
+ *   literal)
+ */
 export type ExclusiveMaximum<Value extends number | bigint> = TagBase<{
   target: Value extends bigint ? "bigint" : "number";
   kind: "exclusiveMaximum";

package/src/tags/ExclusiveMinimum.ts

@@ -1,5 +1,26 @@
 import { TagBase } from "./TagBase";
 
+/**
+ * Exclusive minimum value constraint tag.
+ *
+ * Enforces that a numeric value must be strictly greater than the specified
+ * minimum (not equal). This constraint validates that the input value
+ * satisfies: input > minimum.
+ *
+ * Example usage:
+ *
+ * ```typescript
+ * type PositiveNumber = number & tags.ExclusiveMinimum<0>; // Must be > 0
+ * type LargeCount = bigint & tags.ExclusiveMinimum<999n>; // Must be > 999
+ * ```
+ *
+ * Note: This tag is mutually exclusive with Minimum. You cannot apply both
+ * ExclusiveMinimum and Minimum constraints to the same property.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @template Value - The exclusive minimum value constraint (number or bigint
+ *   literal)
+ */
 export type ExclusiveMinimum<Value extends number | bigint> = TagBase<{
   target: Value extends bigint ? "bigint" : "number";
   kind: "exclusiveMinimum";