typia 9.3.1 → 9.5.0-dev.20250710

package/lib/schemas/json/IJsonSchemaUnit.d.ts

@@ -1,26 +1,236 @@
 import { OpenApi, OpenApiV3 } from "@samchon/openapi";
 /**
- * Unit of JSON schema.
+ * Single unit of JSON schema representation.
  *
- * `IJsonSchemaUnit` is a type that represents a single JSON schema unit
- * containing the schema and components.
+ * `IJsonSchemaUnit` represents a self-contained JSON schema unit that encapsulates
+ * a single schema definition along with its associated reusable components. This is
+ * typically used when generating a JSON schema for a single TypeScript type, as
+ * opposed to a collection of multiple types.
  *
- * @template Version Version of the OpenAPI specification
- * @template Type Original TypeScript type used in the JSON schema
+ * Unlike {@link IJsonSchemaCollection} which handles multiple schemas, `IJsonSchemaUnit`
+ * focuses on representing a single schema with its dependencies. This makes it ideal
+ * for scenarios where you need to work with individual type definitions or when
+ * integrating with systems that expect single schema documents.
+ *
+ * The unit contains:
+ * - A single JSON schema definition for the specified TypeScript type
+ * - All necessary reusable components that the schema may reference
+ * - Version-specific formatting for either OpenAPI v3.0 or v3.1 compatibility
+ * - Optional type metadata for compile-time type safety
+ *
+ * Key differences from collection:
+ * - Contains only one schema instead of an array of schemas
+ * - More lightweight for single-type use cases
+ * - Simpler structure for direct schema consumption
+ * - Still maintains full component reference support
+ *
+ * @template Version The OpenAPI specification version to target ("3.0" or "3.1").
+ *                   Defaults to "3.1" for enhanced JSON Schema Draft 2020-12 compatibility.
+ *                   This determines the schema format, validation capabilities, and
+ *                   available features like tuple support and null type handling.
+ * @template Type    The original TypeScript type that was analyzed to generate this
+ *                   JSON schema unit. This provides compile-time type safety and
+ *                   enables IDEs to provide better intellisense and validation.
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   name: string;
+ *   email?: string;
+ * }
+ *
+ * // Generate a single schema unit for OpenAPI v3.1 (default)
+ * const userSchema = typia.json.schema<User>();
+ * // Type: IJsonSchemaUnit<"3.1", User>
+ *
+ * // Generate a single schema unit for OpenAPI v3.0 (Swagger compatibility)
+ * const swaggerUserSchema = typia.json.schema<User, "3.0">();
+ * // Type: IJsonSchemaUnit<"3.0", User>
+ * ```
+ *
+ * @see {@link IJsonSchemaCollection} For handling multiple schemas at once
  * @author Jeongho Nam - https://github.com/samchon
  */
 export type IJsonSchemaUnit<Version extends "3.0" | "3.1" = "3.1", Type = unknown> = Version extends "3.0" ? IJsonSchemaUnit.IV3_0<Type> : IJsonSchemaUnit.IV3_1<Type>;
 export declare namespace IJsonSchemaUnit {
+    /**
+     * JSON Schema unit formatted for OpenAPI v3.0 specification.
+     *
+     * This interface represents a single JSON schema unit that complies with
+     * OpenAPI v3.0 standards. It contains one schema definition along with
+     * any reusable components that the schema references, formatted according
+     * to OpenAPI v3.0 constraints and limitations.
+     *
+     * OpenAPI v3.0 characteristics affecting this unit:
+     * - Schema follows OpenAPI v3.0 JSON Schema subset
+     * - Limited support for advanced JSON Schema features
+     * - Uses nullable property for optional null values
+     * - Cannot natively express tuple types or pattern properties
+     * - Based on JSON Schema Draft 4 with OpenAPI-specific extensions
+     *
+     * Use cases for v3.0:
+     * - Integration with legacy Swagger tooling
+     * - Compatibility with older OpenAPI implementations
+     * - Systems that specifically require OpenAPI v3.0 format
+     * - Code generation tools that expect v3.0 schemas
+     *
+     * @template Type The original TypeScript type represented by this schema unit.
+     *                Provides compile-time type information and enables type-safe
+     *                operations on the schema.
+     */
     interface IV3_0<Type> {
+        /**
+         * OpenAPI specification version identifier.
+         *
+         * Always set to "3.0" to indicate this schema unit uses OpenAPI v3.0
+         * format and adheres to its specific constraints and limitations.
+         */
         version: "3.0";
+        /**
+         * The primary JSON schema definition.
+         *
+         * Contains the main JSON schema that represents the TypeScript type specified
+         * in the `Type` template parameter. This schema follows OpenAPI v3.0 format
+         * and may contain references to reusable components defined in the
+         * {@link components} property.
+         *
+         * The schema structure includes:
+         * - Type definitions following OpenAPI v3.0 constraints
+         * - Property definitions with v3.0-compatible validation rules
+         * - References to shared components using $ref syntax
+         * - Nullable properties for optional fields that can be null
+         *
+         * Example schema reference: `{ "$ref": "#/components/schemas/NestedType" }`
+         */
         schema: OpenApiV3.IJsonSchema;
+        /**
+         * Reusable schema components for OpenAPI v3.0.
+         *
+         * Contains all reusable schema definitions and components that may be
+         * referenced by the main schema. This enables schema modularity and
+         * prevents duplication when the same types are used in multiple places
+         * within the schema definition.
+         *
+         * Component categories include:
+         * - schemas: Named type definitions for complex objects, arrays, and unions
+         * - securitySchemes: Authentication and authorization definitions
+         * - parameters: Reusable parameter specifications
+         * - requestBodies: Reusable request body definitions
+         * - responses: Reusable response specifications
+         * - headers: Reusable header definitions
+         * - examples: Reusable example values
+         *
+         * All components follow OpenAPI v3.0 format restrictions and capabilities.
+         */
         components: OpenApiV3.IComponents;
+        /**
+         * Type metadata for compile-time type safety.
+         *
+         * This optional property maintains a reference to the original TypeScript
+         * type that was used to generate this schema unit. It provides compile-time
+         * type information without affecting the runtime JSON representation.
+         *
+         * Benefits of type metadata:
+         * - Enables type-safe schema validation and usage
+         * - Provides IDE intellisense and autocompletion
+         * - Allows compile-time checking of schema operations
+         * - Maintains traceability to original TypeScript definitions
+         *
+         * The property is intentionally marked as optional and undefined to ensure
+         * it doesn't appear in serialized JSON output while preserving type information
+         * at compile time.
+         */
         __type?: Type | undefined;
     }
+    /**
+     * JSON Schema unit formatted for OpenAPI v3.1 specification.
+     *
+     * This interface represents a single JSON schema unit that takes advantage
+     * of OpenAPI v3.1's enhanced capabilities and improved JSON Schema compatibility.
+     * It provides a more feature-rich and accurate representation of TypeScript
+     * types compared to the v3.0 format.
+     *
+     * OpenAPI v3.1 advantages for this unit:
+     * - Full JSON Schema Draft 2020-12 compatibility
+     * - Native tuple type support using prefixItems
+     * - Proper null type handling via union types
+     * - Pattern properties for dynamic object keys
+     * - Enhanced const, enum, and validation capabilities
+     * - Better support for complex nested structures
+     *
+     * Use cases for v3.1:
+     * - Modern OpenAPI implementations and tooling
+     * - Systems requiring accurate TypeScript type representation
+     * - Applications needing advanced JSON Schema features
+     * - New projects without legacy compatibility requirements
+     *
+     * @template Type The original TypeScript type represented by this schema unit.
+     *                Enables compile-time type safety and provides enhanced
+     *                development experience with better IDE support.
+     */
     interface IV3_1<Type> {
+        /**
+         * OpenAPI specification version identifier.
+         *
+         * Always set to "3.1" to indicate this schema unit uses OpenAPI v3.1
+         * format with enhanced JSON Schema compatibility and modern features.
+         */
         version: "3.1";
+        /**
+         * The primary JSON schema definition with v3.1 enhancements.
+         *
+         * Contains the main JSON schema that accurately represents the TypeScript
+         * type using OpenAPI v3.1's enhanced capabilities. This schema can express
+         * complex TypeScript constructs that were not possible or accurate in v3.0.
+         *
+         * Enhanced schema features include:
+         * - Tuple types using prefixItems for exact array structure
+         * - Union types with proper null handling via oneOf
+         * - Const values for literal types
+         * - Pattern properties for Record<string, T> types
+         * - Advanced validation constraints and metadata
+         * - Recursive type definitions with proper $ref handling
+         *
+         * The schema follows the emended OpenAPI v3.1 format used by typia,
+         * which removes ambiguous expressions while maintaining full compatibility.
+         */
         schema: OpenApi.IJsonSchema;
+        /**
+         * Reusable schema components for OpenAPI v3.1.
+         *
+         * Contains reusable schema definitions and components that leverage
+         * OpenAPI v3.1's enhanced capabilities. These components provide better
+         * type representation and more accurate schema definitions compared to v3.0.
+         *
+         * Enhanced component features:
+         * - schemas: More accurate type definitions with v3.1 JSON Schema features
+         * - securitySchemes: Enhanced authentication scheme definitions
+         * - Better support for complex nested references
+         * - Improved handling of recursive and circular type dependencies
+         *
+         * The components structure follows the emended OpenAPI v3.1 specification
+         * that simplifies certain patterns while maintaining full expressiveness.
+         */
         components: OpenApi.IComponents;
+        /**
+         * Type metadata for enhanced compile-time type safety.
+         *
+         * This optional property preserves the original TypeScript type information
+         * for compile-time type checking and enhanced development experience. It
+         * enables type-safe operations and better IDE support without affecting
+         * the runtime JSON schema representation.
+         *
+         * Enhanced type safety features:
+         * - Strong typing connection to original TypeScript definitions
+         * - Better IDE intellisense and error detection
+         * - Compile-time validation of schema usage patterns
+         * - Type-safe integration with validation and serialization libraries
+         * - Enhanced debugging and development experience
+         *
+         * The property remains optional and undefined to maintain clean JSON
+         * serialization while preserving valuable compile-time information.
+         */
         __type?: Type | undefined;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typia",
-  "version": "9.3.1",
+  "version": "9.5.0-dev.20250710",
   "description": "Superfast runtime validators with only one line",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -41,7 +41,7 @@
   },
   "homepage": "https://typia.io",
   "dependencies": {
-    "@samchon/openapi": "^4.3.1",
+    "@samchon/openapi": "^4.4.1",
     "@standard-schema/spec": "^1.0.0",
     "commander": "^10.0.0",
     "comment-json": "^4.2.3",
@@ -50,7 +50,7 @@
     "randexp": "^0.5.3"
   },
   "peerDependencies": {
-    "@samchon/openapi": ">=4.3.1 <5.0.0",
+    "@samchon/openapi": ">=4.4.1 <5.0.0",
     "typescript": ">=4.8.0 <5.9.0"
   },
   "devDependencies": {

package/src/AssertionGuard.ts

@@ -1 +1,39 @@
-export type AssertionGuard<T> = (input: unknown) => asserts input is T;
+/**
+ * Type definition for assertion guard functions in `typia`.
+ *
+ * An assertion guard is a function that asserts an input value's type at runtime
+ * and performs a TypeScript type assertion if validation passes. Unlike regular
+ * assertion functions that return the validated value, assertion guards return
+ * nothing but automatically cast the input parameter to the expected type `T`.
+ *
+ * This type is used by `typia.createAssertGuard<T>()` and `typia.createAssertGuardEquals<T>()`
+ * to generate reusable assertion guard functions.
+ *
+ * @template T - The expected type to validate and assert against
+ * @param input - The value to validate (type unknown)
+ * @throws {TypeGuardError} When the input value doesn't match the expected type T
+ * @returns void - Returns nothing, but asserts that input is type T
+ *
+ * @example
+ * ```typescript
+ * interface IMember {
+ *   name: string;
+ *   age: number;
+ * }
+ *
+ * // Create reusable assertion guard
+ * const assertMember: AssertionGuard<IMember> = typia.createAssertGuard<IMember>();
+ *
+ * // Usage - input will be automatically cast to IMember if validation passes
+ * const unknownData: unknown = { name: "John", age: 25 };
+ *
+ * assertMember(unknownData);
+ * // After this line, unknownData is automatically treated as IMember type
+ * console.log(unknownData.name); // TypeScript knows this is safe
+ * ```
+ *
+ * @see {@link https://github.com/samchon/typia#assertguard-functions} Typia assertion guards documentation
+ * @see {@link TypeGuardError} Error thrown when assertion fails
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export type AssertionGuard<T> = (input: unknown) => asserts input is T;

package/src/CamelCase.ts

@@ -1,75 +1,75 @@
-import { Equal } from "./typings/Equal";
-import { IsTuple } from "./typings/IsTuple";
-import { NativeClass } from "./typings/NativeClass";
-import { ValueOf } from "./typings/ValueOf";
-
-/**
- * Camel case type.
- *
- * `CamelCase` type is a type that all keys of an object are camelized.
- *
- * It also erase every method properties like {@link Resolved} type.
- *
- * @template T Target type to be camelized
- * @author Jeongho Nam - https://github.com/samchon
- */
-export type CamelCase<T> =
-  Equal<T, CamelizeMain<T>> extends true ? T : CamelizeMain<T>;
-
-type CamelizeMain<T> = T extends [never]
-  ? never // special trick for (jsonable | null) type
-  : T extends { valueOf(): boolean | bigint | number | string }
-    ? ValueOf<T>
-    : T extends Function
-      ? never
-      : T extends object
-        ? CamelizeObject<T>
-        : T;
-
-type CamelizeObject<T extends object> =
-  T extends Array<infer U>
-    ? IsTuple<T> extends true
-      ? CamelizeTuple<T>
-      : CamelizeMain<U>[]
-    : T extends Set<infer U>
-      ? Set<CamelizeMain<U>>
-      : T extends Map<infer K, infer V>
-        ? Map<CamelizeMain<K>, CamelizeMain<V>>
-        : T extends WeakSet<any> | WeakMap<any, any>
-          ? never
-          : T extends NativeClass
-            ? T
-            : {
-                [Key in keyof T as CamelizeString<Key & string>]: CamelizeMain<
-                  T[Key]
-                >;
-              };
-
-type CamelizeTuple<T extends readonly any[]> = T extends []
-  ? []
-  : T extends [infer F]
-    ? [CamelizeMain<F>]
-    : T extends [infer F, ...infer Rest extends readonly any[]]
-      ? [CamelizeMain<F>, ...CamelizeTuple<Rest>]
-      : T extends [(infer F)?]
-        ? [CamelizeMain<F>?]
-        : T extends [(infer F)?, ...infer Rest extends readonly any[]]
-          ? [CamelizeMain<F>?, ...CamelizeTuple<Rest>]
-          : [];
-
-type CamelizeString<Key extends string> = Key extends `_${infer R}`
-  ? `_${CamelizeString<R>}`
-  : Key extends `${infer _F}_${infer _R}`
-    ? CamelizeSnakeString<Key>
-    : Key extends Uppercase<Key>
-      ? Lowercase<Key>
-      : CamelizePascalString<Key>;
-type CamelizePascalString<Key extends string> =
-  Key extends `${infer F}${infer R}` ? `${Lowercase<F>}${R}` : Key;
-type CamelizeSnakeString<Key extends string> = Key extends `_${infer R}`
-  ? CamelizeSnakeString<R>
-  : Key extends `${infer F}_${infer M}${infer R}`
-    ? M extends "_"
-      ? CamelizeSnakeString<`${F}_${R}`>
-      : `${Lowercase<F>}${Uppercase<M>}${CamelizeSnakeString<R>}`
-    : Lowercase<Key>;
+import { Equal } from "./typings/Equal";
+import { IsTuple } from "./typings/IsTuple";
+import { NativeClass } from "./typings/NativeClass";
+import { ValueOf } from "./typings/ValueOf";
+
+/**
+ * Camel case type.
+ *
+ * `CamelCase` type is a type that all keys of an object are camelized.
+ *
+ * It also erase every method properties like {@link Resolved} type.
+ *
+ * @template T Target type to be camelized
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export type CamelCase<T> =
+  Equal<T, CamelizeMain<T>> extends true ? T : CamelizeMain<T>;
+
+type CamelizeMain<T> = T extends [never]
+  ? never // special trick for (jsonable | null) type
+  : T extends { valueOf(): boolean | bigint | number | string }
+    ? ValueOf<T>
+    : T extends Function
+      ? never
+      : T extends object
+        ? CamelizeObject<T>
+        : T;
+
+type CamelizeObject<T extends object> =
+  T extends Array<infer U>
+    ? IsTuple<T> extends true
+      ? CamelizeTuple<T>
+      : CamelizeMain<U>[]
+    : T extends Set<infer U>
+      ? Set<CamelizeMain<U>>
+      : T extends Map<infer K, infer V>
+        ? Map<CamelizeMain<K>, CamelizeMain<V>>
+        : T extends WeakSet<any> | WeakMap<any, any>
+          ? never
+          : T extends NativeClass
+            ? T
+            : {
+                [Key in keyof T as CamelizeString<Key & string>]: CamelizeMain<
+                  T[Key]
+                >;
+              };
+
+type CamelizeTuple<T extends readonly any[]> = T extends []
+  ? []
+  : T extends [infer F]
+    ? [CamelizeMain<F>]
+    : T extends [infer F, ...infer Rest extends readonly any[]]
+      ? [CamelizeMain<F>, ...CamelizeTuple<Rest>]
+      : T extends [(infer F)?]
+        ? [CamelizeMain<F>?]
+        : T extends [(infer F)?, ...infer Rest extends readonly any[]]
+          ? [CamelizeMain<F>?, ...CamelizeTuple<Rest>]
+          : [];
+
+type CamelizeString<Key extends string> = Key extends `_${infer R}`
+  ? `_${CamelizeString<R>}`
+  : Key extends `${infer _F}_${infer _R}`
+    ? CamelizeSnakeString<Key>
+    : Key extends Uppercase<Key>
+      ? Lowercase<Key>
+      : CamelizePascalString<Key>;
+type CamelizePascalString<Key extends string> =
+  Key extends `${infer F}${infer R}` ? `${Lowercase<F>}${R}` : Key;
+type CamelizeSnakeString<Key extends string> = Key extends `_${infer R}`
+  ? CamelizeSnakeString<R>
+  : Key extends `${infer F}_${infer M}${infer R}`
+    ? M extends "_"
+      ? CamelizeSnakeString<`${F}_${R}`>
+      : `${Lowercase<F>}${Uppercase<M>}${CamelizeSnakeString<R>}`
+    : Lowercase<Key>;

package/src/IRandomGenerator.ts

@@ -1,49 +1,49 @@
-import { OpenApi } from "@samchon/openapi";
-
-export interface IRandomGenerator {
-  // REGULAR
-  boolean(): boolean | undefined;
-  number(schema: OpenApi.IJsonSchema.INumber): number;
-  integer(schema: OpenApi.IJsonSchema.IInteger): number;
-  bigint(schema: OpenApi.IJsonSchema.IInteger): bigint;
-  string(schema: OpenApi.IJsonSchema.IString): string;
-  array<T>(
-    schema: Omit<OpenApi.IJsonSchema.IArray, "items"> & {
-      element: (index: number, count: number) => T;
-    },
-  ): T[];
-  pattern(regex: RegExp): string;
-
-  //----
-  // FORMAT
-  //----
-  // SPECIAL CHARACTERS
-  byte(): string;
-  password(): string;
-  regex(): string;
-  uuid(): string;
-
-  // ADDRESSES
-  email(): string;
-  hostname(): string;
-  idnEmail(): string;
-  idnHostname(): string;
-  iri(): string;
-  iriReference(): string;
-  ipv4(): string;
-  ipv6(): string;
-  uri(): string;
-  uriReference(): string;
-  uriTemplate(): string;
-  url(): string;
-
-  // TIMESTAMPS
-  datetime(props?: { minimum?: number; maximum?: number }): string;
-  date(props?: { minimum?: number; maximum?: number }): string;
-  time(): string;
-  duration(): string;
-
-  // POINTERS
-  jsonPointer(): string;
-  relativeJsonPointer(): string;
-}
+import { OpenApi } from "@samchon/openapi";
+
+export interface IRandomGenerator {
+  // REGULAR
+  boolean(): boolean | undefined;
+  number(schema: OpenApi.IJsonSchema.INumber): number;
+  integer(schema: OpenApi.IJsonSchema.IInteger): number;
+  bigint(schema: OpenApi.IJsonSchema.IInteger): bigint;
+  string(schema: OpenApi.IJsonSchema.IString): string;
+  array<T>(
+    schema: Omit<OpenApi.IJsonSchema.IArray, "items"> & {
+      element: (index: number, count: number) => T;
+    },
+  ): T[];
+  pattern(regex: RegExp): string;
+
+  //----
+  // FORMAT
+  //----
+  // SPECIAL CHARACTERS
+  byte(): string;
+  password(): string;
+  regex(): string;
+  uuid(): string;
+
+  // ADDRESSES
+  email(): string;
+  hostname(): string;
+  idnEmail(): string;
+  idnHostname(): string;
+  iri(): string;
+  iriReference(): string;
+  ipv4(): string;
+  ipv6(): string;
+  uri(): string;
+  uriReference(): string;
+  uriTemplate(): string;
+  url(): string;
+
+  // TIMESTAMPS
+  datetime(props?: { minimum?: number; maximum?: number }): string;
+  date(props?: { minimum?: number; maximum?: number }): string;
+  time(): string;
+  duration(): string;
+
+  // POINTERS
+  jsonPointer(): string;
+  relativeJsonPointer(): string;
+}

package/src/IReadableURLSearchParams.ts

@@ -1,9 +1,9 @@
-/**
- * Interface for a readable URLSearchParams object.
- *
- * This interface is a subset of the {@link URLSearchParams} interface,
- * designed especially for the [Hono.JS](https://hono.dev/) library.
- *
- * @author https://github.com/miyaji255
- */
-export type IReadableURLSearchParams = Pick<URLSearchParams, "get" | "getAll">;
+/**
+ * Interface for a readable URLSearchParams object.
+ *
+ * This interface is a subset of the {@link URLSearchParams} interface,
+ * designed especially for the [Hono.JS](https://hono.dev/) library.
+ *
+ * @author https://github.com/miyaji255
+ */
+export type IReadableURLSearchParams = Pick<URLSearchParams, "get" | "getAll">;

package/src/IValidation.ts

@@ -1 +1 @@
-export { IValidation } from "@samchon/openapi";
+export { IValidation } from "@samchon/openapi";