typia 9.7.2 → 10.0.0-dev.20251107

package/src/tags/Example.ts

@@ -1,56 +1,56 @@
-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
-    | bigint
-    | number
-    | string
-    | object
-    | Array<unknown>
-    | null,
-> = TagBase<{
-  target: "boolean" | "bigint" | "number" | "string" | "array" | "object";
-  kind: "example";
-  value: Value;
-  exclusive: true;
-  schema: Value extends bigint
-    ? { example: Numeric<Value> }
-    : { example: Value };
-}>;
-
-type Numeric<T extends bigint> = `${T}` extends `${infer N extends number}`
-  ? N
-  : never;
+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
+    | bigint
+    | number
+    | string
+    | object
+    | Array<unknown>
+    | null,
+> = TagBase<{
+  target: "boolean" | "bigint" | "number" | "string" | "array" | "object";
+  kind: "example";
+  value: Value;
+  exclusive: true;
+  schema: Value extends bigint
+    ? { example: Numeric<Value> }
+    : { example: Value };
+}>;
+
+type Numeric<T extends bigint> = `${T}` extends `${infer N extends number}`
+  ? N
+  : never;

package/src/tags/Examples.ts

@@ -1,56 +1,56 @@
-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,
-    boolean | bigint | number | string | object | Array<unknown> | null
-  >,
-> = TagBase<{
-  target: "boolean" | "bigint" | "number" | "string" | "array" | "object";
-  kind: "examples";
-  value: Value;
-  exclusive: true;
-  schema: {
-    examples: Value;
-  };
-}>;
+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,
+    boolean | bigint | number | string | object | Array<unknown> | null
+  >,
+> = TagBase<{
+  target: "boolean" | "bigint" | "number" | "string" | "array" | "object";
+  kind: "examples";
+  value: Value;
+  exclusive: true;
+  schema: {
+    examples: Value;
+  };
+}>;

package/src/tags/ExclusiveMaximum.ts

@@ -1,44 +1,44 @@
-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";
-  value: Value;
-  validate: `$input < ${Cast<Value>}`;
-  exclusive: ["exclusiveMaximum", "maximum"];
-  schema: Value extends bigint
-    ? {
-        exclusiveMaximum: Numeric<Value>;
-      }
-    : {
-        exclusiveMaximum: Value;
-      };
-}>;
-
-type Cast<Value extends number | bigint> = Value extends number
-  ? Value
-  : `BigInt(${Value})`;
-type Numeric<T extends bigint> = `${T}` extends `${infer N extends number}`
-  ? N
-  : never;
+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";
+  value: Value;
+  validate: `$input < ${Cast<Value>}`;
+  exclusive: ["exclusiveMaximum", "maximum"];
+  schema: Value extends bigint
+    ? {
+        exclusiveMaximum: Numeric<Value>;
+      }
+    : {
+        exclusiveMaximum: Value;
+      };
+}>;
+
+type Cast<Value extends number | bigint> = Value extends number
+  ? Value
+  : `BigInt(${Value})`;
+type Numeric<T extends bigint> = `${T}` extends `${infer N extends number}`
+  ? N
+  : never;

package/src/tags/ExclusiveMinimum.ts

@@ -1,44 +1,44 @@
-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";
-  value: Value;
-  validate: `${Cast<Value>} < $input`;
-  exclusive: ["exclusiveMinimum", "minimum"];
-  schema: Value extends bigint
-    ? {
-        exclusiveMinimum: Numeric<Value>;
-      }
-    : {
-        exclusiveMinimum: Value;
-      };
-}>;
-
-type Cast<Value extends number | bigint> = Value extends number
-  ? Value
-  : `BigInt(${Value})`;
-type Numeric<T extends bigint> = `${T}` extends `${infer N extends number}`
-  ? N
-  : never;
+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";
+  value: Value;
+  validate: `${Cast<Value>} < $input`;
+  exclusive: ["exclusiveMinimum", "minimum"];
+  schema: Value extends bigint
+    ? {
+        exclusiveMinimum: Numeric<Value>;
+      }
+    : {
+        exclusiveMinimum: Value;
+      };
+}>;
+
+type Cast<Value extends number | bigint> = Value extends number
+  ? Value
+  : `BigInt(${Value})`;
+type Numeric<T extends bigint> = `${T}` extends `${infer N extends number}`
+  ? N
+  : never;

package/src/tags/Format.ts

@@ -1,78 +1,78 @@
-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";
-  value: Value;
-  validate: `$importInternal("isFormat${PascalizeString<Value>}")($input)`;
-  exclusive: ["format", "pattern"];
-  schema: {
-    format: Value;
-  };
-}>;
-export namespace Format {
-  export type Value =
-    | "byte"
-    | "password"
-    | "regex"
-    | "uuid"
-    | "email"
-    | "hostname"
-    | "idn-email"
-    | "idn-hostname"
-    | "iri"
-    | "iri-reference"
-    | "ipv4"
-    | "ipv6"
-    | "uri"
-    | "uri-reference"
-    | "uri-template"
-    | "url"
-    | "date-time"
-    | "date"
-    | "time"
-    | "duration"
-    | "json-pointer"
-    | "relative-json-pointer";
-}
-
-type PascalizeString<Key extends string> = Key extends `-${infer R}`
-  ? `${PascalizeString<R>}`
-  : Key extends `${infer _F}-${infer _R}`
-    ? PascalizeSnakeString<Key>
-    : Capitalize<Key>;
-type PascalizeSnakeString<Key extends string> = Key extends `-${infer R}`
-  ? PascalizeSnakeString<R>
-  : Key extends `${infer F}${infer M}-${infer R}`
-    ? `${Uppercase<F>}${Lowercase<M>}${PascalizeSnakeString<R>}`
-    : Key extends `${infer F}${infer R}`
-      ? `${Uppercase<F>}${Lowercase<R>}`
-      : Key;
+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";
+  value: Value;
+  validate: `$importInternal("isFormat${PascalizeString<Value>}")($input)`;
+  exclusive: ["format", "pattern"];
+  schema: {
+    format: Value;
+  };
+}>;
+export namespace Format {
+  export type Value =
+    | "byte"
+    | "password"
+    | "regex"
+    | "uuid"
+    | "email"
+    | "hostname"
+    | "idn-email"
+    | "idn-hostname"
+    | "iri"
+    | "iri-reference"
+    | "ipv4"
+    | "ipv6"
+    | "uri"
+    | "uri-reference"
+    | "uri-template"
+    | "url"
+    | "date-time"
+    | "date"
+    | "time"
+    | "duration"
+    | "json-pointer"
+    | "relative-json-pointer";
+}
+
+type PascalizeString<Key extends string> = Key extends `-${infer R}`
+  ? `${PascalizeString<R>}`
+  : Key extends `${infer _F}-${infer _R}`
+    ? PascalizeSnakeString<Key>
+    : Capitalize<Key>;
+type PascalizeSnakeString<Key extends string> = Key extends `-${infer R}`
+  ? PascalizeSnakeString<R>
+  : Key extends `${infer F}${infer M}-${infer R}`
+    ? `${Uppercase<F>}${Lowercase<M>}${PascalizeSnakeString<R>}`
+    : Key extends `${infer F}${infer R}`
+      ? `${Uppercase<F>}${Lowercase<R>}`
+      : Key;

package/src/tags/JsonSchemaPlugin.ts

@@ -1,36 +1,36 @@
-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";
-  value: undefined;
-  schema: Schema;
-}>;
+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";
+  value: undefined;
+  schema: Schema;
+}>;