typia 9.7.1 → 10.0.0-dev.20251107

package/src/tags/Constant.ts

@@ -1,47 +1,47 @@
-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.
- *
- * @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
- * @author Jeongho Nam - https://github.com/samchon
- */
-export type Constant<
-  Value extends boolean | number | string | bigint,
-  Content extends {
-    title?: string | undefined;
-    description?: string | undefined;
-  },
-> = Value &
-  TagBase<{
-    target: "string" | "boolean" | "number" | "bigint";
-    kind: "constant";
-    value: undefined;
-    schema: Content;
-  }>;
+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 {
+    title?: string | undefined;
+    description?: string | undefined;
+  },
+> = Value &
+  TagBase<{
+    target: "string" | "boolean" | "number" | "bigint";
+    kind: "constant";
+    value: undefined;
+    schema: Content;
+  }>;

package/src/tags/ContentMediaType.ts

@@ -1,27 +1,27 @@
-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";
-  value: undefined;
-  schema: {
-    contentMediaType: Value;
-  };
-}>;
+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";
+  value: undefined;
+  schema: {
+    contentMediaType: Value;
+  };
+}>;

package/src/tags/Default.ts

@@ -1,52 +1,52 @@
-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.
- *
- * @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)
- * @author Jeongho Nam - https://github.com/samchon
- */
-export type Default<Value extends boolean | bigint | number | string> =
-  TagBase<{
-    target: Value extends boolean
-      ? "boolean"
-      : Value extends bigint
-        ? "bigint"
-        : Value extends number
-          ? "number"
-          : "string";
-    kind: "default";
-    value: Value;
-    exclusive: true;
-    schema: Value extends bigint
-      ? { default: Numeric<Value> }
-      : { default: Value };
-  }>;
-
-type Numeric<T extends bigint> = `${T}` extends `${infer N extends number}`
-  ? N
-  : never;
+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
+      ? "boolean"
+      : Value extends bigint
+        ? "bigint"
+        : Value extends number
+          ? "number"
+          : "string";
+    kind: "default";
+    value: Value;
+    exclusive: true;
+    schema: Value extends bigint
+      ? { default: Numeric<Value> }
+      : { default: Value };
+  }>;
+
+type Numeric<T extends bigint> = `${T}` extends `${infer N extends number}`
+  ? N
+  : never;

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.
- *
- * @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)
- * @author Jeongho Nam - https://github.com/samchon
- */
-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.
- *
- * @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
- * @author Jeongho Nam - https://github.com/samchon
- */
-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,41 +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.
- *
- * @template Value - The exclusive maximum value constraint (number or bigint literal)
- * @author Jeongho Nam - https://github.com/samchon
- */
-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;