drizzle-types 0.3.0

//! `PostgreSQL` columns: [`ColumnDef`] (const) and [`Column`] (runtime), with
//! their generated-column and identity settings.

use crate::alloc_prelude::*;

#[cfg(feature = "serde")]
use crate::serde_helpers::{cow_from_string, cow_option_from_string};

// =============================================================================
// Generated Column Types
// =============================================================================

/// Whether a generated column is `STORED` or `VIRTUAL` (`VIRTUAL` needs
/// PostgreSQL 18 or later).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "lowercase"))]
pub enum GeneratedType {
    /// Stored generated column
    #[default]
    Stored,
    /// Virtual generated column
    Virtual,
}

/// The `GENERATED ALWAYS AS (...)` part of a [`ColumnDef`].
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct GeneratedDef {
    /// SQL expression for generation
    pub expression: &'static str,
    /// `STORED` or `VIRTUAL`
    pub gen_type: GeneratedType,
}

impl GeneratedDef {
    /// Creates a `STORED` generated column from a SQL expression.
    #[must_use]
    pub const fn stored(expression: &'static str) -> Self {
        Self {
            expression,
            gen_type: GeneratedType::Stored,
        }
    }

    /// Creates a `VIRTUAL` generated column from a SQL expression.
    #[must_use]
    pub const fn virtual_col(expression: &'static str) -> Self {
        Self {
            expression,
            gen_type: GeneratedType::Virtual,
        }
    }

    /// Converts to the runtime [`Generated`].
    #[must_use]
    pub const fn into_generated(self) -> Generated {
        Generated {
            expression: Cow::Borrowed(self.expression),
            gen_type: self.gen_type,
        }
    }
}

/// The `GENERATED ALWAYS AS (...)` part of a [`Column`]. With `serde`, the
/// fields are named `as` and `type`.
#[derive(Clone, Debug, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
pub struct Generated {
    /// SQL expression for generation
    #[cfg_attr(
        feature = "serde",
        serde(rename = "as", deserialize_with = "cow_from_string")
    )]
    pub expression: Cow<'static, str>,
    /// `STORED` or `VIRTUAL`
    #[cfg_attr(feature = "serde", serde(rename = "type"))]
    pub gen_type: GeneratedType,
}

// =============================================================================
// Identity Column Types
// =============================================================================

/// Whether an identity column is `GENERATED ALWAYS` or `GENERATED BY DEFAULT`.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
pub enum IdentityType {
    /// GENERATED ALWAYS AS IDENTITY
    #[default]
    Always,
    /// GENERATED BY DEFAULT AS IDENTITY
    ByDefault,
}

/// The `GENERATED ... AS IDENTITY` part of a [`ColumnDef`], with the options
/// of its backing sequence. Numeric options are SQL literals stored as
/// strings, so they can hold any `bigint`.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct IdentityDef {
    /// Name of the backing sequence
    pub name: &'static str,
    /// Schema of the backing sequence
    pub schema: Option<&'static str>,
    /// `ALWAYS` or `BY DEFAULT`
    pub type_: IdentityType,
    /// `INCREMENT BY`
    pub increment: Option<&'static str>,
    /// `MINVALUE`
    pub min_value: Option<&'static str>,
    /// `MAXVALUE`
    pub max_value: Option<&'static str>,
    /// `START WITH`
    pub start_with: Option<&'static str>,
    /// `CACHE`
    pub cache: Option<i32>,
    /// `CYCLE`
    pub cycle: bool,
}

impl IdentityDef {
    /// Creates an identity backed by the sequence `name`, with default options.
    #[must_use]
    pub const fn new(name: &'static str, type_: IdentityType) -> Self {
        Self {
            name,
            schema: None,
            type_,
            increment: None,
            min_value: None,
            max_value: None,
            start_with: None,
            cache: None,
            cycle: false,
        }
    }

    /// Sets the sequence's schema.
    #[must_use]
    pub const fn schema(self, schema: &'static str) -> Self {
        Self {
            schema: Some(schema),
            ..self
        }
    }

    /// Sets `INCREMENT BY`.
    #[must_use]
    pub const fn increment(self, value: &'static str) -> Self {
        Self {
            increment: Some(value),
            ..self
        }
    }

    /// Sets `MINVALUE`.
    #[must_use]
    pub const fn min_value(self, value: &'static str) -> Self {
        Self {
            min_value: Some(value),
            ..self
        }
    }

    /// Sets `MAXVALUE`.
    #[must_use]
    pub const fn max_value(self, value: &'static str) -> Self {
        Self {
            max_value: Some(value),
            ..self
        }
    }

    /// Sets `START WITH`.
    #[must_use]
    pub const fn start_with(self, value: &'static str) -> Self {
        Self {
            start_with: Some(value),
            ..self
        }
    }

    /// Sets `CACHE`.
    #[must_use]
    pub const fn cache(self, value: i32) -> Self {
        Self {
            cache: Some(value),
            ..self
        }
    }

    /// Sets `CYCLE`.
    #[must_use]
    pub const fn cycle(self) -> Self {
        Self {
            cycle: true,
            ..self
        }
    }

    /// Converts to the runtime [`Identity`].
    #[must_use]
    pub const fn into_identity(self) -> Identity {
        Identity {
            name: Cow::Borrowed(self.name),
            schema: match self.schema {
                Some(s) => Some(Cow::Borrowed(s)),
                None => None,
            },
            type_: self.type_,
            increment: match self.increment {
                Some(s) => Some(Cow::Borrowed(s)),
                None => None,
            },
            min_value: match self.min_value {
                Some(s) => Some(Cow::Borrowed(s)),
                None => None,
            },
            max_value: match self.max_value {
                Some(s) => Some(Cow::Borrowed(s)),
                None => None,
            },
            start_with: match self.start_with {
                Some(s) => Some(Cow::Borrowed(s)),
                None => None,
            },
            cache: self.cache,
            cycle: if self.cycle { Some(true) } else { None },
        }
    }
}

/// The `GENERATED ... AS IDENTITY` part of a [`Column`]; see [`IdentityDef`].
#[derive(Clone, Debug, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
pub struct Identity {
    /// Name of the backing sequence
    #[cfg_attr(feature = "serde", serde(deserialize_with = "cow_from_string"))]
    pub name: Cow<'static, str>,

    /// Schema of the backing sequence
    #[cfg_attr(
        feature = "serde",
        serde(
            default,
            skip_serializing_if = "Option::is_none",
            deserialize_with = "cow_option_from_string"
        )
    )]
    pub schema: Option<Cow<'static, str>>,

    /// `ALWAYS` or `BY DEFAULT` (serialized as `type`: `"always"` or
    /// `"byDefault"`)
    #[cfg_attr(feature = "serde", serde(rename = "type"))]
    pub type_: IdentityType,

    /// `INCREMENT BY`
    #[cfg_attr(
        feature = "serde",
        serde(
            default,
            skip_serializing_if = "Option::is_none",
            deserialize_with = "cow_option_from_string"
        )
    )]
    pub increment: Option<Cow<'static, str>>,

    /// `MINVALUE`
    #[cfg_attr(
        feature = "serde",
        serde(
            default,
            skip_serializing_if = "Option::is_none",
            deserialize_with = "cow_option_from_string"
        )
    )]
    pub min_value: Option<Cow<'static, str>>,

    /// `MAXVALUE`
    #[cfg_attr(
        feature = "serde",
        serde(
            default,
            skip_serializing_if = "Option::is_none",
            deserialize_with = "cow_option_from_string"
        )
    )]
    pub max_value: Option<Cow<'static, str>>,

    /// `START WITH`
    #[cfg_attr(
        feature = "serde",
        serde(
            default,
            skip_serializing_if = "Option::is_none",
            deserialize_with = "cow_option_from_string"
        )
    )]
    pub start_with: Option<Cow<'static, str>>,

    /// `CACHE`
    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
    pub cache: Option<i32>,

    /// `CYCLE`
    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
    pub cycle: Option<bool>,
}

impl Identity {
    /// Creates a `GENERATED ALWAYS AS IDENTITY` backed by the sequence `name`.
    #[must_use]
    pub fn always(name: impl Into<Cow<'static, str>>) -> Self {
        Self {
            name: name.into(),
            schema: None,
            type_: IdentityType::Always,
            increment: None,
            min_value: None,
            max_value: None,
            start_with: None,
            cache: None,
            cycle: None,
        }
    }

    /// Creates a `GENERATED BY DEFAULT AS IDENTITY` backed by the sequence
    /// `name`.
    #[must_use]
    pub fn by_default(name: impl Into<Cow<'static, str>>) -> Self {
        Self {
            name: name.into(),
            schema: None,
            type_: IdentityType::ByDefault,
            increment: None,
            min_value: None,
            max_value: None,
            start_with: None,
            cache: None,
            cycle: None,
        }
    }

    /// Sets the sequence's schema.
    #[must_use]
    pub fn schema(mut self, schema: impl Into<Cow<'static, str>>) -> Self {
        self.schema = Some(schema.into());
        self
    }
}

// =============================================================================
// Const-friendly Definition Type
// =============================================================================

/// A column definition that can be built in a `const`.
///
/// Primary keys and unique constraints are separate entities
/// ([`PrimaryKeyDef`](super::PrimaryKeyDef),
/// [`UniqueConstraintDef`](super::UniqueConstraintDef)).
///
/// # Examples
///
/// ```
/// use drizzle_types::postgres::ddl::{ColumnDef, IdentityDef, IdentityType};
///
/// const ID: ColumnDef = ColumnDef::new("public", "users", "id", "integer")
///     .not_null()
///     .identity(IdentityDef::new("users_id_seq", IdentityType::Always));
///
/// let column = ID.into_column();
/// assert!(column.identity.is_some());
/// ```
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct ColumnDef {
    /// Schema name
    pub schema: &'static str,
    /// Parent table name
    pub table: &'static str,
    /// Column name
    pub name: &'static str,
    /// SQL type, such as `"integer"` or `"varchar(255)"`; for an enum, the
    /// enum's type name
    pub sql_type: &'static str,
    /// Schema of a custom or enum type
    pub type_schema: Option<&'static str>,
    /// `NOT NULL`
    pub not_null: bool,
    /// `DEFAULT` value as SQL
    pub default: Option<&'static str>,
    /// Generated column configuration
    pub generated: Option<GeneratedDef>,
    /// Identity column configuration
    pub identity: Option<IdentityDef>,
    /// Number of array dimensions: `Some(1)` renders `type[]`
    pub dimensions: Option<i32>,
    /// Column comment, emitted as `COMMENT ON COLUMN`
    pub comment: Option<&'static str>,
    /// Collation name (e.g. `"en_US"`, `"C"`, `"POSIX"`, or a custom
    /// `CREATE COLLATION` name). `None` uses the type's default collation and
    /// emits no `COLLATE` clause.
    pub collate: Option<&'static str>,
}

impl ColumnDef {
    /// Creates a nullable column with no default.
    #[must_use]
    pub const fn new(
        schema: &'static str,
        table: &'static str,
        name: &'static str,
        sql_type: &'static str,
    ) -> Self {
        Self {
            schema,
            table,
            name,
            sql_type,
            type_schema: None,
            not_null: false,
            default: None,
            generated: None,
            identity: None,
            dimensions: None,
            comment: None,
            collate: None,
        }
    }

    /// Sets the schema of a custom or enum type.
    #[must_use]
    pub const fn type_schema(self, schema: &'static str) -> Self {
        Self {
            type_schema: Some(schema),
            ..self
        }
    }

    /// Adds `NOT NULL`.
    #[must_use]
    pub const fn not_null(self) -> Self {
        Self {
            not_null: true,
            ..self
        }
    }

    /// Sets the `DEFAULT` value, written as SQL.
    #[must_use]
    pub const fn default_value(self, value: &'static str) -> Self {
        Self {
            default: Some(value),
            ..self
        }
    }

    /// Makes the column `GENERATED ALWAYS AS (expression) STORED`.
    #[must_use]
    pub const fn generated_stored(self, expression: &'static str) -> Self {
        Self {
            generated: Some(GeneratedDef::stored(expression)),
            ..self
        }
    }

    /// Makes the column `GENERATED ALWAYS AS (expression) VIRTUAL`.
    #[must_use]
    pub const fn generated_virtual(self, expression: &'static str) -> Self {
        Self {
            generated: Some(GeneratedDef::virtual_col(expression)),
            ..self
        }
    }

    /// Makes the column an identity column.
    #[must_use]
    pub const fn identity(self, identity: IdentityDef) -> Self {
        Self {
            identity: Some(identity),
            ..self
        }
    }

    /// Sets the number of array dimensions.
    #[must_use]
    pub const fn dimensions(self, dims: i32) -> Self {
        Self {
            dimensions: Some(dims),
            ..self
        }
    }

    /// Sets the column comment.
    #[must_use]
    pub const fn comment(self, comment: &'static str) -> Self {
        Self {
            comment: Some(comment),
            ..self
        }
    }

    /// Sets the column's collation.
    ///
    /// Pass the bare name, such as `en_US`; it is rendered quoted, as in
    /// `COLLATE "en_US"`.
    #[must_use]
    pub const fn collate(self, name: &'static str) -> Self {
        Self {
            collate: Some(name),
            ..self
        }
    }

    /// Converts to the runtime [`Column`].
    #[must_use]
    pub const fn into_column(self) -> Column {
        Column {
            schema: Cow::Borrowed(self.schema),
            table: Cow::Borrowed(self.table),
            name: Cow::Borrowed(self.name),
            sql_type: Cow::Borrowed(self.sql_type),
            type_schema: match self.type_schema {
                Some(s) => Some(Cow::Borrowed(s)),
                None => None,
            },
            not_null: self.not_null,
            default: match self.default {
                Some(s) => Some(Cow::Borrowed(s)),
                None => None,
            },
            generated: match self.generated {
                Some(g) => Some(g.into_generated()),
                None => None,
            },
            identity: match self.identity {
                Some(i) => Some(i.into_identity()),
                None => None,
            },
            dimensions: self.dimensions,
            comment: match self.comment {
                Some(s) => Some(Cow::Borrowed(s)),
                None => None,
            },
            collate: match self.collate {
                Some(s) => Some(Cow::Borrowed(s)),
                None => None,
            },
            ordinal_position: None,
        }
    }
}

impl Default for ColumnDef {
    fn default() -> Self {
        Self::new("public", "", "", "")
    }
}

// =============================================================================
// Runtime Type for Serde
// =============================================================================

/// A table column, as stored in migration snapshots.
#[derive(Clone, Debug, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
pub struct Column {
    /// Schema name
    #[cfg_attr(feature = "serde", serde(deserialize_with = "cow_from_string"))]
    pub schema: Cow<'static, str>,

    /// Parent table name
    #[cfg_attr(feature = "serde", serde(deserialize_with = "cow_from_string"))]
    pub table: Cow<'static, str>,

    /// Column name
    #[cfg_attr(feature = "serde", serde(deserialize_with = "cow_from_string"))]
    pub name: Cow<'static, str>,

    /// SQL type, such as `"integer"` (serialized as `type`)
    #[cfg_attr(
        feature = "serde",
        serde(rename = "type", deserialize_with = "cow_from_string")
    )]
    pub sql_type: Cow<'static, str>,

    /// Schema of a custom or enum type
    #[cfg_attr(
        feature = "serde",
        serde(
            default,
            skip_serializing_if = "Option::is_none",
            deserialize_with = "cow_option_from_string"
        )
    )]
    pub type_schema: Option<Cow<'static, str>>,

    /// `NOT NULL`
    #[cfg_attr(feature = "serde", serde(default))]
    pub not_null: bool,

    /// `DEFAULT` value as SQL
    #[cfg_attr(
        feature = "serde",
        serde(default, deserialize_with = "cow_option_from_string")
    )]
    pub default: Option<Cow<'static, str>>,

    /// Generated column configuration
    #[cfg_attr(feature = "serde", serde(default))]
    pub generated: Option<Generated>,

    /// Identity column configuration
    #[cfg_attr(feature = "serde", serde(default))]
    pub identity: Option<Identity>,

    /// Number of array dimensions
    #[cfg_attr(feature = "serde", serde(default))]
    pub dimensions: Option<i32>,

    /// Column comment, emitted as `COMMENT ON COLUMN`
    #[cfg_attr(
        feature = "serde",
        serde(
            default,
            skip_serializing_if = "Option::is_none",
            deserialize_with = "cow_option_from_string"
        )
    )]
    pub comment: Option<Cow<'static, str>>,

    /// Collation name (e.g. `"en_US"`, `"C"`). `None` means the database
    /// default collation and no `COLLATE` clause is emitted.
    #[cfg_attr(
        feature = "serde",
        serde(default, deserialize_with = "cow_option_from_string")
    )]
    pub collate: Option<Cow<'static, str>>,

    /// Ordinal position within the table (1-based).
    ///
    /// This is primarily populated by introspection and used for stable codegen ordering.
    #[cfg_attr(
        feature = "serde",
        serde(default, skip_serializing_if = "Option::is_none")
    )]
    pub ordinal_position: Option<i32>,
}

impl Column {
    /// Creates a nullable column with no default.
    #[must_use]
    pub fn new(
        schema: impl Into<Cow<'static, str>>,
        table: impl Into<Cow<'static, str>>,
        name: impl Into<Cow<'static, str>>,
        sql_type: impl Into<Cow<'static, str>>,
    ) -> Self {
        Self {
            schema: schema.into(),
            table: table.into(),
            name: name.into(),
            sql_type: sql_type.into(),
            type_schema: None,
            not_null: false,
            default: None,
            generated: None,
            identity: None,
            dimensions: None,
            comment: None,
            collate: None,
            ordinal_position: None,
        }
    }

    /// Adds `NOT NULL`.
    #[must_use]
    pub const fn not_null(mut self) -> Self {
        self.not_null = true;
        self
    }

    /// Sets the `DEFAULT` value, written as SQL.
    #[must_use]
    pub fn default_value(mut self, value: impl Into<Cow<'static, str>>) -> Self {
        self.default = Some(value.into());
        self
    }

    /// Makes the column an identity column.
    #[must_use]
    pub fn identity(mut self, identity: Identity) -> Self {
        self.identity = Some(identity);
        self
    }

    /// Sets the column comment.
    #[must_use]
    pub fn comment(mut self, comment: impl Into<Cow<'static, str>>) -> Self {
        self.comment = Some(comment.into());
        self
    }

    /// Returns the schema name.
    #[inline]
    #[must_use]
    pub fn schema(&self) -> &str {
        &self.schema
    }

    /// Returns the table name.
    #[inline]
    #[must_use]
    pub fn table(&self) -> &str {
        &self.table
    }

    /// Returns the column name.
    #[inline]
    #[must_use]
    pub fn name(&self) -> &str {
        &self.name
    }

    /// Returns the SQL type.
    #[inline]
    #[must_use]
    pub fn sql_type(&self) -> &str {
        &self.sql_type
    }
}

impl Default for Column {
    fn default() -> Self {
        Self::new("public", "", "", "")
    }
}

impl From<ColumnDef> for Column {
    fn from(def: ColumnDef) -> Self {
        def.into_column()
    }
}

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

    #[test]
    fn test_const_column_def() {
        const COLDEF: ColumnDef = ColumnDef::new("public", "users", "id", "INTEGER").not_null();

        assert_eq!(COLDEF.schema, "public");
        assert_eq!(COLDEF.name, "id");
        assert_eq!(COLDEF.table, "users");
        assert_eq!(COLDEF.sql_type, "INTEGER");
        const {
            assert!(COLDEF.not_null);
        }

        let col: Column = COLDEF.into_column();

        assert_eq!(col.schema, Cow::Borrowed("public"));
        assert_eq!(col.name, Cow::Borrowed("id"));
        assert_eq!(col.table, Cow::Borrowed("users"));
        assert_eq!(col.sql_type, Cow::Borrowed("INTEGER"));
        assert!(col.not_null);
    }

    #[test]
    fn test_identity_column() {
        const IDENTITY_DEF: IdentityDef = IdentityDef::new("users_id_seq", IdentityType::Always)
            .increment("1")
            .start_with("1");

        const COL: ColumnDef =
            ColumnDef::new("public", "users", "id", "INTEGER").identity(IDENTITY_DEF);

        assert!(COL.identity.is_some());
    }

    #[test]
    fn test_generated_virtual_column() {
        const COL: ColumnDef = ColumnDef::new("public", "users", "name_len", "INTEGER")
            .generated_virtual("length(name)");

        assert_eq!(
            COL.generated.expect("generated column").gen_type,
            GeneratedType::Virtual
        );

        let col = COL.into_column();
        assert_eq!(
            col.generated.expect("generated column").gen_type,
            GeneratedType::Virtual
        );
    }

    #[cfg(feature = "serde")]
    #[test]
    fn test_serde_roundtrip() {
        let col = Column::new("public", "users", "id", "INTEGER");
        let json = serde_json::to_string(&col).unwrap();
        let parsed: Column = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed.name(), "id");
    }
}