typia 9.6.1 → 9.7.1

package/lib/CamelCase.d.mts

@@ -7,7 +7,7 @@ import { ValueOf } from "./typings/ValueOf";
  *
  * `CamelCase` type is a type that all keys of an object are camelized.
  *
- * It also erase every method properties like {@link Resolved} type.
+ * It also erases every method property like {@link Resolved} type.
  *
  * @template T Target type to be camelized
  * @author Jeongho Nam - https://github.com/samchon

package/lib/CamelCase.d.ts

@@ -7,7 +7,7 @@ import { ValueOf } from "./typings/ValueOf";
  *
  * `CamelCase` type is a type that all keys of an object are camelized.
  *
- * It also erase every method properties like {@link Resolved} type.
+ * It also erases every method property like {@link Resolved} type.
  *
  * @template T Target type to be camelized
  * @author Jeongho Nam - https://github.com/samchon

package/lib/IRandomGenerator.d.mts

@@ -1,40 +1,280 @@
 import { OpenApi } from "@samchon/openapi";
+/**
+ * Interface for generating random values for various data types.
+ *
+ * `IRandomGenerator` defines the contract for generating random values
+ * that can be used by typia for creating mock data, testing scenarios,
+ * and random value generation based on JSON schema constraints.
+ *
+ * This interface supports generating random values for:
+ * - Basic types (boolean, number, integer, bigint, string, array)
+ * - String format patterns (email, URL, UUID, etc.)
+ * - Date and time formats
+ * - Various address and identifier formats
+ *
+ * @example
+ * ```typescript
+ * const generator: IRandomGenerator = {
+ *   boolean: () => Math.random() > 0.5,
+ *   number: (schema) => Math.random() * (schema.maximum ?? 100),
+ *   string: (schema) => "example-string",
+ *   email: () => "test@example.com",
+ *   // ... implement other methods
+ * };
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export interface IRandomGenerator {
+    /**
+     * Generates a random boolean value.
+     *
+     * @returns Random boolean value or undefined
+     */
     boolean(): boolean | undefined;
+    /**
+     * Generates a random number based on JSON schema constraints.
+     *
+     * @param schema JSON schema with number constraints (min, max, etc.)
+     * @returns Random number within the specified constraints
+     */
     number(schema: OpenApi.IJsonSchema.INumber): number;
+    /**
+     * Generates a random integer based on JSON schema constraints.
+     *
+     * @param schema JSON schema with integer constraints (min, max, etc.)
+     * @returns Random integer within the specified constraints
+     */
     integer(schema: OpenApi.IJsonSchema.IInteger): number;
+    /**
+     * Generates a random bigint based on JSON schema constraints.
+     *
+     * @param schema JSON schema with integer constraints (min, max, etc.)
+     * @returns Random bigint within the specified constraints
+     */
     bigint(schema: OpenApi.IJsonSchema.IInteger): bigint;
+    /**
+     * Generates a random string based on JSON schema constraints.
+     *
+     * @param schema JSON schema with string constraints (minLength, maxLength, pattern, etc.)
+     * @returns Random string matching the specified constraints
+     */
     string(schema: OpenApi.IJsonSchema.IString): string;
+    /**
+     * Generates a random array with elements created by the provided generator function.
+     *
+     * @param schema Array schema with element generator function
+     * @returns Random array with generated elements
+     */
     array<T>(schema: Omit<OpenApi.IJsonSchema.IArray, "items"> & {
         element: (index: number, count: number) => T;
     }): T[];
+    /**
+     * Generates a random string matching the given regular expression pattern.
+     *
+     * @param regex Regular expression pattern to match
+     * @returns Random string matching the pattern
+     */
     pattern(regex: RegExp): string;
+    /**
+     * Generates a random base64-encoded byte string.
+     *
+     * @returns Random base64 string
+     */
     byte(): string;
+    /**
+     * Generates a random password string.
+     *
+     * @returns Random password
+     */
     password(): string;
+    /**
+     * Generates a random regular expression pattern string.
+     *
+     * @returns Random regex pattern
+     */
     regex(): string;
+    /**
+     * Generates a random UUID (Universally Unique Identifier).
+     *
+     * @returns Random UUID string in standard format
+     */
     uuid(): string;
+    /**
+     * Generates a random email address.
+     *
+     * @returns Random email address
+     */
     email(): string;
+    /**
+     * Generates a random hostname.
+     *
+     * @returns Random hostname
+     */
     hostname(): string;
+    /**
+     * Generates a random internationalized email address.
+     *
+     * @returns Random IDN email address
+     */
     idnEmail(): string;
+    /**
+     * Generates a random internationalized hostname.
+     *
+     * @returns Random IDN hostname
+     */
     idnHostname(): string;
+    /**
+     * Generates a random IRI (Internationalized Resource Identifier).
+     *
+     * @returns Random IRI
+     */
     iri(): string;
+    /**
+     * Generates a random IRI reference.
+     *
+     * @returns Random IRI reference
+     */
     iriReference(): string;
+    /**
+     * Generates a random IPv4 address.
+     *
+     * @returns Random IPv4 address
+     */
     ipv4(): string;
+    /**
+     * Generates a random IPv6 address.
+     *
+     * @returns Random IPv6 address
+     */
     ipv6(): string;
+    /**
+     * Generates a random URI (Uniform Resource Identifier).
+     *
+     * @returns Random URI
+     */
     uri(): string;
+    /**
+     * Generates a random URI reference.
+     *
+     * @returns Random URI reference
+     */
     uriReference(): string;
+    /**
+     * Generates a random URI template.
+     *
+     * @returns Random URI template
+     */
     uriTemplate(): string;
+    /**
+     * Generates a random URL (Uniform Resource Locator).
+     *
+     * @returns Random URL
+     */
     url(): string;
+    /**
+     * Generates a random datetime string in ISO 8601 format.
+     *
+     * @param props Optional constraints for minimum and maximum timestamp values
+     * @returns Random datetime string
+     */
     datetime(props?: {
         minimum?: number;
         maximum?: number;
     }): string;
+    /**
+     * Generates a random date string in ISO 8601 format (YYYY-MM-DD).
+     *
+     * @param props Optional constraints for minimum and maximum timestamp values
+     * @returns Random date string
+     */
     date(props?: {
         minimum?: number;
         maximum?: number;
     }): string;
+    /**
+     * Generates a random time string in ISO 8601 format (HH:MM:SS).
+     *
+     * @returns Random time string
+     */
     time(): string;
+    /**
+     * Generates a random duration string in ISO 8601 format.
+     *
+     * @returns Random duration string
+     */
     duration(): string;
+    /**
+     * Generates a random JSON pointer string.
+     *
+     * @returns Random JSON pointer
+     */
     jsonPointer(): string;
+    /**
+     * Generates a random relative JSON pointer string.
+     *
+     * @returns Random relative JSON pointer
+     */
     relativeJsonPointer(): string;
 }
+export declare namespace IRandomGenerator {
+    /**
+     * Map of custom generators for different data types.
+     *
+     * This interface allows customization of random generation for specific
+     * types when they have certain schema properties or constraints.
+     *
+     * @example
+     * ```typescript
+     * const generator: Partial<IRandomGenerator> = {
+     *   string: (schema) => {
+     *     if ((schema as any)["x-typia-monetary"] === "dollar") {
+     *       return "$" + Math.floor(Math.random() * 1000);
+     *     }
+     *     return "default-string";
+     *   },
+     *   number: (schema) => {
+     *     if ((schema as any)["x-typia-powerOf"] !== undefined) {
+     *       const powerOf = (schema as any)["x-typia-powerOf"];
+     *       return Math.pow(powerOf, Math.random() * 10 + 1);
+     *     }
+     *     return Math.random() * 100;
+     *   }
+     * };
+     * ```
+     */
+    interface CustomMap {
+        /**
+         * Custom string generator that can handle special string formats
+         * based on schema properties.
+         */
+        string?: (schema: OpenApi.IJsonSchema.IString & Record<string, any>) => string;
+        /**
+         * Custom number generator that can handle special number constraints
+         * based on schema properties.
+         */
+        number?: (schema: OpenApi.IJsonSchema.INumber & Record<string, any>) => number;
+        /**
+         * Custom integer generator that can handle special integer constraints
+         * based on schema properties.
+         */
+        integer?: (schema: OpenApi.IJsonSchema.IInteger & Record<string, any>) => number;
+        /**
+         * Custom bigint generator that can handle special bigint constraints
+         * based on schema properties.
+         */
+        bigint?: (schema: OpenApi.IJsonSchema.IInteger & Record<string, any>) => bigint;
+        /**
+         * Custom boolean generator that can handle special boolean constraints
+         * based on schema properties.
+         */
+        boolean?: (schema: Record<string, any>) => boolean | undefined;
+        /**
+         * Custom array generator that can handle special array constraints
+         * based on schema properties.
+         */
+        array?: <T>(schema: Omit<OpenApi.IJsonSchema.IArray, "items"> & {
+            element: (index: number, count: number) => T;
+        } & Record<string, any>) => T[];
+    }
+}

package/lib/IRandomGenerator.d.ts

@@ -1,40 +1,280 @@
 import { OpenApi } from "@samchon/openapi";
+/**
+ * Interface for generating random values for various data types.
+ *
+ * `IRandomGenerator` defines the contract for generating random values
+ * that can be used by typia for creating mock data, testing scenarios,
+ * and random value generation based on JSON schema constraints.
+ *
+ * This interface supports generating random values for:
+ * - Basic types (boolean, number, integer, bigint, string, array)
+ * - String format patterns (email, URL, UUID, etc.)
+ * - Date and time formats
+ * - Various address and identifier formats
+ *
+ * @example
+ * ```typescript
+ * const generator: IRandomGenerator = {
+ *   boolean: () => Math.random() > 0.5,
+ *   number: (schema) => Math.random() * (schema.maximum ?? 100),
+ *   string: (schema) => "example-string",
+ *   email: () => "test@example.com",
+ *   // ... implement other methods
+ * };
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export interface IRandomGenerator {
+    /**
+     * Generates a random boolean value.
+     *
+     * @returns Random boolean value or undefined
+     */
     boolean(): boolean | undefined;
+    /**
+     * Generates a random number based on JSON schema constraints.
+     *
+     * @param schema JSON schema with number constraints (min, max, etc.)
+     * @returns Random number within the specified constraints
+     */
     number(schema: OpenApi.IJsonSchema.INumber): number;
+    /**
+     * Generates a random integer based on JSON schema constraints.
+     *
+     * @param schema JSON schema with integer constraints (min, max, etc.)
+     * @returns Random integer within the specified constraints
+     */
     integer(schema: OpenApi.IJsonSchema.IInteger): number;
+    /**
+     * Generates a random bigint based on JSON schema constraints.
+     *
+     * @param schema JSON schema with integer constraints (min, max, etc.)
+     * @returns Random bigint within the specified constraints
+     */
     bigint(schema: OpenApi.IJsonSchema.IInteger): bigint;
+    /**
+     * Generates a random string based on JSON schema constraints.
+     *
+     * @param schema JSON schema with string constraints (minLength, maxLength, pattern, etc.)
+     * @returns Random string matching the specified constraints
+     */
     string(schema: OpenApi.IJsonSchema.IString): string;
+    /**
+     * Generates a random array with elements created by the provided generator function.
+     *
+     * @param schema Array schema with element generator function
+     * @returns Random array with generated elements
+     */
     array<T>(schema: Omit<OpenApi.IJsonSchema.IArray, "items"> & {
         element: (index: number, count: number) => T;
     }): T[];
+    /**
+     * Generates a random string matching the given regular expression pattern.
+     *
+     * @param regex Regular expression pattern to match
+     * @returns Random string matching the pattern
+     */
     pattern(regex: RegExp): string;
+    /**
+     * Generates a random base64-encoded byte string.
+     *
+     * @returns Random base64 string
+     */
     byte(): string;
+    /**
+     * Generates a random password string.
+     *
+     * @returns Random password
+     */
     password(): string;
+    /**
+     * Generates a random regular expression pattern string.
+     *
+     * @returns Random regex pattern
+     */
     regex(): string;
+    /**
+     * Generates a random UUID (Universally Unique Identifier).
+     *
+     * @returns Random UUID string in standard format
+     */
     uuid(): string;
+    /**
+     * Generates a random email address.
+     *
+     * @returns Random email address
+     */
     email(): string;
+    /**
+     * Generates a random hostname.
+     *
+     * @returns Random hostname
+     */
     hostname(): string;
+    /**
+     * Generates a random internationalized email address.
+     *
+     * @returns Random IDN email address
+     */
     idnEmail(): string;
+    /**
+     * Generates a random internationalized hostname.
+     *
+     * @returns Random IDN hostname
+     */
     idnHostname(): string;
+    /**
+     * Generates a random IRI (Internationalized Resource Identifier).
+     *
+     * @returns Random IRI
+     */
     iri(): string;
+    /**
+     * Generates a random IRI reference.
+     *
+     * @returns Random IRI reference
+     */
     iriReference(): string;
+    /**
+     * Generates a random IPv4 address.
+     *
+     * @returns Random IPv4 address
+     */
     ipv4(): string;
+    /**
+     * Generates a random IPv6 address.
+     *
+     * @returns Random IPv6 address
+     */
     ipv6(): string;
+    /**
+     * Generates a random URI (Uniform Resource Identifier).
+     *
+     * @returns Random URI
+     */
     uri(): string;
+    /**
+     * Generates a random URI reference.
+     *
+     * @returns Random URI reference
+     */
     uriReference(): string;
+    /**
+     * Generates a random URI template.
+     *
+     * @returns Random URI template
+     */
     uriTemplate(): string;
+    /**
+     * Generates a random URL (Uniform Resource Locator).
+     *
+     * @returns Random URL
+     */
     url(): string;
+    /**
+     * Generates a random datetime string in ISO 8601 format.
+     *
+     * @param props Optional constraints for minimum and maximum timestamp values
+     * @returns Random datetime string
+     */
     datetime(props?: {
         minimum?: number;
         maximum?: number;
     }): string;
+    /**
+     * Generates a random date string in ISO 8601 format (YYYY-MM-DD).
+     *
+     * @param props Optional constraints for minimum and maximum timestamp values
+     * @returns Random date string
+     */
     date(props?: {
         minimum?: number;
         maximum?: number;
     }): string;
+    /**
+     * Generates a random time string in ISO 8601 format (HH:MM:SS).
+     *
+     * @returns Random time string
+     */
     time(): string;
+    /**
+     * Generates a random duration string in ISO 8601 format.
+     *
+     * @returns Random duration string
+     */
     duration(): string;
+    /**
+     * Generates a random JSON pointer string.
+     *
+     * @returns Random JSON pointer
+     */
     jsonPointer(): string;
+    /**
+     * Generates a random relative JSON pointer string.
+     *
+     * @returns Random relative JSON pointer
+     */
     relativeJsonPointer(): string;
 }
+export declare namespace IRandomGenerator {
+    /**
+     * Map of custom generators for different data types.
+     *
+     * This interface allows customization of random generation for specific
+     * types when they have certain schema properties or constraints.
+     *
+     * @example
+     * ```typescript
+     * const generator: Partial<IRandomGenerator> = {
+     *   string: (schema) => {
+     *     if ((schema as any)["x-typia-monetary"] === "dollar") {
+     *       return "$" + Math.floor(Math.random() * 1000);
+     *     }
+     *     return "default-string";
+     *   },
+     *   number: (schema) => {
+     *     if ((schema as any)["x-typia-powerOf"] !== undefined) {
+     *       const powerOf = (schema as any)["x-typia-powerOf"];
+     *       return Math.pow(powerOf, Math.random() * 10 + 1);
+     *     }
+     *     return Math.random() * 100;
+     *   }
+     * };
+     * ```
+     */
+    interface CustomMap {
+        /**
+         * Custom string generator that can handle special string formats
+         * based on schema properties.
+         */
+        string?: (schema: OpenApi.IJsonSchema.IString & Record<string, any>) => string;
+        /**
+         * Custom number generator that can handle special number constraints
+         * based on schema properties.
+         */
+        number?: (schema: OpenApi.IJsonSchema.INumber & Record<string, any>) => number;
+        /**
+         * Custom integer generator that can handle special integer constraints
+         * based on schema properties.
+         */
+        integer?: (schema: OpenApi.IJsonSchema.IInteger & Record<string, any>) => number;
+        /**
+         * Custom bigint generator that can handle special bigint constraints
+         * based on schema properties.
+         */
+        bigint?: (schema: OpenApi.IJsonSchema.IInteger & Record<string, any>) => bigint;
+        /**
+         * Custom boolean generator that can handle special boolean constraints
+         * based on schema properties.
+         */
+        boolean?: (schema: Record<string, any>) => boolean | undefined;
+        /**
+         * Custom array generator that can handle special array constraints
+         * based on schema properties.
+         */
+        array?: <T>(schema: Omit<OpenApi.IJsonSchema.IArray, "items"> & {
+            element: (index: number, count: number) => T;
+        } & Record<string, any>) => T[];
+    }
+}

package/lib/PascalCase.d.mts

@@ -7,7 +7,7 @@ import { ValueOf } from "./typings/ValueOf";
  *
  * `PascalCase` type is a type that all keys of an object are pascalized.
  *
- * It also erase every method properties like {@link Resolved} type.
+ * It also erases every method property like {@link Resolved} type.
  *
  * @template T Target type to be pascalized
  * @author Jeongho Nam - https://github.com/samchon

package/lib/PascalCase.d.ts

@@ -7,7 +7,7 @@ import { ValueOf } from "./typings/ValueOf";
  *
  * `PascalCase` type is a type that all keys of an object are pascalized.
  *
- * It also erase every method properties like {@link Resolved} type.
+ * It also erases every method property like {@link Resolved} type.
  *
  * @template T Target type to be pascalized
  * @author Jeongho Nam - https://github.com/samchon

package/lib/Primitive.d.mts

@@ -7,19 +7,19 @@ import { Format } from "./tags";
  * Primitive type of JSON.
  *
  * `Primitive<T>` is a TMP (Type Meta Programming) type which converts
- * its argument as a primitive type within framework JSON.
+ * its argument as a primitive type within the framework JSON.
  *
  * If the target argument is a built-in class which returns its origin primitive type
- * through the `valueOf()` method like the `String` or `Number`, its return type would
- * be the `string` or `number`. Otherwise, the built-in class does not have the
- * `valueOf()` method, the return type would be an empty object (`{}`).
+ * through the `valueOf()` method like the `String` or `Number`, its return type will
+ * be the `string` or `number`. Otherwise, if the built-in class does not have the
+ * `valueOf()` method, the return type will be an empty object (`{}`).
  *
- * Otherwise, the target argument is a type of custom class, all of its custom method
- * would be erased and its prototype would be changed to the primitive `object`.
- * Therefore, return type of the TMP type finally be the primitive object.
+ * Otherwise, if the target argument is a type of custom class, all of its custom methods
+ * will be erased and its prototype will be changed to the primitive `object`.
+ * Therefore, the return type of the TMP type will finally be the primitive object.
  *
  * In addition, if the target argument is a type of custom class and it has a special
- * method `toJSON()`, return type of this `Primitive` would be not `Primitive<Instance>`
+ * method `toJSON()`, the return type of this `Primitive` will be not `Primitive<Instance>`
  * but `Primitive<ReturnType<Instance.toJSON>>`.
  *
  * Before                  | After

package/lib/Primitive.d.ts

@@ -7,19 +7,19 @@ import { Format } from "./tags";
  * Primitive type of JSON.
  *
  * `Primitive<T>` is a TMP (Type Meta Programming) type which converts
- * its argument as a primitive type within framework JSON.
+ * its argument as a primitive type within the framework JSON.
  *
  * If the target argument is a built-in class which returns its origin primitive type
- * through the `valueOf()` method like the `String` or `Number`, its return type would
- * be the `string` or `number`. Otherwise, the built-in class does not have the
- * `valueOf()` method, the return type would be an empty object (`{}`).
+ * through the `valueOf()` method like the `String` or `Number`, its return type will
+ * be the `string` or `number`. Otherwise, if the built-in class does not have the
+ * `valueOf()` method, the return type will be an empty object (`{}`).
  *
- * Otherwise, the target argument is a type of custom class, all of its custom method
- * would be erased and its prototype would be changed to the primitive `object`.
- * Therefore, return type of the TMP type finally be the primitive object.
+ * Otherwise, if the target argument is a type of custom class, all of its custom methods
+ * will be erased and its prototype will be changed to the primitive `object`.
+ * Therefore, the return type of the TMP type will finally be the primitive object.
  *
  * In addition, if the target argument is a type of custom class and it has a special
- * method `toJSON()`, return type of this `Primitive` would be not `Primitive<Instance>`
+ * method `toJSON()`, the return type of this `Primitive` will be not `Primitive<Instance>`
  * but `Primitive<ReturnType<Instance.toJSON>>`.
  *
  * Before                  | After

package/lib/Resolved.d.mts

@@ -3,19 +3,19 @@ import { IsTuple } from "./typings/IsTuple";
 import { NativeClass } from "./typings/NativeClass";
 import { ValueOf } from "./typings/ValueOf";
 /**
- * Resolved type erased every methods.
+ * Resolved type that erases every method.
  *
- * `Resolved` is a type of TMP (Type Meta Programming) type which converts
- * its argument as a resolved type that erased every method properties.
+ * `Resolved` is a TMP (Type Meta Programming) type which converts
+ * its argument as a resolved type that erases every method property.
  *
  * If the target argument is a built-in class which returns its origin primitive type
- * through the `valueOf()` method like the `String` or `Number`, its return type would
- * be the `string` or `number`. Otherwise, the built-in class does not have the
- * `valueOf()` method, the return type would be same with the target argument.
+ * through the `valueOf()` method like the `String` or `Number`, its return type will
+ * be the `string` or `number`. Otherwise, if the built-in class does not have the
+ * `valueOf()` method, the return type will be the same as the target argument.
  *
- * Otherwise, the target argument is a type of custom class, all of its custom methods
- * would be erased and its prototype would be changed to the primitive `object`.
- * Therefore, return type of the TMP type finally be the resolved object.
+ * Otherwise, if the target argument is a type of custom class, all of its custom methods
+ * will be erased and its prototype will be changed to the primitive `object`.
+ * Therefore, the return type of the TMP type will finally be the resolved object.
  *
  * Before                  | After
  * ------------------------|----------------------------------------