import { OpenApi } from "../openapi/OpenApi";
import { OpenApiV3 } from "../openapi/OpenApiV3";

/**
 * Single JSON schema unit for one TypeScript type.
 *
 * `IJsonSchemaUnit` represents a complete JSON schema for a single TypeScript
 * type, including the main schema definition and any referenced component
 * schemas. Generated by `typia.json.schema<T>()` at compile time.
 *
 * The result contains:
 *
 * - {@link IV3_0.schema | schema}: The main JSON schema for the type
 * - {@link IV3_0.components | components}: Shared schemas referenced via `$ref`
 * - {@link IV3_0.__type | __type}: Phantom property for TypeScript type inference
 *
 * Use this for single-type schema generation. For multiple types, see
 * {@link IJsonSchemaCollection}. For function schemas, see
 * {@link IJsonSchemaApplication}.
 *
 * @author Jeongho Nam - https://github.com/samchon
 * @template Version OpenAPI version ("3.0" or "3.1")
 * @template Type Original TypeScript type
 */
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 for OpenAPI v3.0 specification.
   *
   * Uses OpenAPI v3.0 compatible JSON Schema format. In v3.0, nullable types
   * are expressed with `nullable: true` rather than v3.1's `type: ["string",
   * "null"]`.
   *
   * @template Type Original TypeScript type for phantom type preservation
   */
  export interface IV3_0<Type> {
    /**
     * OpenAPI specification version.
     *
     * Always `"3.0"` for this variant. Use this discriminator to determine
     * which schema format is in use.
     */
    version: "3.0";

    /**
     * The main JSON schema definition for the type.
     *
     * Contains the complete schema for the target TypeScript type. May include
     * `$ref` references to schemas in {@link components}.
     */
    schema: OpenApiV3.IJsonSchema;

    /**
     * Reusable schema definitions for `$ref` references.
     *
     * Contains named schemas that can be referenced throughout the main schema.
     * Essential for recursive types and reducing duplication.
     */
    components: OpenApiV3.IComponents;

    /**
     * Phantom property for TypeScript generic type preservation.
     *
     * This property exists only in the type system to preserve the `Type`
     * generic parameter. It is always `undefined` at runtime and should not be
     * accessed or used in application code.
     */
    __type?: Type | undefined;
  }

  /**
   * JSON Schema unit for OpenAPI v3.1 specification.
   *
   * Uses OpenAPI v3.1 compatible JSON Schema format. v3.1 aligns more closely
   * with JSON Schema draft 2020-12, supporting features like `type` arrays for
   * nullable types and `const` values.
   *
   * @template Type Original TypeScript type for phantom type preservation
   */
  export interface IV3_1<Type> {
    /**
     * OpenAPI specification version.
     *
     * Always `"3.1"` for this variant. Use this discriminator to determine
     * which schema format is in use.
     */
    version: "3.1";

    /**
     * The main JSON schema definition for the type.
     *
     * Contains the complete schema for the target TypeScript type. May include
     * `$ref` references to schemas in {@link components}.
     */
    schema: OpenApi.IJsonSchema;

    /**
     * Reusable schema definitions for `$ref` references.
     *
     * Contains named schemas that can be referenced throughout the main schema.
     * Essential for recursive types and reducing duplication.
     */
    components: OpenApi.IComponents;

    /**
     * Phantom property for TypeScript generic type preservation.
     *
     * This property exists only in the type system to preserve the `Type`
     * generic parameter. It is always `undefined` at runtime and should not be
     * accessed or used in application code.
     */
    __type?: Type | undefined;
  }
}