typia 9.7.0 → 9.7.1

package/src/tags/Format.ts

@@ -1,5 +1,29 @@
 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:
+ *   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,31 @@
 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.
+ *
+ * @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
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 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.
+ *
+ * @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
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export type MaxItems<Value extends number> = TagBase<{
   target: "array";
   kind: "maxItems";

package/src/tags/MaxLength.ts

@@ -1,5 +1,17 @@
 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,23 @@
 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.
+ *
+ * @template Value - The maximum value constraint (number or bigint literal)
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 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.
+ *
+ * @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
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export type MinItems<Value extends number> = TagBase<{
   target: "array";
   kind: "minItems";

package/src/tags/MinLength.ts

@@ -1,5 +1,17 @@
 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,23 @@
 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.
+ *
+ * @template Value - The minimum value constraint (number or bigint literal)
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export type Minimum<Value extends number | bigint> = TagBase<{
   target: Value extends bigint ? "bigint" : "number";
   kind: "minimum";

package/src/tags/MultipleOf.ts

@@ -1,5 +1,23 @@
 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.
+ *
+ * @template Value - The divisor value that input must be a multiple of (number or bigint literal)
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export type MultipleOf<Value extends number | bigint> = TagBase<{
   target: Value extends bigint ? "bigint" : "number";
   kind: "multipleOf";

package/src/tags/Pattern.ts

@@ -1,5 +1,20 @@
 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:
+ *   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,30 @@
 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.
+ *
+ * @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)
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export type Sequence<N extends number> = TagBase<{
   target: "boolean" | "bigint" | "number" | "string" | "array" | "object";
   kind: "sequence";

package/src/tags/TagBase.ts

@@ -1,3 +1,25 @@
+/**
+ * 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.
+ *
+ * @template Props - Tag properties that define validation behavior
+ *
+ * @example
+ * ```typescript
+ * // Custom tag example
+ * type MyCustomTag<Value extends number> = TagBase<{
+ *   target: "number";
+ *   kind: "MyCustom";
+ *   value: Value;
+ *   validate: `$input === ${Value}`;
+ * }>;
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export type TagBase<
   Props extends TagBase.IProps<any, any, any, any, any, any>,
 > = {
@@ -9,6 +31,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"

package/src/tags/Type.ts

@@ -1,5 +1,31 @@
 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)
+ *
+ * @template Value - The numeric type representation
+ *
+ * @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
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export type Type<
   Value extends "int32" | "uint32" | "int64" | "uint64" | "float" | "double",
 > = TagBase<{

package/src/tags/UniqueItems.ts

@@ -1,5 +1,24 @@
 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.
+ *
+ * @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)
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export type UniqueItems<Value extends boolean = true> = TagBase<{
   target: "array";
   kind: "uniqueItems";

package/src/transformers/ImportTransformer.ts

@@ -26,7 +26,8 @@ export namespace ImportTransformer {
     );
     const to: string = from.replace(props.top, props.to);
 
-    return ts.visitEachChild(
+    // First pass: transform relative imports
+    let transformedFile = ts.visitEachChild(
       props.file,
       (node) =>
         transform_node({
@@ -37,6 +38,11 @@ export namespace ImportTransformer {
         }),
       props.context,
     );
+
+    // Second pass: remove unused typia imports
+    transformedFile = removeUnusedTypiaImports(transformedFile);
+
+    return transformedFile;
   };
 
   const transform_node = (props: {
@@ -79,3 +85,174 @@ const get_directory_path = (file: string): string => {
   split.pop();
   return path.resolve(split.join(path.sep));
 };
+
+/**
+ * Remove unused typia imports that are only used in transformable calls
+ */
+const removeUnusedTypiaImports = (file: ts.SourceFile): ts.SourceFile => {
+  // Find typia imports and collect all identifiers
+  interface ImportMetadata {
+    declaration: ts.ImportDeclaration;
+    default: boolean;
+  }
+  const imports: Map<string, ImportMetadata> = new Map();
+  for (const stmt of file.statements) {
+    if (
+      ts.isImportDeclaration(stmt) === false ||
+      ts.isStringLiteral(stmt.moduleSpecifier) === false ||
+      stmt.moduleSpecifier.text !== "typia" ||
+      stmt.importClause === undefined
+    )
+      continue;
+
+    // Track default import (import typia from 'typia')
+    if (stmt.importClause.name)
+      imports.set(stmt.importClause.name.text, {
+        declaration: stmt,
+        default: true,
+      });
+
+    // Track named imports (import { tags } from 'typia') - keep these
+    if (
+      stmt.importClause.namedBindings &&
+      ts.isNamedImports(stmt.importClause.namedBindings)
+    )
+      for (const element of stmt.importClause.namedBindings.elements)
+        imports.set(element.name.text, {
+          declaration: stmt,
+          default: false,
+        });
+  }
+  if (imports.size === 0) return file; // No typia imports to check
+
+  // Find usage of typia identifiers that are NOT transformable calls
+  const nonTransformableUsage = new Set<string>();
+  const checkUsage = (node: ts.Node) => {
+    if (ts.isIdentifier(node) && imports.has(node.text)) {
+      const identifier: string = node.text;
+      // Check if this identifier is being used as part of a property access
+      if (
+        node.parent &&
+        ts.isPropertyAccessExpression(node.parent) &&
+        node.parent.expression === node
+      ) {
+        // This is typia.something - check if it's a transformable call pattern
+        if (!isLikelyTransformableCall(node.parent))
+          nonTransformableUsage.add(identifier);
+      } else
+        // Direct usage of the typia identifier (not as property access)
+        // This is definitely non-transformable usage
+        nonTransformableUsage.add(identifier);
+    }
+    ts.forEachChild(node, checkUsage);
+  };
+
+  // Check all statements except import declarations
+  for (const stmt of file.statements)
+    if (
+      !ts.isImportDeclaration(stmt) ||
+      !ts.isStringLiteral(stmt.moduleSpecifier) ||
+      stmt.moduleSpecifier.text !== "typia"
+    )
+      checkUsage(stmt);
+
+  // Update import statements
+  const newStatements: ts.Statement[] = file.statements
+    .map((stmt) => {
+      if (
+        ts.isImportDeclaration(stmt) &&
+        ts.isStringLiteral(stmt.moduleSpecifier) &&
+        stmt.moduleSpecifier.text === "typia" &&
+        stmt.importClause
+      ) {
+        const newImportClause = filterTypiaImportClause(
+          stmt.importClause,
+          nonTransformableUsage,
+        );
+        if (newImportClause)
+          return ts.factory.createImportDeclaration(
+            stmt.modifiers,
+            newImportClause,
+            stmt.moduleSpecifier,
+            stmt.attributes,
+          );
+        return null; // Skip adding the import if all imports are unused
+      }
+      return stmt;
+    })
+    .filter((stmt) => stmt !== null);
+  return ts.factory.updateSourceFile(
+    file,
+    newStatements,
+    file.isDeclarationFile,
+    file.referencedFiles,
+    file.typeReferenceDirectives,
+    file.hasNoDefaultLib,
+    file.libReferenceDirectives,
+  );
+};
+
+/**
+ * Check if a property access expression looks like a transformable typia call
+ * This uses heuristics to detect patterns like typia.xxx(), typia.namespace.xxx()
+ */
+const isLikelyTransformableCall = (
+  node: ts.PropertyAccessExpression,
+): boolean => {
+  // Check if this is eventually part of a call expression
+  let current: ts.Node = node;
+
+  // Walk up the chain to find if this leads to a call expression
+  // Handle patterns like: typia.xxx(), typia.namespace.xxx()
+  while (ts.isPropertyAccessExpression(current)) {
+    current = current.parent;
+  }
+
+  // If the final result is a call expression, this is likely transformable
+  if (
+    ts.isCallExpression(current) &&
+    (current.expression === node ||
+      (ts.isPropertyAccessExpression(current.expression) &&
+        isTypiaPropertyChain(current.expression)))
+  ) {
+    return true;
+  }
+
+  return false;
+};
+
+/**
+ * Check if a property access expression is part of a typia.xxx.yyy chain
+ */
+const isTypiaPropertyChain = (node: ts.PropertyAccessExpression): boolean => {
+  let current: ts.Expression = node;
+
+  while (ts.isPropertyAccessExpression(current)) {
+    current = current.expression;
+  }
+
+  return ts.isIdentifier(current) && current.text === "typia";
+};
+
+/**
+ * Filter import clause to remove unused default imports
+ */
+const filterTypiaImportClause = (
+  importClause: ts.ImportClause,
+  usedImports: Set<string>,
+): ts.ImportClause | undefined => {
+  const hasDefaultImport =
+    importClause.name && usedImports.has(importClause.name.text);
+  const namedBindings = importClause.namedBindings; // Always keep named bindings like { tags }
+
+  // Return undefined if no imports are used
+  if (!hasDefaultImport && !namedBindings) {
+    return undefined;
+  }
+
+  return ts.factory.createImportClause(
+    importClause.isTypeOnly,
+    hasDefaultImport ? importClause.name : undefined,
+    namedBindings,
+  );
+};