typia 9.7.0 → 9.7.2

package/src/tags/Format.ts

@@ -1,5 +1,33 @@
 import type { TagBase } from "./TagBase";
 
+/**
+ * String format constraint tag.
+ *
+ * Validates strings against predefined formats for common use cases. This tag
+ * provides built-in validation for standard string formats without needing to
+ * write custom regular expressions.
+ *
+ * Examples:
+ *
+ * ```ts
+ * Type Email = string & Format<"email">; // user@example.com
+ * Type WebURL = string & Format<"url">; // https://example.com
+ * Type DateTime = string & Format<"date-time">; // 2024-01-15T10:30:00Z
+ * ```
+ *
+ * Supported formats include:
+ *
+ * - Network: email, url, hostname, ipv4, ipv6, uri
+ * - Identifiers: uuid, byte, password
+ * - Date/Time: date, time, date-time, duration
+ * - Data: json-pointer, regex
+ * - Internationalized: idn-email, idn-hostname, iri
+ *
+ * Note: This tag is mutually exclusive with the Pattern tag. You cannot use
+ * both Format and Pattern on the same type.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export type Format<Value extends Format.Value> = TagBase<{
   target: "string";
   kind: "format";

package/src/tags/JsonSchemaPlugin.ts

@@ -1,5 +1,33 @@
 import { TagBase } from "./TagBase";
 
+/**
+ * Injects custom properties into generated JSON Schema.
+ *
+ * The JsonSchemaPlugin tag allows you to add vendor-specific extensions or
+ * custom metadata to the generated JSON Schema output. These properties are
+ * merged at the root level of the schema and are commonly used for
+ * documentation, tooling hints, or API-specific metadata. The custom properties
+ * only affect schema generation and do not impact runtime validation.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   ```typescript
+ *   // Add OpenAPI vendor extensions
+ *   type UserId = string & JsonSchemaPlugin<{
+ *     "x-internal-id": true,
+ *     "x-deprecated": "Use UUID instead"
+ *   }>;
+ *
+ *   // Add custom documentation metadata
+ *   type Price = number & JsonSchemaPlugin<{
+ *     "x-format": "currency",
+ *     "x-example": 19.99
+ *   }>;
+ *   ```
+ *
+ * @template Schema - Object containing custom properties to add to the JSON
+ *   Schema
+ */
 export type JsonSchemaPlugin<Schema extends object> = TagBase<{
   target: "string" | "boolean" | "bigint" | "number" | "array" | "object";
   kind: "jsonPlugin";

package/src/tags/MaxItems.ts

@@ -1,5 +1,24 @@
 import { TagBase } from "./TagBase";
 
+/**
+ * Maximum items validation tag for arrays.
+ *
+ * Enforces that an array contains at most the specified number of items. This
+ * tag is useful for limiting array sizes, such as restricting the number of
+ * uploaded files, limiting selections in a form, or capping the size of
+ * collections to prevent performance issues.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   // Allow maximum 5 file uploads
+ *   type FileList = File[] & MaxItems<5>;
+ *
+ * @example
+ *   // Limit tags to 10 items
+ *   type ProductTags = string[] & MaxItems<10>;
+ *
+ * @template Value - The maximum number of items allowed
+ */
 export type MaxItems<Value extends number> = TagBase<{
   target: "array";
   kind: "maxItems";

package/src/tags/MaxLength.ts

@@ -1,5 +1,18 @@
 import { TagBase } from "./TagBase";
 
+/**
+ * String maximum length constraint tag.
+ *
+ * Validates that a string's length is less than or equal to the specified
+ * value. This tag enforces an upper limit on the number of characters in a
+ * string.
+ *
+ * Examples: type ShortComment = string & MaxLength<200>; // Comment limited to
+ * 200 characters type ZipCode = string & MaxLength<10>; // Zip code with max 10
+ * characters
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export type MaxLength<Value extends number> = TagBase<{
   target: "string";
   kind: "maxLength";

package/src/tags/Maximum.ts

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

package/src/tags/MinItems.ts

@@ -1,5 +1,24 @@
 import { TagBase } from "./TagBase";
 
+/**
+ * Minimum items validation tag for arrays.
+ *
+ * Enforces that an array contains at least the specified number of items. This
+ * tag is useful for ensuring arrays have a minimum length requirement, such as
+ * requiring at least one item in a list or a minimum number of selections in a
+ * multi-choice field.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   // Require at least 1 item in the array
+ *   type Tags = string[] & MinItems<1>;
+ *
+ * @example
+ *   // Require at least 3 selections
+ *   type MultipleChoice = number[] & MinItems<3>;
+ *
+ * @template Value - The minimum number of items required
+ */
 export type MinItems<Value extends number> = TagBase<{
   target: "array";
   kind: "minItems";

package/src/tags/MinLength.ts

@@ -1,5 +1,18 @@
 import { TagBase } from "./TagBase";
 
+/**
+ * String minimum length constraint tag.
+ *
+ * Validates that a string's length is greater than or equal to the specified
+ * value. This tag ensures that string values meet a minimum character count
+ * requirement.
+ *
+ * Examples: type Username = string & MinLength<3>; // Username must be at least
+ * 3 characters type Password = string & MinLength<8>; // Password must be at
+ * least 8 characters
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export type MinLength<Value extends number> = TagBase<{
   target: "string";
   kind: "minLength";

package/src/tags/Minimum.ts

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

package/src/tags/MultipleOf.ts

@@ -1,5 +1,26 @@
 import { TagBase } from "./TagBase";
 
+/**
+ * Multiple of constraint tag.
+ *
+ * Enforces that a numeric value must be an exact multiple of the specified
+ * divisor. This constraint validates that the input value satisfies: input %
+ * divisor === 0.
+ *
+ * Example usage:
+ *
+ * ```typescript
+ * type EvenNumber = number & tags.MultipleOf<2>; // Must be even (2, 4, 6, ...)
+ * type DollarAmount = number & tags.MultipleOf<0.01>; // Must be in cents
+ * ```
+ *
+ * Common use cases include validating even/odd numbers, currency amounts, time
+ * intervals, or any value that must align to specific increments.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @template Value - The divisor value that input must be a multiple of (number
+ *   or bigint literal)
+ */
 export type MultipleOf<Value extends number | bigint> = TagBase<{
   target: Value extends bigint ? "bigint" : "number";
   kind: "multipleOf";

package/src/tags/Pattern.ts

@@ -1,5 +1,23 @@
 import { TagBase } from "./TagBase";
 
+/**
+ * String pattern (regular expression) constraint tag.
+ *
+ * Validates that a string matches a specified regular expression pattern. Use
+ * this tag to enforce custom string formats through regex validation.
+ *
+ * Examples:
+ *
+ * ```ts
+ * type PhoneNumber = string & Pattern<"^\d{3}-\d{3}-\d{4}$">; // 123-456-7890
+ * type HexColor = string & Pattern<"^#[0-9A-Fa-f]{6}$">; // #FF5733
+ * ```
+ *
+ * Note: This tag is mutually exclusive with the Format tag. You cannot use both
+ * Pattern and Format on the same type.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export type Pattern<Value extends string> = TagBase<{
   target: "string";
   kind: "pattern";

package/src/tags/Sequence.ts

@@ -1,5 +1,32 @@
 import { TagBase } from "./TagBase";
 
+/**
+ * Assigns unique field numbers for Protocol Buffer serialization.
+ *
+ * In Protocol Buffer encoding, each field in a message must have a unique
+ * numeric identifier. The Sequence tag assigns these field numbers to
+ * TypeScript properties, enabling proper Protocol Buffer serialization and
+ * deserialization. Field numbers 1-15 require only one byte to encode, making
+ * them ideal for frequently used fields. Numbers 19000-19999 are reserved by
+ * the Protocol Buffer specification and should not be used.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   ```typescript
+ *   interface User {
+ *     id: string & Sequence<1>;        // Most frequent field uses 1
+ *     email: string & Sequence<2>;     // Common fields use low numbers
+ *     createdAt: number & Sequence<3>;
+ *     metadata?: object & Sequence<10>; // Optional fields work too
+ *   }
+ *
+ *   // Generate Protocol Buffer message
+ *   const message = typia.protobuf.message<User>();
+ *   ```
+ *
+ * @template N - Field number (positive integer from 1 to 536,870,911, excluding
+ *   19000-19999)
+ */
 export type Sequence<N extends number> = TagBase<{
   target: "boolean" | "bigint" | "number" | "string" | "array" | "object";
   kind: "sequence";

package/src/tags/TagBase.ts

@@ -1,3 +1,24 @@
+/**
+ * Base type for all validation tags in typia.
+ *
+ * TagBase provides the foundation for all typia's validation tags. It attaches
+ * metadata to TypeScript types that typia's transformer processes at
+ * compile-time to generate optimized runtime validation code.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   ```typescript
+ *   // Custom tag example
+ *   type MyCustomTag<Value extends number> = TagBase<{
+ *   target: "number";
+ *   kind: "MyCustom";
+ *   value: Value;
+ *   validate: `$input === ${Value}`;
+ *   }>;
+ *   ```
+ *
+ * @template Props - Tag properties that define validation behavior
+ */
 export type TagBase<
   Props extends TagBase.IProps<any, any, any, any, any, any>,
 > = {
@@ -9,6 +30,11 @@ export type TagBase<
   "typia.tag"?: Props;
 };
 export namespace TagBase {
+  /**
+   * Properties interface for validation tags.
+   *
+   * @author Jeongho Nam - https://github.com/samchon
+   */
   export interface IProps<
     Target extends
       | "boolean"
@@ -30,30 +56,26 @@ export namespace TagBase {
     /**
      * Target type.
      *
-     * If user tries to adapt this tag to a different type, it would be a compile
-     * error.
+     * If user tries to adapt this tag to a different type, it would be a
+     * compile error.
      *
-     * For example, you've configured target type as `string`, but user adapted it
-     * onto a `number` type (`number & YourCustomTag<Value>`), then it would be
-     * blocked by TypeScript compiler.
+     * For example, you've configured target type as `string`, but user adapted
+     * it onto a `number` type (`number & YourCustomTag<Value>`), then it would
+     * be blocked by TypeScript compiler.
      */
     target: Target;
 
-    /**
-     * What kind of tag is this?
-     */
+    /** What kind of tag is this? */
     kind: Kind;
 
-    /**
-     * Value to be configured by user.
-     */
+    /** Value to be configured by user. */
     value: Value;
 
     /**
      * Validation script.
      *
-     * This script would be inserted into the generated validation function.
-     * In here script, target variable name must be `$input`. The variable name
+     * This script would be inserted into the generated validation function. In
+     * here script, target variable name must be `$input`. The variable name
      * `$input` would be transformed to the suitable when compilation.
      *
      * Also, If you've take a mistake on this script, compile error would be
@@ -67,16 +89,14 @@ export namespace TagBase {
      *
      * If this property configured as `true`, same {@link kind} tag cannot be
      * duplicated in the target type. Otherwise, if you've configured this
-     * property as string array, all of the {@link kind} value assigned
-     * tags cannot be compatible in the target type.
+     * property as string array, all of the {@link kind} value assigned tags
+     * cannot be compatible in the target type.
      *
      * @default false
      */
     exclusive?: Exclusive | string[];
 
-    /**
-     * Additional schema info assigned to the {@link IJsonSchema} object.
-     */
+    /** Additional schema info assigned to the {@link IJsonSchema} object. */
     schema?: Schema;
   }
 }

package/src/tags/Type.ts

@@ -1,5 +1,32 @@
 import { TagBase } from "./TagBase";
 
+/**
+ * Type tag for specifying numeric bit-width representations.
+ *
+ * Constrains numeric types to specific bit-width formats used in systems
+ * programming and protocol buffers. Ensures numbers conform to
+ * platform-specific representations.
+ *
+ * Supported types:
+ *
+ * - `int32`: 32-bit signed integer (-2^31 to 2^31-1)
+ * - `uint32`: 32-bit unsigned integer (0 to 2^32-1)
+ * - `int64`: 64-bit signed integer (supports both bigint and number)
+ * - `uint64`: 64-bit unsigned integer (supports both bigint and number)
+ * - `float`: 32-bit floating point (single precision)
+ * - `double`: 64-bit floating point (double precision, default JS number)
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   ```typescript
+ *   type Score = number & Type<"int32">;      // -2,147,483,648 to 2,147,483,647
+ *   type UserId = number & Type<"uint32">;    // 0 to 4,294,967,295
+ *   type FileSize = bigint & Type<"int64">;   // Large file sizes
+ *   type Coordinate = number & Type<"double">; // High precision coordinates
+ *   ```
+ *
+ * @template Value - The numeric type representation
+ */
 export type Type<
   Value extends "int32" | "uint32" | "int64" | "uint64" | "float" | "double",
 > = TagBase<{

package/src/tags/UniqueItems.ts

@@ -1,5 +1,25 @@
 import { TagBase } from "./TagBase";
 
+/**
+ * Unique items validation tag for arrays.
+ *
+ * Enforces that all items in an array are unique, preventing duplicate values.
+ * Uniqueness is determined using strict equality (===) for primitives and deep
+ * structural comparison for objects and arrays. This means two objects with the
+ * same properties and values are considered duplicates.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   // Ensure all IDs are unique
+ *   type UserIds = number[] & UniqueItems;
+ *
+ * @example
+ *   // Prevent duplicate email addresses
+ *   type EmailList = string[] & UniqueItems;
+ *
+ * @template Value - Boolean flag to enable/disable uniqueness validation
+ *   (defaults to true)
+ */
 export type UniqueItems<Value extends boolean = true> = TagBase<{
   target: "array";
   kind: "uniqueItems";

package/src/tags/internal/FormatCheatSheet.ts

@@ -1,9 +1,7 @@
 const RegexCall = <Text extends string>(text: Text) =>
   `${text}.test($input)` as const;
 
-/**
- * @reference https://github.dev/ajv-validator/ajv-formats/blob/master/src/formats.ts
- */
+/** @reference https://github.dev/ajv-validator/ajv-formats/blob/master/src/formats.ts */
 export const FormatCheatSheet = {
   // SPECIAL CHARACTERS
   byte: RegexCall(

package/src/transformers/ITransformOptions.ts

@@ -2,16 +2,20 @@ export interface ITransformOptions {
   /**
    * Whether to validate finite number or not.
    *
-   * If configured true, number typed values would be validated by Number.isNaN().
+   * If configured true, number typed values would be validated by
+   * Number.isNaN().
    *
-   * However, whatever you configure, it would be ignored when marshaling or parsing.
+   * However, whatever you configure, it would be ignored when marshaling or
+   * parsing.
    *
-   *   - when marshaling, always be true
-   *     - assertStringify()
-   *     - validateEncode()
-   *   - when parsing, always be false
-   *     - assertParse()
-   *     - isDecode()
+   * - When marshaling, always be true
+   *
+   *   - AssertStringify()
+   *   - ValidateEncode()
+   * - When parsing, always be false
+   *
+   *   - AssertParse()
+   *   - IsDecode()
    *
    * @default false
    */
@@ -20,17 +24,20 @@ export interface ITransformOptions {
   /**
    * Whether to validate finite number or not.
    *
-   * If configured true, number typed values would be validated by Number.isFinite().
+   * If configured true, number typed values would be validated by
+   * Number.isFinite().
    *
    * However, whatever you configure, it can be ignored in below case.
    *
-   *   - when `finite` option is true, this option would be ignored
-   *   - when marshaling, always be true
-   *     - assertStringify()
-   *     - validateEncode()
-   *   - when parsing, always be false
-   *     - assertParse()
-   *     - isDecode()
+   * - When `finite` option is true, this option would be ignored
+   * - When marshaling, always be true
+   *
+   *   - AssertStringify()
+   *   - ValidateEncode()
+   * - When parsing, always be false
+   *
+   *   - AssertParse()
+   *   - IsDecode()
    *
    * @default false
    */
@@ -39,7 +46,8 @@ export interface ITransformOptions {
   /**
    * Whether to validate functional type or not.
    *
-   * However, whatever you configure, it becomes false when marshaling or parsing.
+   * However, whatever you configure, it becomes false when marshaling or
+   * parsing.
    *
    * @default false
    */
@@ -49,8 +57,8 @@ export interface ITransformOptions {
    * Whether to check undefined value or not.
    *
    * JavaScript can assign `undefined` value to a specific property and it is an
-   * issue when validating without allowing superfluous properties. Should undefined
-   * value assigned superfluous property be allowed or not?
+   * issue when validating without allowing superfluous properties. Should
+   * undefined value assigned superfluous property be allowed or not?
    *
    * Note that, this option only works on {@link equals} function. Other function
    * like {@link assertEquals} or {@link validateEquals} would ignore this option