typia 9.7.1 → 10.0.0-dev.20251107

package/src/tags/Minimum.ts

@@ -1,37 +1,39 @@
-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";
-  value: Value;
-  validate: `${Cast<Value>} <= $input`;
-  exclusive: ["minimum", "exclusiveMinimum"];
-  schema: Value extends bigint
-    ? { minimum: Numeric<Value> }
-    : { minimum: 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";
+
+/**
+ * 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";
+  value: Value;
+  validate: `${Cast<Value>} <= $input`;
+  exclusive: ["minimum", "exclusiveMinimum"];
+  schema: Value extends bigint
+    ? { minimum: Numeric<Value> }
+    : { minimum: 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/MultipleOf.ts

@@ -1,39 +1,42 @@
-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";
-  value: Value;
-  validate: `$input % ${Cast<Value>} === ${Value extends bigint
-    ? Cast<0n>
-    : 0}`;
-  exclusive: true;
-  schema: Value extends bigint
-    ? { multipleOf: Numeric<Value> }
-    : { multipleOf: 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";
+
+/**
+ * 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";
+  value: Value;
+  validate: `$input % ${Cast<Value>} === ${Value extends bigint
+    ? Cast<0n>
+    : 0}`;
+  exclusive: true;
+  schema: Value extends bigint
+    ? { multipleOf: Numeric<Value> }
+    : { multipleOf: 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/Pattern.ts

@@ -1,46 +1,49 @@
-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";
-  value: Value;
-  validate: `RegExp("${Serialize<Value>}").test($input)`;
-  exclusive: ["format", "pattern"];
-  schema: {
-    pattern: Value;
-  };
-}>;
-
-/// reference: https://github.com/type-challenges/type-challenges/issues/22394#issuecomment-1397158205
-type Serialize<T extends string, Output extends string = ""> = string extends T
-  ? never
-  : T extends ""
-    ? Output
-    : T extends `${infer P}${infer R}`
-      ? Serialize<R, `${Output}${P extends keyof Escaper ? Escaper[P] : P}`>
-      : never;
-
-type Escaper = {
-  '"': '\\"';
-  "\\": "\\\\";
-  "\b": "\\b";
-  "\f": "\\f";
-  "\n": "\\n";
-  "\r": "\\r";
-  "\t": "\\t";
-};
+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";
+  value: Value;
+  validate: `RegExp("${Serialize<Value>}").test($input)`;
+  exclusive: ["format", "pattern"];
+  schema: {
+    pattern: Value;
+  };
+}>;
+
+/// reference: https://github.com/type-challenges/type-challenges/issues/22394#issuecomment-1397158205
+type Serialize<T extends string, Output extends string = ""> = string extends T
+  ? never
+  : T extends ""
+    ? Output
+    : T extends `${infer P}${infer R}`
+      ? Serialize<R, `${Output}${P extends keyof Escaper ? Escaper[P] : P}`>
+      : never;
+
+type Escaper = {
+  '"': '\\"';
+  "\\": "\\\\";
+  "\b": "\\b";
+  "\f": "\\f";
+  "\n": "\\n";
+  "\r": "\\r";
+  "\t": "\\t";
+};

package/src/tags/Sequence.ts

@@ -1,35 +1,37 @@
-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";
-  value: N;
-  schema: {
-    "x-protobuf-sequence": N;
-  };
-}>;
+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";
+  value: N;
+  schema: {
+    "x-protobuf-sequence": N;
+  };
+}>;

package/src/tags/TagBase.ts

@@ -1,109 +1,102 @@
-/**
- * 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>,
-> = {
-  /**
-   * This is a dummy property for compilation.
-   *
-   * It does not mean anything in runtime.
-   */
-  "typia.tag"?: Props;
-};
-export namespace TagBase {
-  /**
-   * Properties interface for validation tags.
-   *
-   * @author Jeongho Nam - https://github.com/samchon
-   */
-  export interface IProps<
-    Target extends
-      | "boolean"
-      | "bigint"
-      | "number"
-      | "string"
-      | "array"
-      | "object",
-    Kind extends string,
-    Value extends boolean | bigint | number | string | undefined,
-    Validate extends
-      | string
-      | {
-          [key in Target]?: string;
-        },
-    Exclusive extends boolean | string[],
-    Schema extends object | undefined,
-  > {
-    /**
-     * Target type.
-     *
-     * 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.
-     */
-    target: Target;
-
-    /**
-     * What kind of tag is this?
-     */
-    kind: Kind;
-
-    /**
-     * 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
-     * `$input` would be transformed to the suitable when compilation.
-     *
-     * Also, If you've take a mistake on this script, compile error would be
-     * occurred. So, define it with confidence. Compiler will block all your
-     * mistakes.
-     */
-    validate?: Validate;
-
-    /**
-     * Exclusive option.
-     *
-     * 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.
-     *
-     * @default false
-     */
-    exclusive?: Exclusive | string[];
-
-    /**
-     * Additional schema info assigned to the {@link IJsonSchema} object.
-     */
-    schema?: Schema;
-  }
-}
+/**
+ * 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>,
+> = {
+  /**
+   * This is a dummy property for compilation.
+   *
+   * It does not mean anything in runtime.
+   */
+  "typia.tag"?: Props;
+};
+export namespace TagBase {
+  /**
+   * Properties interface for validation tags.
+   *
+   * @author Jeongho Nam - https://github.com/samchon
+   */
+  export interface IProps<
+    Target extends
+      | "boolean"
+      | "bigint"
+      | "number"
+      | "string"
+      | "array"
+      | "object",
+    Kind extends string,
+    Value extends boolean | bigint | number | string | undefined,
+    Validate extends
+      | string
+      | {
+          [key in Target]?: string;
+        },
+    Exclusive extends boolean | string[],
+    Schema extends object | undefined,
+  > {
+    /**
+     * Target type.
+     *
+     * 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.
+     */
+    target: Target;
+
+    /** What kind of tag is this? */
+    kind: Kind;
+
+    /** 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
+     * `$input` would be transformed to the suitable when compilation.
+     *
+     * Also, If you've take a mistake on this script, compile error would be
+     * occurred. So, define it with confidence. Compiler will block all your
+     * mistakes.
+     */
+    validate?: Validate;
+
+    /**
+     * Exclusive option.
+     *
+     * 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.
+     *
+     * @default false
+     */
+    exclusive?: Exclusive | string[];
+
+    /** Additional schema info assigned to the {@link IJsonSchema} object. */
+    schema?: Schema;
+  }
+}