typia 9.7.1 → 10.0.0-dev.20251107

package/src/schemas/json/IJsonSchemaUnit.ts

@@ -1,250 +1,263 @@
-import { OpenApi, OpenApiV3 } from "@samchon/openapi";
-
-/**
- * Single unit of JSON schema representation.
- *
- * `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.
- *
- * 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 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.
-   */
-  export 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.
-   */
-  export 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;
-  }
-}
+import { OpenApi, OpenApiV3 } from "@samchon/openapi";
+
+/**
+ * Single unit of JSON schema representation.
+ *
+ * `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.
+ *
+ * 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
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @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>
+ *   ```;
+ *
+ * @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.
+ * @see {@link IJsonSchemaCollection} For handling multiple schemas at once
+ */
+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 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.
+   */
+  export 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.
+   */
+  export 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/src/schemas/metadata/IMetadataTypeTag.ts

@@ -1,16 +1,14 @@
-import type ts from "typescript";
-
-export interface IMetadataTypeTag {
-  target: "boolean" | "bigint" | "number" | "string" | "array" | "object";
-  name: string;
-  kind: string;
-  exclusive: boolean | string[];
-  value?: any;
-  validate?: string | undefined;
-  schema?: object | undefined;
-
-  /**
-   * @internal
-   */
-  predicate?: (input: ts.Expression) => ts.Expression;
-}
+import type ts from "typescript";
+
+export interface IMetadataTypeTag {
+  target: "boolean" | "bigint" | "number" | "string" | "array" | "object";
+  name: string;
+  kind: string;
+  exclusive: boolean | string[];
+  value?: any;
+  validate?: string | undefined;
+  schema?: object | undefined;
+
+  /** @internal */
+  predicate?: (input: ts.Expression) => ts.Expression;
+}