ormkit/schema/

column.rs

//! Column trait and type-safe column references
//!
//! This module defines the `Column` type which provides type-safe references to database columns.
//! Columns are parameterized by their table type, Rust type, and a unique marker type.
//!
//! ## Type Safety
//!
//! The `Column<T, Type, M>` type ensures at compile time that:
//! - Columns can only be used with their parent table (via the `T` parameter)
//! - Column types are checked (via the `Type` parameter)
//! - Each column has a unique identity (via the `M` marker parameter)
//!
//! ## Example
//!
//! ```rust,ignore
//! use ormkit::schema::{Table, Column};
//!
//! // Table marker type
//! #[derive(Debug, Clone, Copy)]
//! pub struct UsersTable;
//!
//! impl Table for UsersTable {
//!     const NAME: &'static str = "users";
//! }
//!
//! // Column marker types
//! #[derive(Debug, Clone, Copy)]
//! pub struct EmailColumn;
//!
//! // Type-safe column reference
//! pub const email: Column<UsersTable, String, EmailColumn> = Column::new("email");
//!
//! // Usage
//! assert_eq!(email.name(), "email");
//! assert_eq!(email.table_name(), "users");
//! ```
//!
//! ## Zero-Sized Types
//!
//! `Column` instances are zero-sized when used as constants. The compiler optimizes
//! them away completely, leaving zero runtime overhead for type safety.

use std::fmt;
use std::marker::PhantomData;

use super::table::Table;

/// A type-safe reference to a database column
///
/// # Type Parameters
///
/// - `T`: The table type this column belongs to (enforces ownership)
/// - `Type`: The Rust type of values in this column (String, i32, etc.)
/// - `M`: A unique marker type for this specific column (prevents column confusion)
///
/// # Type Safety
///
/// The type parameter `T` ensures that columns cannot be used with the wrong table.
/// This is enforced at compile time, preventing SQL injection through type confusion.
///
/// # Zero-Sized Type
///
/// When used as a constant, `Column` is a zero-sized type. All data is stored in the
/// type system itself, not in runtime values.
///
/// # Example
///
/// ```rust,ignore
/// use ormkit::schema::{Table, Column};
///
/// # #[derive(Debug, Clone, Copy)]
/// # pub struct UsersTable;
/// # impl Table for UsersTable { const NAME: &'static str = "users"; }
/// # #[derive(Debug, Clone, Copy)]
/// # pub struct EmailColumn;
///
/// pub const email: Column<UsersTable, String, EmailColumn> = Column::new("email");
///
/// // Access column metadata
/// assert_eq!(email.name(), "email");
/// assert_eq!(email.table_name(), "users");
/// ```
#[derive(Debug, Clone, Copy)]
pub struct Column<T, Type, M = ()>
where
    T: Table,
    M: 'static + Send + Sync + Copy + fmt::Debug,
{
    /// The column name in the database
    name: &'static str,

    /// Phantom data for the table this column belongs to
    ///
    /// This ensures the column can only be used with its parent table.
    phantom_table: PhantomData<T>,

    /// Phantom data for the Rust type of this column
    ///
    /// This enables type-safe queries and operations.
    phantom_type: PhantomData<Type>,

    /// Phantom data for the unique column marker
    ///
    /// This ensures each column has a unique type identity.
    phantom_marker: PhantomData<M>,
}

impl<T, Type, M> Column<T, Type, M>
where
    T: Table,
    M: 'static + Send + Sync + Copy + fmt::Debug,
{
    /// Create a new column reference
    ///
    /// This should only be called in generated code. Users should use the
    /// pre-defined column constants (e.g., `users::email`).
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// # use ormkit::schema::{Table, Column};
    /// # #[derive(Debug, Clone, Copy)] pub struct UsersTable;
    /// # impl Table for UsersTable { const NAME: &'static str = "users"; }
    /// # #[derive(Debug, Clone, Copy)] pub struct EmailColumn;
    /// pub const email: Column<UsersTable, String, EmailColumn> = Column::new("email");
    /// ```
    #[inline]
    pub const fn new(name: &'static str) -> Self {
        Self {
            name,
            phantom_table: PhantomData,
            phantom_type: PhantomData,
            phantom_marker: PhantomData,
        }
    }

    /// Get the column name
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// # use ormkit::schema::{Table, Column};
    /// # #[derive(Debug, Clone, Copy)] pub struct UsersTable;
    /// # impl Table for UsersTable { const NAME: &'static str = "users"; }
    /// # #[derive(Debug, Clone, Copy)] pub struct EmailColumn;
    /// # pub const email: Column<UsersTable, String, EmailColumn> = Column::new("email");
    /// assert_eq!(email.name(), "email");
    /// ```
    #[inline]
    pub fn name(&self) -> &'static str {
        self.name
    }

    /// Get the table name this column belongs to
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// # use ormkit::schema::{Table, Column};
    /// # #[derive(Debug, Clone, Copy)] pub struct UsersTable;
    /// # impl Table for UsersTable { const NAME: &'static str = "users"; }
    /// # #[derive(Debug, Clone, Copy)] pub struct EmailColumn;
    /// # pub const email: Column<UsersTable, String, EmailColumn> = Column::new("email");
    /// assert_eq!(email.table_name(), "users");
    /// ```
    #[inline]
    pub fn table_name(&self) -> &'static str {
        T::NAME
    }

    /// Get the fully qualified column name (table.column)
    ///
    /// This is useful for generating SQL queries.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// # use ormkit::schema::{Table, Column};
    /// # #[derive(Debug, Clone, Copy)] pub struct UsersTable;
    /// # impl Table for UsersTable { const NAME: &'static str = "users"; }
    /// # #[derive(Debug, Clone, Copy)] pub struct EmailColumn;
    /// # pub const email: Column<UsersTable, String, EmailColumn> = Column::new("email");
    /// assert_eq!(email.qualified_name(), "users.email");
    /// ```
    #[inline]
    pub fn qualified_name(&self) -> String {
        format!("{}.{}", T::NAME, self.name)
    }

    /// Check if this column is the given column name
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// # use ormkit::schema::{Table, Column};
    /// # #[derive(Debug, Clone, Copy)] pub struct UsersTable;
    /// # impl Table for UsersTable { const NAME: &'static str = "users"; }
    /// # #[derive(Debug, Clone, Copy)] pub struct EmailColumn;
    /// # pub const email: Column<UsersTable, String, EmailColumn> = Column::new("email");
    /// assert!(email.is_column("email"));
    /// assert!(!email.is_column("name"));
    /// ```
    #[inline]
    pub fn is_column(&self, name: &str) -> bool {
        self.name == name
    }

    /// Get a reference to this column (for ZSTs, this is essentially a no-op)
    ///
    /// This method is useful when you need a reference to the column.
    #[inline]
    pub fn as_ref(&self) -> &Self {
        self
    }
}

impl<T, Type, M> fmt::Display for Column<T, Type, M>
where
    T: Table,
    M: 'static + Send + Sync + Copy + fmt::Debug,
{
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.qualified_name())
    }
}

/// Implement ColumnSealed for valid column types
///
/// This sealed trait prevents external implementations of Column extensions.
pub trait ColumnSealed<T, Type>: 'static + Send + Sync + Copy + fmt::Debug
where
    T: Table,
{
}

/// Blanket implementation for all valid marker types
impl<T, Type, M> ColumnSealed<T, Type> for M
where
    T: Table,
    M: 'static + Send + Sync + Copy + fmt::Debug,
{
}

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

    // Test table and column types
    #[derive(Debug, Clone, Copy)]
    struct TestTable;

    impl Table for TestTable {
        const NAME: &'static str = "test_table";
    }

    #[derive(Debug, Clone, Copy)]
    struct TestColumn1;

    #[derive(Debug, Clone, Copy)]
    struct TestColumn2;

    type TestColumn1Type = Column<TestTable, String, TestColumn1>;
    type TestColumn2Type = Column<TestTable, i32, TestColumn2>;

    const TEST_COL1: TestColumn1Type = Column::new("col1");
    const TEST_COL2: TestColumn2Type = Column::new("col2");

    #[test]
    fn test_column_name() {
        assert_eq!(TEST_COL1.name(), "col1");
        assert_eq!(TEST_COL2.name(), "col2");
    }

    #[test]
    fn test_table_name() {
        assert_eq!(TEST_COL1.table_name(), "test_table");
        assert_eq!(TEST_COL2.table_name(), "test_table");
    }

    #[test]
    fn test_qualified_name() {
        assert_eq!(TEST_COL1.qualified_name(), "test_table.col1");
        assert_eq!(TEST_COL2.qualified_name(), "test_table.col2");
    }

    #[test]
    fn test_is_column() {
        assert!(TEST_COL1.is_column("col1"));
        assert!(!TEST_COL1.is_column("col2"));
        assert!(!TEST_COL1.is_column("other"));
    }

    #[test]
    fn test_column_display() {
        assert_eq!(TEST_COL1.to_string(), "test_table.col1");
        assert_eq!(TEST_COL2.to_string(), "test_table.col2");
    }

    #[test]
    fn test_column_copy() {
        let col = TEST_COL1;
        let _copy = col; // Tests that Column is Copy
        let _copy2 = col; // Tests that Column is Copy (can use again)
    }

    #[test]
    fn test_column_clone() {
        let col = TEST_COL1;
        let _clone = col; // Tests that Column is Clone
    }

    #[test]
    fn test_column_zst() {
        assert_eq!(std::mem::size_of::<TestColumn1Type>(), 0);
        assert_eq!(std::mem::size_of::<TestColumn2Type>(), 0);
    }

    #[test]
    fn test_multiple_columns() {
        // Multiple columns with different types
        #[derive(Debug, Clone, Copy)]
        struct StrCol;
        #[derive(Debug, Clone, Copy)]
        struct IntCol;
        #[derive(Debug, Clone, Copy)]
        struct BoolCol;

        type StrColumnType = Column<TestTable, String, StrCol>;
        type IntColumnType = Column<TestTable, i32, IntCol>;
        type BoolColumnType = Column<TestTable, bool, BoolCol>;

        const STR_COL: StrColumnType = Column::new("str_col");
        const INT_COL: IntColumnType = Column::new("int_col");
        const BOOL_COL: BoolColumnType = Column::new("bool_col");

        assert_eq!(STR_COL.name(), "str_col");
        assert_eq!(INT_COL.name(), "int_col");
        assert_eq!(BOOL_COL.name(), "bool_col");
    }
}