razeri_plugin_contract/

data_type.rs

// Copyright (C) 2026 Gabriel Shea
// Licensed under either of the Apache License, Version 2.0 or the MIT
// license, at your option.

//! Generic data types for cross-database compatibility.
//!
//! This module defines the unified [`DataType`] enum and all component types
//! (integer, decimal, float, boolean, string, binary, date/time, special, and
//! collection types) that serve as the foundation for SQL rendering across
//! all supported database platforms.
//!
//! # Design Philosophy
//!
//! - **Abstract over database-specific implementations** — `DataType` captures
//!   enough metadata to generate correct DDL for each target, but does not
//!   embed platform-specific syntax.
//! - **Preserve precision metadata** — Decimal types carry precision and scale;
//!   string types carry length constraints; timestamp types carry fractional
//!   seconds precision.
//! - **Every type renders somewhere** — a dialect answers for every variant,
//!   emulating a type it does not have (JSON stored as `NVARCHAR(MAX)` on SQL
//!   Server, a struct stored as `jsonb` on `PostgreSQL`) rather than refusing.
//!
//! # Type Categories
//!
//! | Category | Types | Example |
//! |----------|-------|---------|
//! | Integer | [`IntegerDataType`] | `INT`, `BIGINT`, `TINYINT` |
//! | Decimal | [`DecimalDataType`] | `DECIMAL(19,4)`, `DECIMAL(5,2)` |
//! | Float | [`FloatDataType`] | `REAL`, `DOUBLE` |
//! | Boolean | [`BooleanDataType`] | `BOOLEAN`, `BIT` |
//! | String | [`CharDataType`], [`VarCharDataType`], [`TextDataType`] | `VARCHAR(100)`, `TEXT` |
//! | Binary | [`BinaryDataType`], [`VarBinaryDataType`] | `BYTEA`, `VARBINARY` |
//! | Date/Time | [`DateDataType`], [`TimestampDataType`], [`TimestampTzDataType`] | `DATE`, `TIMESTAMP` |
//! | Special | [`UuidDataType`], [`JsonDataType`] | `UUID`, `JSONB` |
//! | Collection | [`ArrayDataType`], [`MapDataType`], [`StructDataType`] | `INTEGER[]`, `MAP<TEXT,INT>`, `STRUCT<a INT>` |
//!
//! # Usage
//!
//! Convenience constructors for common types:
//!
//! ```rust
//! use razeri_plugin_contract::DataType;
//!
//! let id = DataType::bigint();
//! let name = DataType::varchar(255);
//! let price = DataType::decimal(19, 4);
//! let created = DataType::timestamp();
//!
//! // JSON with binary storage (JSONB in PostgreSQL, VARIANT in Snowflake)
//! let data = DataType::json();
//! ```
//!
//! Each variant maps to platform-specific types as documented in the variant
//! definitions. Dialect plugins resolve the final SQL type string during
//! rendering; the rendering traits live in this crate's `renderer` module.

// ============================================================================
// Integer Types
// ============================================================================

/// Integer size variants matching common database integer types.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum IntegerSize {
    /// 1 byte: -128 to 127 (signed) or 0 to 255 (unsigned)
    /// Maps to: TINYINT (SQL Server, Snowflake, Databricks), SMALLINT (`PostgreSQL`), Int8/UInt8 (`ClickHouse`)
    Tiny,
    /// 2 bytes: -32,768 to 32,767 (signed)
    /// Maps to: SMALLINT (all databases), Int16/UInt16 (`ClickHouse`)
    Small,
    /// 4 bytes: -2.1B to 2.1B (signed)
    /// Maps to: INT/INTEGER (all databases), Int32/UInt32 (`ClickHouse`)
    Standard,
    /// 8 bytes: -9.2E18 to 9.2E18 (signed)
    /// Maps to: BIGINT (all databases), Int64/UInt64 (`ClickHouse`)
    Big,
}

/// Integer data type supporting signed/unsigned variants.
///
/// Most databases only support signed integers. `ClickHouse` is the exception,
/// supporting unsigned variants via `UInt8`, `UInt16`, `UInt32`, `UInt64`.
/// Other dialect plugins will map unsigned types to the next larger signed type
/// when unsigned is not supported.
///
/// # Example
///
/// ```rust
/// use razeri_plugin_contract::{DataType, data_type::{IntegerDataType, IntegerSize}};
///
/// // Signed 4-byte integer (INT/INTEGER on most platforms)
/// let _id = DataType::int();
///
/// // Unsigned 8-byte integer (UInt64 in ClickHouse, BIGINT elsewhere)
/// let big = IntegerDataType::unsigned(IntegerSize::Big);
/// assert_eq!(big.byte_size(), 8);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct IntegerDataType {
    /// Size of the integer (Tiny, Small, Standard, Big).
    pub size: IntegerSize,

    /// Whether the integer is unsigned.
    ///
    /// Only `ClickHouse` fully supports unsigned integers. Other dialect plugins
    /// will map unsigned types to the next larger signed type when unsigned is
    /// not supported by the target platform.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::{IntegerDataType, IntegerSize};
    ///
    /// let signed = IntegerDataType::new(IntegerSize::Standard);
    /// assert!(!signed.unsigned);
    ///
    /// let unsigned = IntegerDataType::unsigned(IntegerSize::Big);
    /// assert!(unsigned.unsigned);
    /// ```
    pub unsigned: bool,
}

impl IntegerDataType {
    /// Creates a new signed integer with the given [`IntegerSize`].
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::{IntegerDataType, IntegerSize};
    ///
    /// let small = IntegerDataType::new(IntegerSize::Small);
    /// assert_eq!(small.byte_size(), 2);
    /// ```
    #[must_use]
    pub fn new(size: IntegerSize) -> Self {
        Self { size, unsigned: false }
    }

    /// Creates a new unsigned integer with the given [`IntegerSize`].
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::{IntegerDataType, IntegerSize};
    ///
    /// let unsigned_big = IntegerDataType::unsigned(IntegerSize::Big);
    /// assert!(unsigned_big.unsigned);
    /// assert_eq!(unsigned_big.byte_size(), 8);
    /// ```
    #[must_use]
    pub fn unsigned(size: IntegerSize) -> Self {
        Self { size, unsigned: true }
    }

    /// Returns the byte size of this integer type.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::{IntegerDataType, IntegerSize};
    ///
    /// assert_eq!(IntegerDataType::new(IntegerSize::Tiny).byte_size(), 1);
    /// assert_eq!(IntegerDataType::new(IntegerSize::Small).byte_size(), 2);
    /// assert_eq!(IntegerDataType::new(IntegerSize::Standard).byte_size(), 4);
    /// assert_eq!(IntegerDataType::new(IntegerSize::Big).byte_size(), 8);
    /// ```
    #[must_use]
    pub fn byte_size(&self) -> usize {
        match self.size {
            IntegerSize::Tiny => 1,
            IntegerSize::Small => 2,
            IntegerSize::Standard => 4,
            IntegerSize::Big => 8,
        }
    }
}

// ============================================================================
// Decimal/Numeric Types (Exact Precision)
// ============================================================================

/// Exact numeric type with fixed precision and scale.
///
/// Maps to: `NUMERIC`/`DECIMAL` (`PostgreSQL`, SQL Server), `NUMBER` (Snowflake),
/// `DECIMAL` (Databricks), `Decimal` (`ClickHouse`).
///
/// # Constraints
///
/// - `precision`: 1–38 (most databases), up to 76 (some platforms)
/// - `scale`: 0 to `precision`
/// - Panics if `scale > precision` or `precision > 38`
///
/// # Example
///
/// ```rust
/// use razeri_plugin_contract::data_type::DecimalDataType;
///
/// // Money: DECIMAL(19, 4)
/// let money = DecimalDataType::money();
/// assert_eq!(money.precision, 19);
/// assert_eq!(money.scale, 4);
///
/// // Percentage: DECIMAL(5, 2)
/// let pct = DecimalDataType::percentage();
/// assert_eq!(pct.precision, 5);
/// assert_eq!(pct.scale, 2);
///
/// // Custom decimal
/// let custom = DecimalDataType::new(10, 2);
/// assert_eq!(custom.precision, 10);
/// assert_eq!(custom.scale, 2);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct DecimalDataType {
    /// Total number of digits (1–38 for most databases, up to 76 for some).
    pub precision: u8,

    /// Number of digits after the decimal point (0 to `precision`).
    pub scale: u8,
}

impl DecimalDataType {
    /// Creates a new decimal type with the given precision and scale.
    ///
    /// # Panics
    ///
    /// Panics if `precision` is 0 or exceeds 38, or if `scale > precision`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::DecimalDataType;
    ///
    /// let dec = DecimalDataType::new(10, 2);
    /// assert_eq!(dec.precision, 10);
    /// assert_eq!(dec.scale, 2);
    /// ```
    ///
    /// # Panics
    ///
    /// ```should_panic
    /// use razeri_plugin_contract::data_type::DecimalDataType;
    ///
    /// // Precision must be 1-38
    /// let _ = DecimalDataType::new(0, 0); // panics
    ///
    /// // Scale cannot exceed precision
    /// let _ = DecimalDataType::new(5, 10); // panics
    /// ```
    #[must_use]
    pub fn new(precision: u8, scale: u8) -> Self {
        assert!(precision > 0 && precision <= 38, "Precision must be 1-38");
        assert!(scale <= precision, "Scale cannot exceed precision");
        Self { precision, scale }
    }

    /// Creates the common money type: `DECIMAL(19, 4)`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::DecimalDataType;
    ///
    /// let money = DecimalDataType::money();
    /// assert_eq!(money.precision, 19);
    /// assert_eq!(money.scale, 4);
    /// ```
    #[must_use]
    pub fn money() -> Self {
        Self { precision: 19, scale: 4 }
    }

    /// Creates a percentage type with 2 decimal places: `DECIMAL(5, 2)`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::DecimalDataType;
    ///
    /// let pct = DecimalDataType::percentage();
    /// assert_eq!(pct.precision, 5);
    /// assert_eq!(pct.scale, 2);
    /// ```
    #[must_use]
    pub fn percentage() -> Self {
        Self { precision: 5, scale: 2 }
    }
}

// ============================================================================
// Floating Point Types (Approximate)
// ============================================================================

/// Floating point precision variants.
///
/// # Example
///
/// ```rust
/// use razeri_plugin_contract::data_type::FloatPrecision;
///
/// let single = FloatPrecision::Single;
/// let double = FloatPrecision::Double;
///
/// assert_eq!(format!("{:?}", single), "Single");
/// assert_eq!(format!("{:?}", double), "Double");
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum FloatPrecision {
    /// Single precision (4 bytes, ~7 decimal digits).
    ///
    /// Maps to: `REAL`/`FLOAT4` (`PostgreSQL`), `REAL`/`FLOAT(24)` (SQL Server),
    /// `FLOAT` (Snowflake, Databricks), `Float32` (`ClickHouse`).
    Single,
    /// Double precision (8 bytes, ~15 decimal digits).
    ///
    /// Maps to: `DOUBLE PRECISION`/`FLOAT8` (`PostgreSQL`), `FLOAT` (SQL Server),
    /// `DOUBLE` (Snowflake, Databricks), `Float64` (`ClickHouse`).
    Double,
}

/// Approximate floating-point numeric type.
///
/// Maps to: `REAL`/`DOUBLE PRECISION` (`PostgreSQL`), `REAL`/`FLOAT` (SQL Server),
/// `FLOAT`/`DOUBLE` (Snowflake, Databricks), `Float32`/`Float64` (`ClickHouse`).
///
/// # Example
///
/// ```
/// use razeri_plugin_contract::DataType;
///
/// // Single precision (REAL)
/// let real = DataType::float();
///
/// // Double precision (DOUBLE)
/// let double = DataType::double();
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct FloatDataType {
    /// Precision level (Single or Double).
    pub precision: FloatPrecision,
}

impl FloatDataType {
    /// Creates a single-precision (4-byte) float type.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::{FloatDataType, FloatPrecision};
    ///
    /// let single = FloatDataType::single();
    /// assert_eq!(single.precision, FloatPrecision::Single);
    /// ```
    #[must_use]
    pub fn single() -> Self {
        Self { precision: FloatPrecision::Single }
    }

    /// Creates a double-precision (8-byte) float type.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::{FloatDataType, FloatPrecision};
    ///
    /// let double = FloatDataType::double();
    /// assert_eq!(double.precision, FloatPrecision::Double);
    /// ```
    #[must_use]
    pub fn double() -> Self {
        Self { precision: FloatPrecision::Double }
    }
}

// ============================================================================
// Boolean Type
// ============================================================================

/// Boolean data type (true/false).
///
/// Maps to: `BOOLEAN` (`PostgreSQL`, Snowflake, Databricks, `ClickHouse`),
/// `BIT` (SQL Server), `Bool`/`UInt8` (`ClickHouse`).
///
/// # Example
///
/// ```
/// use razeri_plugin_contract::DataType;
///
/// let bool_type = DataType::boolean();
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub struct BooleanDataType;

// ============================================================================
// String/Text Types
// ============================================================================

/// Character encoding for string types.
///
/// Determines whether strings use ASCII/Latin1 (1 byte per character) or
/// UTF-8/Unicode (variable bytes per character). The default is `Unicode`.
///
/// # Example
///
/// ```rust
/// use razeri_plugin_contract::data_type::StringEncoding;
///
/// let ascii = StringEncoding::Ascii;
/// let unicode = StringEncoding::Unicode;
///
/// assert_eq!(ascii, StringEncoding::Ascii);
/// assert_eq!(unicode, StringEncoding::Unicode);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub enum StringEncoding {
    /// ASCII/Latin1 encoding (1 byte per character).
    ///
    /// Maps to: `CHAR`/`VARCHAR` (SQL Server), `CHAR`/`VARCHAR` (`PostgreSQL`).
    Ascii,
    /// UTF-8/Unicode encoding (variable bytes per character).
    ///
    /// Maps to: `NCHAR`/`NVARCHAR` (SQL Server), all strings in
    /// `PostgreSQL`/Snowflake/`ClickHouse`.
    #[default]
    Unicode,
}

/// Fixed-length character string.
///
/// Maps to: `CHAR(n)` (`PostgreSQL`, SQL Server, Snowflake), `FixedString(n)` (`ClickHouse`).
/// Note: Databricks does not have a fixed-length char type.
///
/// # Example
///
/// ```rust
/// use razeri_plugin_contract::data_type::{CharDataType, StringEncoding};
///
/// // Default: Unicode encoding
/// let char_type = CharDataType::new(50);
/// assert_eq!(char_type.length, 50);
///
/// // Explicit ASCII encoding
/// let ascii_char = CharDataType::with_encoding(10, StringEncoding::Ascii);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct CharDataType {
    /// Fixed length in characters (1-8000 for SQL Server, 1-16777216 for Snowflake).
    pub length: u32,

    /// Character encoding (default: Unicode).
    pub encoding: StringEncoding,
}

impl CharDataType {
    /// Creates a fixed-length character string with Unicode encoding.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::CharDataType;
    ///
    /// let char = CharDataType::new(100);
    /// assert_eq!(char.length, 100);
    /// ```
    #[must_use]
    pub fn new(length: u32) -> Self {
        Self { length, encoding: StringEncoding::Unicode }
    }

    /// Creates a fixed-length character string with the specified encoding.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::{CharDataType, StringEncoding};
    ///
    /// let ascii = CharDataType::with_encoding(20, StringEncoding::Ascii);
    /// assert_eq!(ascii.encoding, StringEncoding::Ascii);
    /// ```
    #[must_use]
    pub fn with_encoding(length: u32, encoding: StringEncoding) -> Self {
        Self { length, encoding }
    }
}

/// Variable-length character string with optional max length.
///
/// Maps to: `VARCHAR(n)` (`PostgreSQL`, SQL Server, Snowflake), `STRING` (Databricks, `ClickHouse`).
///
/// # Example
///
/// ```rust
/// use razeri_plugin_contract::data_type::{VarCharDataType, StringEncoding};
///
/// // Fixed max length
/// let varchar = VarCharDataType::new(255);
/// assert_eq!(varchar.max_length, Some(255));
///
/// // Unlimited length (TEXT/VARCHAR(MAX)/STRING)
/// let text = VarCharDataType::unlimited();
/// assert_eq!(text.max_length, None);
///
/// // Explicit ASCII encoding
/// let ascii = VarCharDataType::with_encoding(Some(100), StringEncoding::Ascii);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct VarCharDataType {
    /// Maximum length in characters (None = unlimited/MAX).
    ///
    /// The longest an engine takes is its dialect's answer, in
    /// [`DialectCapabilities::text_limits`](crate::DialectCapabilities::text_limits).
    pub max_length: Option<u32>,

    /// Character encoding (default: Unicode).
    pub encoding: StringEncoding,
}

impl VarCharDataType {
    /// Creates a VARCHAR with specified max length.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::VarCharDataType;
    ///
    /// let varchar = VarCharDataType::new(100);
    /// assert_eq!(varchar.max_length, Some(100));
    /// ```
    #[must_use]
    pub fn new(max_length: u32) -> Self {
        Self { max_length: Some(max_length), encoding: StringEncoding::Unicode }
    }

    /// Creates an unlimited length text type (`VARCHAR(MAX)`, `TEXT`, `STRING`).
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::VarCharDataType;
    ///
    /// let text = VarCharDataType::unlimited();
    /// assert_eq!(text.max_length, None);
    /// ```
    #[must_use]
    pub fn unlimited() -> Self {
        Self { max_length: None, encoding: StringEncoding::Unicode }
    }

    /// Creates a VARCHAR with the specified length and encoding.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::{VarCharDataType, StringEncoding};
    ///
    /// let ascii = VarCharDataType::with_encoding(Some(50), StringEncoding::Ascii);
    /// assert_eq!(ascii.max_length, Some(50));
    /// assert_eq!(ascii.encoding, StringEncoding::Ascii);
    /// ```
    #[must_use]
    pub fn with_encoding(max_length: Option<u32>, encoding: StringEncoding) -> Self {
        Self { max_length, encoding }
    }
}

/// Unbounded text type for large text storage.
///
/// Maps to: `TEXT` (`PostgreSQL`), `VARCHAR(MAX)` (SQL Server),
/// `STRING` (Snowflake, Databricks, `ClickHouse`).
///
/// # Example
///
/// ```
/// use razeri_plugin_contract::DataType;
///
/// let text = DataType::text();
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub struct TextDataType;

// ============================================================================
// Binary Types
// ============================================================================

/// Fixed-length binary data.
///
/// Maps to: `BYTEA` (`PostgreSQL`), `BINARY(n)` (SQL Server, Snowflake),
/// `FixedString(n)` (`ClickHouse`).
///
/// # Example
///
/// ```rust
/// use razeri_plugin_contract::data_type::BinaryDataType;
///
/// let binary = BinaryDataType::new(256);
/// assert_eq!(binary.length, 256);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct BinaryDataType {
    /// Fixed length in bytes.
    pub length: u32,
}

impl BinaryDataType {
    /// Creates a fixed-length binary type with the given length in bytes.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::BinaryDataType;
    ///
    /// let binary = BinaryDataType::new(128);
    /// assert_eq!(binary.length, 128);
    /// ```
    #[must_use]
    pub fn new(length: u32) -> Self {
        Self { length }
    }
}

/// Variable-length binary data.
///
/// Maps to: `BYTEA` (`PostgreSQL`), `VARBINARY(n)` (SQL Server, Snowflake),
/// `String` (`ClickHouse`), `BINARY` (Databricks).
///
/// # Example
///
/// ```rust
/// use razeri_plugin_contract::data_type::VarBinaryDataType;
///
/// // Fixed max length
/// let vb = VarBinaryDataType::new(1024);
/// assert_eq!(vb.max_length, Some(1024));
///
/// // Unlimited length
/// let blob = VarBinaryDataType::unlimited();
/// assert_eq!(blob.max_length, None);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct VarBinaryDataType {
    /// Maximum length in bytes (None = unlimited/MAX).
    pub max_length: Option<u32>,
}

impl VarBinaryDataType {
    /// Creates a variable-length binary type with the specified max length in bytes.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::VarBinaryDataType;
    ///
    /// let vb = VarBinaryDataType::new(2048);
    /// assert_eq!(vb.max_length, Some(2048));
    /// ```
    #[must_use]
    pub fn new(max_length: u32) -> Self {
        Self { max_length: Some(max_length) }
    }

    /// Creates an unlimited-length binary type (BYTEA, VARBINARY(MAX), etc.).
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::VarBinaryDataType;
    ///
    /// let blob = VarBinaryDataType::unlimited();
    /// assert_eq!(blob.max_length, None);
    /// ```
    #[must_use]
    pub fn unlimited() -> Self {
        Self { max_length: None }
    }
}

// ============================================================================
// Date and Time Types
// ============================================================================

/// Date only (year, month, day) without time component.
///
/// Maps to: `DATE` (all databases), `Date`/`Date32` (`ClickHouse`).
///
/// # Example
///
/// ```
/// use razeri_plugin_contract::DataType;
///
/// let date = DataType::date();
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub struct DateDataType;

/// Time only without date component.
///
/// Maps to: `TIME` (`PostgreSQL`, SQL Server, Snowflake), not directly supported in
/// `ClickHouse`/Databricks.
///
/// # Precision
///
/// - `PostgreSQL`: 0-6
/// - SQL Server: 0-7
/// - Snowflake: 0-9
/// - `ClickHouse`: 0-9
///
/// # Example
///
/// ```rust
/// use razeri_plugin_contract::data_type::TimeDataType;
///
/// // Default precision: 6, no timezone
/// let time = TimeDataType::default();
/// assert_eq!(time.precision, 6);
/// assert!(!time.with_timezone);
///
/// // Precision 3, with timezone
/// let tz_time = TimeDataType::with_timezone(3);
/// assert_eq!(tz_time.precision, 3);
/// assert!(tz_time.with_timezone);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct TimeDataType {
    /// Fractional seconds precision (0-7 for SQL Server, 0-6 for `PostgreSQL`, 0-9 for Snowflake).
    pub precision: u8,

    /// Whether to include timezone offset.
    ///
    /// Maps to: `TIME WITH TIME ZONE` (`PostgreSQL`), not supported in SQL Server.
    pub with_timezone: bool,
}

impl TimeDataType {
    /// Creates a new `TimeDataType` with the given fractional seconds precision.
    ///
    /// # Panics
    ///
    /// Panics if `precision` exceeds 9.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::TimeDataType;
    ///
    /// let time = TimeDataType::new(3);
    /// assert_eq!(time.precision, 3);
    /// assert!(!time.with_timezone);
    /// ```
    ///
    /// ```rust,should_panic
    /// use razeri_plugin_contract::data_type::TimeDataType;
    ///
    /// let _ = TimeDataType::new(10); // panics: precision must be 0-9
    /// ```
    #[must_use]
    pub fn new(precision: u8) -> Self {
        assert!(precision <= 9, "Time precision must be 0-9");
        Self { precision, with_timezone: false }
    }

    /// Creates a `TimeDataType` with timezone and the given precision.
    ///
    /// # Panics
    ///
    /// Panics if `precision` exceeds 9.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::TimeDataType;
    ///
    /// let tz_time = TimeDataType::with_timezone(3);
    /// assert_eq!(tz_time.precision, 3);
    /// assert!(tz_time.with_timezone);
    /// ```
    #[must_use]
    pub fn with_timezone(precision: u8) -> Self {
        assert!(precision <= 9, "Time precision must be 0-9");
        Self { precision, with_timezone: true }
    }
}

impl Default for TimeDataType {
    fn default() -> Self {
        Self { precision: 6, with_timezone: false }
    }
}

/// Timestamp (date and time) without timezone.
///
/// Maps to: `TIMESTAMP` (`PostgreSQL`), `DATETIME2` (SQL Server),
/// `TIMESTAMP_NTZ` (Snowflake), `TIMESTAMP` (Databricks), `DateTime` (`ClickHouse`).
///
/// # Precision
///
/// - `PostgreSQL`: 0-6
/// - SQL Server: 0-7
/// - Snowflake: 0-9
/// - `ClickHouse`: 0-9
///
/// # Example
///
/// ```rust
/// use razeri_plugin_contract::data_type::{DataType, TimestampDataType};
///
/// // Default: precision 6
/// let ts = TimestampDataType::default();
/// assert_eq!(ts.precision, 6);
///
/// // Custom precision
/// let ts3 = TimestampDataType::new(3);
/// assert_eq!(ts3.precision, 3);
///
/// // Via DataType convenience
/// let created = DataType::timestamp();
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct TimestampDataType {
    /// Fractional seconds precision (0-9).
    ///
    /// - `PostgreSQL`: 0-6
    /// - SQL Server: 0-7
    /// - Snowflake: 0-9
    /// - `ClickHouse`: 0-9
    pub precision: u8,
}

impl TimestampDataType {
    /// Creates a new `TimestampDataType` with the given fractional seconds precision.
    ///
    /// # Panics
    ///
    /// Panics if `precision` exceeds 9.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::TimestampDataType;
    ///
    /// let ts = TimestampDataType::new(3);
    /// assert_eq!(ts.precision, 3);
    /// ```
    ///
    /// ```should_panic
    /// use razeri_plugin_contract::data_type::TimestampDataType;
    ///
    /// let _ = TimestampDataType::new(10); // panics: precision must be 0-9
    /// ```
    #[must_use]
    pub fn new(precision: u8) -> Self {
        assert!(precision <= 9, "Timestamp precision must be 0-9");
        Self { precision }
    }
}

impl Default for TimestampDataType {
    fn default() -> Self {
        Self { precision: 6 }
    }
}

/// Timestamp with timezone awareness.
///
/// Maps to: `TIMESTAMPTZ` (`PostgreSQL`), `DATETIMEOFFSET` (SQL Server),
/// `TIMESTAMP_TZ`/`TIMESTAMP_LTZ` (Snowflake), `TIMESTAMP` (Databricks),
/// `DateTime64` (`ClickHouse`).
///
/// # Example
///
/// ```rust
/// use razeri_plugin_contract::DataType;
/// use razeri_plugin_contract::data_type::TimestampTzDataType;
///
/// // Default: precision 6
/// let ts = TimestampTzDataType::default();
/// assert_eq!(ts.precision, 6);
///
/// // Via DataType convenience
/// let created_tz = DataType::timestamp_tz();
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct TimestampTzDataType {
    /// Fractional seconds precision (0-9).
    pub precision: u8,
}

impl TimestampTzDataType {
    /// Creates a new `TimestampTzDataType` with the given fractional seconds precision.
    ///
    /// # Panics
    ///
    /// Panics if `precision` exceeds 9.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::TimestampTzDataType;
    ///
    /// let ts = TimestampTzDataType::new(3);
    /// assert_eq!(ts.precision, 3);
    /// ```
    ///
    /// ```should_panic
    /// use razeri_plugin_contract::data_type::TimestampTzDataType;
    ///
    /// let _ = TimestampTzDataType::new(10); // panics: precision must be 0-9
    /// ```
    #[must_use]
    pub fn new(precision: u8) -> Self {
        assert!(precision <= 9, "Timestamp precision must be 0-9");
        Self { precision }
    }
}

impl Default for TimestampTzDataType {
    fn default() -> Self {
        Self { precision: 6 }
    }
}

/// Combined date and time for legacy compatibility.
///
/// Maps to: `DATETIME` (SQL Server legacy), `TIMESTAMP` (`PostgreSQL`).
/// Prefer [`TimestampDataType`] for new designs.
///
/// # Example
///
/// ```rust
/// use razeri_plugin_contract::data_type::DateTimeDataType;
///
/// let dt = DateTimeDataType::new(3, true);
/// assert_eq!(dt.precision, 3);
/// assert!(dt.with_timezone);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct DateTimeDataType {
    /// Fractional seconds precision (0-9).
    pub precision: u8,

    /// Whether to include timezone offset.
    pub with_timezone: bool,
}

impl DateTimeDataType {
    /// Creates a new `DateTimeDataType` with the given precision and timezone flag.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::DateTimeDataType;
    ///
    /// let dt = DateTimeDataType::new(6, false);
    /// assert_eq!(dt.precision, 6);
    /// assert!(!dt.with_timezone);
    /// ```
    #[must_use]
    pub fn new(precision: u8, with_timezone: bool) -> Self {
        Self { precision, with_timezone }
    }
}

impl Default for DateTimeDataType {
    fn default() -> Self {
        Self { precision: 6, with_timezone: false }
    }
}

/// Interval/duration type for time spans.
///
/// Maps to: `INTERVAL` (`PostgreSQL`, Snowflake, Databricks), not directly supported in
/// SQL Server/`ClickHouse`.
///
/// # Example
///
/// ```rust
/// use razeri_plugin_contract::data_type::IntervalDataType;
///
/// let ym = IntervalDataType::YearMonth;
/// let dt = IntervalDataType::DayTime;
///
/// assert_eq!(format!("{:?}", ym), "YearMonth");
/// assert_eq!(format!("{:?}", dt), "DayTime");
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum IntervalDataType {
    /// Year to month intervals.
    YearMonth,
    /// Day to second intervals (with optional fractional seconds precision).
    DayTime,
}

// ============================================================================
// Special Types
// ============================================================================

/// Universally Unique Identifier (UUID/GUID).
///
/// Maps to: `UUID` (`PostgreSQL`), `UNIQUEIDENTIFIER` (SQL Server),
/// `STRING` (Snowflake, Databricks), `UUID` (`ClickHouse`).
///
/// # Example
///
/// ```
/// use razeri_plugin_contract::DataType;
///
/// let uuid = DataType::uuid();
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub struct UuidDataType;

/// JSON storage format preference.
///
/// Determines whether JSON data is stored as text (preserving whitespace and key order)
/// or in a binary-optimized format (normalized, faster queries, indexable).
///
/// # Example
///
/// ```rust
/// use razeri_plugin_contract::data_type::JsonStorageFormat;
///
/// let text = JsonStorageFormat::Text;
/// let binary = JsonStorageFormat::Binary;
///
/// assert_eq!(format!("{:?}", text), "Text");
/// assert_eq!(format!("{:?}", binary), "Binary");
/// assert!(!text.is_binary());
/// assert!(binary.is_binary());
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub enum JsonStorageFormat {
    /// Text-based JSON storage (preserves whitespace, key order).
    ///
    /// Maps to: `JSON` (`PostgreSQL`), `NVARCHAR(MAX)` (SQL Server),
    /// `STRING` (Databricks).
    Text,
    /// Binary-optimized JSON storage (normalized, faster queries, indexable).
    ///
    /// Maps to: `JSONB` (`PostgreSQL`), `VARIANT` (Snowflake), `JSON` (`ClickHouse`).
    ///
    /// This is the recommended default for most use cases.
    #[default]
    Binary,
}

impl JsonStorageFormat {
    /// Returns `true` if this is the binary storage format.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::JsonStorageFormat;
    ///
    /// assert!(!JsonStorageFormat::Text.is_binary());
    /// assert!(JsonStorageFormat::Binary.is_binary());
    /// ```
    #[must_use]
    pub const fn is_binary(&self) -> bool {
        matches!(self, Self::Binary)
    }
}

/// JSON/Semi-structured data type.
///
/// Database mapping details:
///
/// | Platform | Type | Notes |
/// |----------|------|-------|
/// | **`PostgreSQL`** | `JSON` or `JSONB` | JSONB supports GIN indexing and is faster for queries |
/// | **SQL Server** | `NVARCHAR(MAX)` with JSON functions (2016+), or native JSON (2025+) | |
/// | **Snowflake** | `VARIANT` | Native semi-structured type, supports nested data and arrays |
/// | **Databricks** | `STRING` with JSON functions, or `VARIANT` | |
/// | **`ClickHouse`** | `JSON` (experimental/production), or `String` with JSON functions | |
/// | **`CitusDB`** | Same as `PostgreSQL` (JSONB recommended) | |
///
/// # Storage Formats
///
/// - **Binary** (default): Normalized storage, faster queries, indexable.
///   Maps to `JSONB` in `PostgreSQL`, `VARIANT` in Snowflake.
/// - **Text**: Preserves whitespace, key order, and duplicate keys.
///   Maps to `JSON` in `PostgreSQL`, `NVARCHAR(MAX)` in SQL Server.
///
/// # Example
///
/// ```rust
/// use razeri_plugin_contract::DataType;
/// use razeri_plugin_contract::data_type::{JsonDataType, JsonStorageFormat};
///
/// // Binary format (recommended) - uses JSONB in PostgreSQL, VARIANT in Snowflake
/// let json_binary = JsonDataType::default();
/// assert_eq!(json_binary.storage_format, JsonStorageFormat::Binary);
///
/// // Text format - preserves original formatting
/// let json_text = JsonDataType::text();
/// assert_eq!(json_text.storage_format, JsonStorageFormat::Text);
///
/// // Via DataType convenience
/// let data = DataType::json();
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash, Default)]
pub struct JsonDataType {
    /// Storage format preference (binary is recommended for most use cases).
    pub storage_format: JsonStorageFormat,

    /// Whether to validate JSON on insert (if supported by the database).
    ///
    /// `PostgreSQL` always validates, some other databases may not.
    pub validate_on_insert: bool,
}

impl JsonDataType {
    /// Creates a new JSON type with binary storage format (JSONB in `PostgreSQL`).
    ///
    /// This is the recommended format for most use cases as it enables:
    /// - Faster query performance
    /// - GIN indexing support (`PostgreSQL`)
    /// - Normalized storage (no duplicate keys, sorted keys)
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::{JsonDataType, JsonStorageFormat};
    ///
    /// let json = JsonDataType::new();
    /// assert_eq!(json.storage_format, JsonStorageFormat::Binary);
    /// assert!(!json.validate_on_insert);
    /// ```
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Creates a JSON type with text storage format.
    ///
    /// Use this when you need to preserve:
    /// - Original whitespace formatting
    /// - Original key order
    /// - Duplicate keys (not recommended but sometimes required)
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::{JsonDataType, JsonStorageFormat};
    ///
    /// let json = JsonDataType::text();
    /// assert_eq!(json.storage_format, JsonStorageFormat::Text);
    /// assert!(json.validate_on_insert);
    /// ```
    #[must_use]
    pub fn text() -> Self {
        Self { storage_format: JsonStorageFormat::Text, validate_on_insert: true }
    }

    /// Creates a JSON type with binary storage format.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::{JsonDataType, JsonStorageFormat};
    ///
    /// let json = JsonDataType::binary();
    /// assert_eq!(json.storage_format, JsonStorageFormat::Binary);
    /// assert!(json.validate_on_insert);
    /// ```
    #[must_use]
    pub fn binary() -> Self {
        Self { storage_format: JsonStorageFormat::Binary, validate_on_insert: true }
    }

    /// Sets whether to validate JSON on insert.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::data_type::JsonDataType;
    ///
    /// let json = JsonDataType::new().with_validation(false);
    /// assert!(!json.validate_on_insert);
    /// ```
    #[must_use]
    pub fn with_validation(mut self, validate: bool) -> Self {
        self.validate_on_insert = validate;
        self
    }
}

// ============================================================================
// Complex/Collection Types
// ============================================================================

/// Array type containing elements of another type.
///
/// Supported by: `PostgreSQL`, `ClickHouse`, Snowflake (ARRAY), Databricks (ARRAY).
/// Not directly supported by SQL Server.
///
/// # Example
///
/// ```rust
/// use razeri_plugin_contract::{DataType, data_type::ArrayDataType};
///
/// let int_array = ArrayDataType::new(DataType::int());
/// assert_eq!(*int_array.element_type, DataType::int());
///
/// let _str_array = ArrayDataType::new(DataType::varchar(100));
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ArrayDataType {
    /// The data type of array elements.
    pub element_type: Box<DataType>,
}

impl ArrayDataType {
    /// Creates a new array type with the given element type.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::{DataType, data_type::ArrayDataType};
    ///
    /// let arr = ArrayDataType::new(DataType::bigint());
    /// assert_eq!(*arr.element_type, DataType::bigint());
    /// ```
    #[must_use]
    pub fn new(element_type: DataType) -> Self {
        Self { element_type: Box::new(element_type) }
    }
}

/// Map/Dictionary type with key-value pairs.
///
/// Supported by: `ClickHouse`, Snowflake (OBJECT), Databricks (MAP).
/// `PostgreSQL` uses JSONB, SQL Server uses JSON string.
///
/// # Example
///
/// ```rust
/// use razeri_plugin_contract::DataType;
/// use razeri_plugin_contract::data_type::MapDataType;
///
/// let map = MapDataType::new(DataType::varchar(50), DataType::int());
/// assert_eq!(*map.key_type, DataType::varchar(50));
/// assert_eq!(*map.value_type, DataType::int());
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MapDataType {
    /// The data type of map keys.
    pub key_type: Box<DataType>,

    /// The data type of map values.
    pub value_type: Box<DataType>,
}

impl MapDataType {
    /// Creates a new map type with the given key and value types.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::DataType;
    /// use razeri_plugin_contract::data_type::MapDataType;
    ///
    /// let map = MapDataType::new(DataType::varchar(50), DataType::int());
    /// assert_eq!(*map.key_type, DataType::varchar(50));
    /// assert_eq!(*map.value_type, DataType::int());
    /// ```
    #[must_use]
    pub fn new(key_type: DataType, value_type: DataType) -> Self {
        Self { key_type: Box::new(key_type), value_type: Box::new(value_type) }
    }
}

/// One named field inside a [`StructDataType`], in the order it was declared.
///
/// A struct's fields are named on every engine that has a record type, and
/// positional on some, so both the name and the position are part of the type.
///
/// # Example
///
/// ```rust
/// use razeri_plugin_contract::{DataType, data_type::StructField};
///
/// let zip = StructField::new("zip", DataType::varchar(10));
/// assert_eq!(zip.name, "zip");
/// assert_eq!(zip.data_type, DataType::varchar(10));
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StructField {
    /// The field's name, as the design declared it.
    pub name: String,

    /// The field's type. May itself be a collection or another struct.
    pub data_type: DataType,
}

impl StructField {
    /// Creates a named field of the given type.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::{DataType, data_type::StructField};
    ///
    /// let field = StructField::new("category", DataType::varchar(100));
    /// assert_eq!(field.data_type, DataType::varchar(100));
    /// ```
    pub fn new(name: impl Into<String>, data_type: DataType) -> Self {
        Self { name: name.into(), data_type }
    }
}

/// Struct/record type: an ordered list of named fields.
///
/// Supported natively by `BigQuery` (`STRUCT`), Databricks (`STRUCT`),
/// `ClickHouse` (named `Tuple`) and `DuckDB` (`STRUCT`). Engines without a
/// record type render their JSON type instead; the field names and types are
/// still part of the declared type, they are simply not restated in the DDL.
///
/// Field order is significant: it is the order the design declared, it is the
/// order every engine with a record type writes, and two structs holding the
/// same fields in a different order are different types.
///
/// # Example
///
/// ```rust
/// use razeri_plugin_contract::{DataType, data_type::{StructDataType, StructField}};
///
/// let address = StructDataType::new(vec![
///     StructField::new("street", DataType::varchar(200)),
///     StructField::new("zip", DataType::varchar(10)),
/// ]);
/// assert_eq!(address.fields.len(), 2);
/// assert_eq!(address.fields[0].name, "street");
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StructDataType {
    /// The struct's fields, in declaration order.
    pub fields: Vec<StructField>,
}

impl StructDataType {
    /// Creates a struct type from an ordered list of named fields.
    ///
    /// # Example
    ///
    /// ```rust
    /// use razeri_plugin_contract::{DataType, data_type::{StructDataType, StructField}};
    ///
    /// let point = StructDataType::new(vec![
    ///     StructField::new("x", DataType::int()),
    ///     StructField::new("y", DataType::int()),
    /// ]);
    /// assert_eq!(point.fields[1].name, "y");
    /// ```
    #[must_use]
    pub fn new(fields: Vec<StructField>) -> Self {
        Self { fields }
    }
}

// ============================================================================
// Unified Data Type Enum
// ============================================================================

/// Unified data type enumeration covering all supported types across databases.
///
/// This is the **primary type system** for Razeri. Every field, column, and
/// parameter in a design document is typed using `DataType`. The enum captures
/// enough metadata to generate correct DDL for every target while remaining
/// abstract over platform-specific implementation details.
///
/// # Type Categories
///
/// | Category | Variants | Example |
/// |----------|----------|---------|
/// | Numeric | `Integer`, `Decimal`, `Float` | `INT`, `DECIMAL(19,4)`, `DOUBLE` |
/// | Boolean | `Boolean` | `BOOLEAN`, `BIT` |
/// | String | `Char`, `VarChar`, `Text` | `VARCHAR(100)`, `TEXT` |
/// | Binary | `Binary`, `VarBinary` | `BYTEA`, `VARBINARY` |
/// | Date/Time | `Date`, `Time`, `Timestamp`, `TimestampTz`, `DateTime`, `Interval` | `DATE`, `TIMESTAMP` |
/// | Special | `Uuid`, `Json` | `UUID`, `JSONB` |
/// | Collection | `Array`, `Map`, `Struct` | `INTEGER[]`, `MAP<TEXT,INT>`, `STRUCT<a INT>` |
///
/// # Design Principles
///
/// 1. **Abstract over database-specific implementations** — `DataType` captures
///    enough metadata to generate correct DDL for each target, but does not
///    embed platform-specific syntax.
/// 2. **Preserve precision metadata** — Decimal types carry precision and scale;
///    string types carry length constraints; timestamp types carry fractional
///    seconds precision.
/// 3. **Every type renders somewhere** — a dialect answers for every variant,
///    emulating a type it does not have (JSON stored as `NVARCHAR(MAX)` on SQL
///    Server, a struct stored as `jsonb` on `PostgreSQL`) rather than refusing.
///
/// # Usage
///
/// ```
/// use razeri_plugin_contract::DataType;
///
/// // Convenience constructors for common types
/// let id = DataType::bigint();
/// let name = DataType::varchar(255);
/// let price = DataType::decimal(19, 4);
/// let created = DataType::timestamp();
///
/// // JSON with binary storage (JSONB in PostgreSQL, VARIANT in Snowflake)
/// let data = DataType::json();
/// ```
///
/// # Cross-Database Mapping
///
/// Each variant maps to platform-specific types as documented in the variant
/// definitions. Dialect plugins resolve the final SQL type string during
/// rendering; the rendering traits live in this crate's `renderer` module.
///
/// # The enum is `#[non_exhaustive]`
///
/// New types are added over time, so a `match` outside this crate needs a
/// fallback arm. A dialect's fallback should render the closest type the engine
/// does have — its JSON or text type — rather than panicking: a type the
/// dialect has not been taught about is still a column someone declared.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum DataType {
    // Numeric types
    /// Signed/unsigned integer (1, 2, 4, or 8 bytes).
    Integer(IntegerDataType),

    /// Exact numeric with fixed precision and scale.
    Decimal(DecimalDataType),

    /// Approximate floating-point (4 or 8 bytes).
    Float(FloatDataType),

    /// Boolean (true/false).
    Boolean(BooleanDataType),

    // String types
    /// Fixed-length character string.
    Char(CharDataType),

    /// Variable-length character string.
    VarChar(VarCharDataType),

    /// Unbounded text type.
    Text(TextDataType),

    // Binary types
    /// Fixed-length binary data.
    Binary(BinaryDataType),

    /// Variable-length binary data.
    VarBinary(VarBinaryDataType),

    // Date/Time types
    /// Date only (year, month, day).
    Date(DateDataType),

    /// Time only (hour, minute, second, optional timezone).
    Time(TimeDataType),

    /// Timestamp without timezone.
    Timestamp(TimestampDataType),

    /// Timestamp with timezone.
    TimestampTz(TimestampTzDataType),

    /// Combined date and time (legacy).
    DateTime(DateTimeDataType),

    /// Interval/duration.
    Interval(IntervalDataType),

    // Special types
    /// UUID/GUID.
    Uuid(UuidDataType),

    /// JSON/semi-structured data.
    Json(JsonDataType),

    // Complex types
    /// Array of elements.
    Array(ArrayDataType),

    /// Map/dictionary with key-value pairs.
    Map(MapDataType),

    /// Record with an ordered list of named fields.
    Struct(StructDataType),
}

impl DataType {
    /// Whether this type holds more than one value inside one column — an
    /// array, a map, or a record.
    ///
    /// Nested columns are answered differently from scalars in several places:
    /// they cannot be part of a key, nothing aggregates them, and an engine
    /// with no record type of its own stores them as JSON or text. This is the
    /// one question all of those ask, so they ask it the same way.
    ///
    /// # Example
    ///
    /// ```
    /// use razeri_plugin_contract::{DataType, data_type::ArrayDataType};
    ///
    /// assert!(DataType::Array(ArrayDataType::new(DataType::int())).is_nested());
    /// assert!(!DataType::bigint().is_nested());
    /// ```
    #[must_use]
    pub const fn is_nested(&self) -> bool {
        matches!(self, DataType::Array(_) | DataType::Map(_) | DataType::Struct(_))
    }

    // ==========================================================================
    // Numeric Type Constructors
    // ==========================================================================

    /// Creates a 1-byte signed integer (`TINYINT` / `SMALLINT` / `Int8`).
    ///
    /// # Example
    ///
    /// ```
    /// use razeri_plugin_contract::DataType;
    ///
    /// let ty = DataType::tinyint();
    /// assert!(matches!(ty, DataType::Integer(_)));
    /// ```
    #[must_use]
    pub fn tinyint() -> Self {
        DataType::Integer(IntegerDataType::new(IntegerSize::Tiny))
    }

    /// Creates a 2-byte signed integer (`SMALLINT` / `Int16`).
    ///
    /// # Example
    ///
    /// ```
    /// use razeri_plugin_contract::DataType;
    ///
    /// let ty = DataType::smallint();
    /// assert!(matches!(ty, DataType::Integer(_)));
    /// ```
    #[must_use]
    pub fn smallint() -> Self {
        DataType::Integer(IntegerDataType::new(IntegerSize::Small))
    }

    /// Creates a 4-byte signed integer (`INT` / `INTEGER` / `Int32`).
    ///
    /// # Example
    ///
    /// ```
    /// use razeri_plugin_contract::DataType;
    ///
    /// let id = DataType::int();
    /// assert!(matches!(id, DataType::Integer(_)));
    /// ```
    #[must_use]
    pub fn int() -> Self {
        DataType::Integer(IntegerDataType::new(IntegerSize::Standard))
    }

    /// Creates an 8-byte signed integer (`BIGINT` / `Int64`).
    ///
    /// # Example
    ///
    /// ```
    /// use razeri_plugin_contract::DataType;
    ///
    /// let id = DataType::bigint();
    /// assert!(matches!(id, DataType::Integer(_)));
    /// ```
    #[must_use]
    pub fn bigint() -> Self {
        DataType::Integer(IntegerDataType::new(IntegerSize::Big))
    }

    /// Creates a `DECIMAL(precision, scale)` type.
    ///
    /// # Panics
    ///
    /// Panics if `precision` is 0 or exceeds 38, or if `scale > precision`.
    ///
    /// # Example
    ///
    /// ```
    /// use razeri_plugin_contract::DataType;
    ///
    /// let price = DataType::decimal(19, 4);
    /// assert!(matches!(price, DataType::Decimal(_)));
    /// ```
    ///
    /// ```should_panic
    /// use razeri_plugin_contract::DataType;
    ///
    /// let _ = DataType::decimal(0, 0); // panics: precision must be 1-38
    /// ```
    #[must_use]
    pub fn decimal(precision: u8, scale: u8) -> Self {
        DataType::Decimal(DecimalDataType::new(precision, scale))
    }

    /// Creates a single-precision float (`REAL` / `FLOAT4`).
    ///
    /// # Example
    ///
    /// ```
    /// use razeri_plugin_contract::DataType;
    ///
    /// let ty = DataType::float();
    /// assert!(matches!(ty, DataType::Float(_)));
    /// ```
    #[must_use]
    pub fn float() -> Self {
        DataType::Float(FloatDataType::single())
    }

    /// Creates a double-precision float (`DOUBLE PRECISION` / `DOUBLE`).
    ///
    /// # Example
    ///
    /// ```
    /// use razeri_plugin_contract::DataType;
    ///
    /// let ty = DataType::double();
    /// assert!(matches!(ty, DataType::Float(_)));
    /// ```
    #[must_use]
    pub fn double() -> Self {
        DataType::Float(FloatDataType::double())
    }

    // ==========================================================================
    // Boolean Type Constructor
    // ==========================================================================

    /// Creates a boolean type (`BOOLEAN` / `BIT`).
    ///
    /// # Example
    ///
    /// ```
    /// use razeri_plugin_contract::DataType;
    ///
    /// let ty = DataType::boolean();
    /// assert!(matches!(ty, DataType::Boolean(_)));
    /// ```
    #[must_use]
    pub fn boolean() -> Self {
        DataType::Boolean(BooleanDataType)
    }

    // ==========================================================================
    // String Type Constructors
    // ==========================================================================

    /// Creates a `VARCHAR(max_length)` type.
    ///
    /// # Example
    ///
    /// ```
    /// use razeri_plugin_contract::DataType;
    ///
    /// let name = DataType::varchar(255);
    /// assert!(matches!(name, DataType::VarChar(_)));
    /// ```
    #[must_use]
    pub fn varchar(max_length: u32) -> Self {
        DataType::VarChar(VarCharDataType::new(max_length))
    }

    /// Creates an unbounded text type (`TEXT` / `VARCHAR(MAX)` / `STRING`).
    ///
    /// # Example
    ///
    /// ```
    /// use razeri_plugin_contract::DataType;
    ///
    /// let ty = DataType::text();
    /// assert!(matches!(ty, DataType::Text(_)));
    /// ```
    #[must_use]
    pub fn text() -> Self {
        DataType::Text(TextDataType)
    }

    // ==========================================================================
    // Date/Time Type Constructors
    // ==========================================================================

    /// Creates a date-only type (`DATE`).
    ///
    /// # Example
    ///
    /// ```
    /// use razeri_plugin_contract::DataType;
    ///
    /// let ty = DataType::date();
    /// assert!(matches!(ty, DataType::Date(_)));
    /// ```
    #[must_use]
    pub fn date() -> Self {
        DataType::Date(DateDataType)
    }

    /// Creates a timestamp without timezone (`TIMESTAMP`).
    ///
    /// # Example
    ///
    /// ```
    /// use razeri_plugin_contract::DataType;
    ///
    /// let created = DataType::timestamp();
    /// assert!(matches!(created, DataType::Timestamp(_)));
    /// ```
    #[must_use]
    pub fn timestamp() -> Self {
        DataType::Timestamp(TimestampDataType::default())
    }

    /// Creates a timestamp with timezone (`TIMESTAMPTZ` / `DATETIMEOFFSET`).
    ///
    /// # Example
    ///
    /// ```
    /// use razeri_plugin_contract::DataType;
    ///
    /// let created_tz = DataType::timestamp_tz();
    /// assert!(matches!(created_tz, DataType::TimestampTz(_)));
    /// ```
    #[must_use]
    pub fn timestamp_tz() -> Self {
        DataType::TimestampTz(TimestampTzDataType::default())
    }

    // ==========================================================================
    // Special Type Constructors
    // ==========================================================================

    /// Creates a UUID type (`UUID` / `UNIQUEIDENTIFIER`).
    ///
    /// # Example
    ///
    /// ```
    /// use razeri_plugin_contract::DataType;
    ///
    /// let ty = DataType::uuid();
    /// assert!(matches!(ty, DataType::Uuid(_)));
    /// ```
    #[must_use]
    pub fn uuid() -> Self {
        DataType::Uuid(UuidDataType)
    }

    /// Creates a JSON type with binary storage (JSONB in `PostgreSQL`, VARIANT in Snowflake).
    ///
    /// # Example
    ///
    /// ```
    /// use razeri_plugin_contract::DataType;
    ///
    /// let data = DataType::json();
    /// assert!(matches!(data, DataType::Json(_)));
    /// ```
    #[must_use]
    pub fn json() -> Self {
        DataType::Json(JsonDataType::binary())
    }

    /// Creates a JSON type with text storage (preserves formatting).
    ///
    /// # Example
    ///
    /// ```
    /// use razeri_plugin_contract::DataType;
    ///
    /// let data = DataType::json_text();
    /// assert!(matches!(data, DataType::Json(_)));
    /// ```
    #[must_use]
    pub fn json_text() -> Self {
        DataType::Json(JsonDataType::text())
    }
}

// ============================================================================
// Tests
// ============================================================================

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_integer_types() {
        let tiny = IntegerDataType::new(IntegerSize::Tiny);
        assert_eq!(tiny.byte_size(), 1);
        assert!(!tiny.unsigned);

        let big_unsigned = IntegerDataType::unsigned(IntegerSize::Big);
        assert_eq!(big_unsigned.byte_size(), 8);
        assert!(big_unsigned.unsigned);
    }

    #[test]
    fn test_decimal_type() {
        let money = DecimalDataType::money();
        assert_eq!(money.precision, 19);
        assert_eq!(money.scale, 4);
    }

    #[test]
    #[should_panic(expected = "Scale cannot exceed precision")]
    fn test_decimal_invalid_scale() {
        let _ = DecimalDataType::new(5, 10);
    }

    #[test]
    fn test_convenience_constructors() {
        assert!(matches!(DataType::int(), DataType::Integer(_)));
        assert!(matches!(DataType::varchar(100), DataType::VarChar(_)));
        assert!(matches!(DataType::timestamp(), DataType::Timestamp(_)));
    }

    /// A struct is built from named fields and keeps them in the order given.
    #[test]
    fn a_struct_keeps_its_fields_in_declaration_order() {
        let address = StructDataType::new(vec![
            StructField::new("street", DataType::varchar(200)),
            StructField::new("city", DataType::varchar(100)),
            StructField::new("zip", DataType::varchar(10)),
        ]);

        let names: Vec<&str> = address.fields.iter().map(|f| f.name.as_str()).collect();
        assert_eq!(names, ["street", "city", "zip"]);
        assert_eq!(address.fields[2].data_type, DataType::varchar(10));
        assert!(matches!(DataType::Struct(address), DataType::Struct(_)));
    }

    /// Field order is part of the type: the same fields in another order are a
    /// different struct, and the same fields in the same order are the same one.
    #[test]
    fn two_structs_are_equal_only_when_their_fields_agree_in_order() {
        let field = |name: &str| StructField::new(name, DataType::int());
        let xy = StructDataType::new(vec![field("x"), field("y")]);
        let xy_again = StructDataType::new(vec![field("x"), field("y")]);
        let yx = StructDataType::new(vec![field("y"), field("x")]);
        let renamed = StructDataType::new(vec![field("x"), field("z")]);
        let retyped = StructDataType::new(vec![
            StructField::new("x", DataType::int()),
            StructField::new("y", DataType::bigint()),
        ]);

        assert_eq!(DataType::Struct(xy.clone()), DataType::Struct(xy_again));
        assert_ne!(DataType::Struct(xy.clone()), DataType::Struct(yx));
        assert_ne!(DataType::Struct(xy.clone()), DataType::Struct(renamed));
        assert_ne!(DataType::Struct(xy), DataType::Struct(retyped));
    }

    /// A struct nests: its fields may themselves be collections or structs, so
    /// the array of structs a nested source table carries is one value.
    #[test]
    fn a_struct_field_may_itself_be_a_collection_or_a_struct() {
        let inner = StructDataType::new(vec![
            StructField::new("key", DataType::varchar(100)),
            StructField::new("value", DataType::varchar(1000)),
        ]);
        let outer = StructDataType::new(vec![
            StructField::new("id", DataType::bigint()),
            StructField::new(
                "extras",
                DataType::Array(ArrayDataType::new(DataType::Struct(inner))),
            ),
            StructField::new(
                "labels",
                DataType::Map(MapDataType::new(DataType::varchar(50), DataType::text())),
            ),
        ]);

        let DataType::Array(extras) = &outer.fields[1].data_type else {
            panic!("the second field is an array");
        };
        let DataType::Struct(element) = extras.element_type.as_ref() else {
            panic!("the array's element is a struct");
        };
        assert_eq!(element.fields[0].name, "key");
        assert!(matches!(outer.fields[2].data_type, DataType::Map(_)));
    }
}

// ============================================================================
// Simplified Data Type Reference (for CAST expressions)
// ============================================================================

/// Simplified data type reference used in CAST / `TRY_CAST` / CONVERT expressions.
///
/// Unlike [`DataType`], which captures full type metadata for DDL generation,
/// `DataTypeRef` represents the type names commonly used in SQL expressions.
///
/// # Purpose
///
/// `DataTypeRef` is a lightweight, platform-agnostic type reference suitable for
/// embedding in SQL expressions such as:
///
/// ```sql
/// SELECT CAST(column_name AS VARCHAR(100)) FROM table
/// SELECT TRY_CAST(value AS DECIMAL(19, 4)) FROM source
/// SELECT CONVERT(DATETIME2, timestamp_col) FROM events
/// ```
///
/// # Differences from `DataType`
///
/// | Aspect | `DataType` | `DataTypeRef` |
/// |--------|-----------|---------------|
/// | **Use case** | DDL generation | CAST / CONVERT expressions |
/// | **Metadata** | Full (encoding, precision, storage format) | Minimal (precision, scale, length) |
/// | **Platform variants** | Unified (one variant per type) | Separate (`Decimal` vs `Numeric`, `DateTime` vs `DateTime2`) |
/// | **Collections** | Array, Map, Struct | Not supported |
///
/// # Platform-Specific Variants
///
/// Some types have separate variants for platform-specific naming:
///
/// - `Decimal` vs `Numeric` — equivalent in SQL, but some dialects prefer one over the other
/// - `DateTime` vs `DateTime2` — SQL Server uses `DATETIME2` for precision
/// - `Json` vs `Jsonb` — `PostgreSQL` distinguishes between text and binary JSON
/// - `Boolean` vs `Bit` — SQL Server uses `BIT` for boolean
///
/// # Example
///
/// ```
/// use razeri_plugin_contract::DataTypeRef;
///
/// let varchar = DataTypeRef::Varchar { length: Some(100) };
/// let decimal = DataTypeRef::Decimal { precision: 19, scale: 4 };
/// let timestamp = DataTypeRef::Timestamp { precision: Some(6) };
/// ```
#[derive(Debug, Clone, PartialEq)]
pub enum DataTypeRef {
    // ==========================================================================
    // Numeric Types
    // ==========================================================================
    /// 4-byte signed integer (`INT` / `INTEGER`).
    Int,

    /// 8-byte signed integer (`BIGINT`).
    BigInt,

    /// 2-byte signed integer (`SMALLINT`).
    SmallInt,

    /// 1-byte signed integer (`TINYINT` / `SMALLINT` in `PostgreSQL`).
    TinyInt,

    /// Single-precision float (`REAL` / `FLOAT4`).
    Float,

    /// Double-precision float (`DOUBLE PRECISION` / `DOUBLE`).
    Double,

    /// Single-precision float (`REAL` / `FLOAT4`).
    Real,

    /// Exact numeric with precision and scale (`DECIMAL(p, s)`).
    Decimal {
        /// Total number of digits.
        precision: u8,
        /// Number of digits after the decimal point.
        scale: u8,
    },

    /// Exact numeric with precision and scale (`NUMERIC(p, s)`).
    ///
    /// Equivalent to `Decimal` in SQL, but some dialects prefer `NUMERIC`
    /// over `DECIMAL` for exact numeric types.
    Numeric {
        /// Total number of digits.
        precision: u8,
        /// Number of digits after the decimal point.
        scale: u8,
    },

    // ==========================================================================
    // String Types
    // ==========================================================================
    /// Variable-length character string (`VARCHAR(n)`).
    Varchar {
        /// Maximum length in characters (None = unlimited/MAX).
        length: Option<u16>,
    },

    /// Fixed-length character string (`CHAR(n)`).
    Char {
        /// Length in characters.
        length: u16,
    },

    /// Unbounded text type (`TEXT`).
    Text,

    /// Variable-length Unicode string (`NVARCHAR(n)` — SQL Server).
    NVarchar {
        /// Maximum length in characters (None = unlimited/MAX).
        length: Option<u16>,
    },

    /// Fixed-length Unicode string (`NCHAR(n)` — SQL Server).
    NChar {
        /// Length in characters.
        length: u16,
    },

    // ==========================================================================
    // Binary Types
    // ==========================================================================
    /// Fixed-length binary data (`BINARY(n)`).
    Binary {
        /// Length in bytes.
        length: Option<u16>,
    },

    /// Variable-length binary data (`VARBINARY(n)`).
    VarBinary {
        /// Maximum length in bytes (None = unlimited/MAX).
        length: Option<u16>,
    },

    /// Unbounded binary data (`BLOB` / `BYTEA`).
    Blob,

    // ==========================================================================
    // Date/Time Types
    // ==========================================================================
    /// Date only (`DATE`).
    Date,

    /// Time with optional precision (`TIME(p)`).
    Time {
        /// Fractional seconds precision (None = default).
        precision: Option<u8>,
    },

    /// Combined date and time (`DATETIME` — SQL Server legacy).
    DateTime,

    /// Combined date and time with precision (`DATETIME2(p)` — SQL Server).
    DateTime2 {
        /// Fractional seconds precision (None = default).
        precision: Option<u8>,
    },

    /// Timestamp with optional precision (`TIMESTAMP(p)`).
    Timestamp {
        /// Fractional seconds precision (None = default).
        precision: Option<u8>,
    },

    /// Timestamp with timezone and optional precision (`TIMESTAMPTZ(p)`).
    TimestampTz {
        /// Fractional seconds precision (None = default).
        precision: Option<u8>,
    },

    /// Interval/duration (`INTERVAL`).
    Interval,

    // ==========================================================================
    // Boolean Types
    // ==========================================================================
    /// Boolean (`BOOLEAN` — `PostgreSQL`, Snowflake, `ClickHouse`).
    Boolean,

    /// Bit (`BIT` — SQL Server).
    Bit,

    // ==========================================================================
    // JSON/Semi-structured Types
    // ==========================================================================
    /// Text-based JSON (`JSON` — `PostgreSQL`).
    Json,

    /// Binary-optimized JSON (`JSONB` — `PostgreSQL`).
    Jsonb,

    /// Semi-structured variant (`VARIANT` — Snowflake).
    Variant,

    // ==========================================================================
    // Other Types
    // ==========================================================================
    /// UUID/GUID (`UUID` / `UNIQUEIDENTIFIER`).
    Uuid,

    /// XML data (`XML`).
    Xml,

    /// Custom type name (for types not covered by the enum variants).
    Custom(String),
}