drizzle-core 0.4.1

//! [`RelationHandle`]: settings for loading one relation.

use core::marker::PhantomData;

use crate::relation::RelationDef;
use crate::{PaginationArg, SQL, SQLParam};

use super::builder::{
    AllColumns, Clauses, HasLimit, HasOffset, HasOrderBy, HasWhere, IntoColumnSelection, NoLimit,
    NoOrderBy, NoWhere, PartialColumns, QueryTable,
};

/// Settings for loading one relation: filters, order, limits, columns, and
/// nested relations.
///
/// Created by the relation methods the table macros generate (for example
/// `users.posts()`) and passed to `.with(...)`.
///
/// A handle without nested relations is also the related rows as a
/// correlated subquery, usable in any query's `where` or `order_by`:
///
/// - `exists(users.posts())` / `not_exists(users.posts())`: whether a user
///   has posts; the handle's `where` narrows the rows that count, as in
///   `exists(users.posts().r#where(eq(posts.published, true)))`.
/// - [`select`](Self::select): a scalar over the related rows, such as
///   `users.posts().select(count(()))`, or a column of a to-one relation,
///   such as `posts.author().select(users.name)`.
///
/// - `Nested` holds nested relation handles: `()` when empty,
///   `(RelationHandle<...>, Rest)` otherwise, so the whole tree is part of
///   the type.
/// - `Cols` is [`AllColumns`] (default) or [`PartialColumns`].
/// - `Cl` is a [`Clauses`] value recording which of WHERE, ORDER BY,
///   LIMIT and OFFSET are set. Each can be set once.
///
/// WHERE and ORDER BY may only read columns of the relation's target table.
pub struct RelationHandle<
    'a,
    V: SQLParam,
    R: RelationDef,
    Nested = (),
    Cols = AllColumns,
    Cl = Clauses,
> {
    pub(crate) where_sql: SQL<'a, V>,
    pub(crate) order_by_sql: SQL<'a, V>,
    pub(crate) limit: Option<SQL<'a, V>>,
    pub(crate) offset: Option<SQL<'a, V>>,
    pub(crate) nested: Nested,
    pub(crate) cols: Cols,
    pub(crate) _marker: PhantomData<(R, Cl)>,
}

impl<'a, V: SQLParam, R: RelationDef> RelationHandle<'a, V, R> {
    /// Creates a handle with no settings.
    #[must_use]
    pub const fn new() -> Self {
        Self {
            where_sql: SQL::empty(),
            order_by_sql: SQL::empty(),
            limit: None,
            offset: None,
            nested: (),
            cols: AllColumns,
            _marker: PhantomData,
        }
    }
}

impl<'a, V: SQLParam, R: RelationDef> Default for RelationHandle<'a, V, R> {
    fn default() -> Self {
        Self::new()
    }
}

impl<'a, V: SQLParam, R: RelationDef, Nested, Cols, Cl> RelationHandle<'a, V, R, Nested, Cols, Cl> {
    /// Also loads the relation `handle` of the target table, nested inside
    /// each loaded row.
    #[allow(clippy::type_complexity)]
    pub fn with<NR, NN, NC, NCl>(
        self,
        handle: RelationHandle<'a, V, NR, NN, NC, NCl>,
    ) -> RelationHandle<'a, V, R, (RelationHandle<'a, V, NR, NN, NC, NCl>, Nested), Cols, Cl>
    where
        NR: RelationDef<Source = R::Target> + 'static,
    {
        RelationHandle {
            where_sql: self.where_sql,
            order_by_sql: self.order_by_sql,
            limit: self.limit,
            offset: self.offset,
            nested: (handle, self.nested),
            cols: self.cols,
            _marker: PhantomData,
        }
    }
}

/// WHERE is only available when no WHERE clause has been set yet.
impl<'a, V: SQLParam, R: RelationDef, Nested, Cols, Ord, Lim>
    RelationHandle<'a, V, R, Nested, Cols, Clauses<NoWhere, Ord, Lim>>
{
    /// Sets the WHERE clause for the loaded rows.
    ///
    /// Can only be called once; combine conditions with `and(...)` or
    /// `or(...)`. The condition must be boolean and may only read columns of
    /// the target table.
    pub fn r#where<E, ScopeProof>(
        self,
        condition: E,
    ) -> RelationHandle<'a, V, R, Nested, Cols, Clauses<HasWhere, Ord, Lim>>
    where
        R::Card: crate::relation::Filtered,
        E: crate::expr::Expr<'a, V>,
        E::Sources: crate::scope::SourcesIn<crate::Cons<R::Target, crate::Nil>, ScopeProof>,
        E::SQLType: crate::types::BooleanLike,
        V: 'a,
    {
        RelationHandle {
            where_sql: condition.into_expr_sql(),
            order_by_sql: self.order_by_sql,
            limit: self.limit,
            offset: self.offset,
            nested: self.nested,
            cols: self.cols,
            _marker: PhantomData,
        }
    }
}

/// ORDER BY is only available when no ORDER BY clause has been set yet.
impl<'a, V: SQLParam, R: RelationDef, Nested, Cols, W, Lim>
    RelationHandle<'a, V, R, Nested, Cols, Clauses<W, NoOrderBy, Lim>>
{
    /// Sets the ORDER BY clause for the loaded rows, such as `asc(col)`.
    ///
    /// Can only be called once. The expressions may only read columns of the
    /// target table.
    pub fn order_by<E, ScopeProof>(
        self,
        expr: E,
    ) -> RelationHandle<'a, V, R, Nested, Cols, Clauses<W, HasOrderBy, Lim>>
    where
        E: crate::traits::ToSQL<'a, V> + crate::expr::ExprSources,
        E::Sources: crate::scope::SourcesIn<crate::Cons<R::Target, crate::Nil>, ScopeProof>,
        V: 'a,
    {
        RelationHandle {
            where_sql: self.where_sql,
            order_by_sql: expr.to_sql(),
            limit: self.limit,
            offset: self.offset,
            nested: self.nested,
            cols: self.cols,
            _marker: PhantomData,
        }
    }
}

/// LIMIT is only available on a relation that loads many rows, and only
/// when no LIMIT has been set yet.
impl<'a, V: SQLParam, R: RelationDef, Nested, Cols, W, Ord>
    RelationHandle<'a, V, R, Nested, Cols, Clauses<W, Ord, NoLimit>>
{
    /// Sets the LIMIT for the loaded rows. Can only be called once, and must
    /// come before `.offset(...)`.
    pub fn limit<P>(self, n: P) -> RelationHandle<'a, V, R, Nested, Cols, Clauses<W, Ord, HasLimit>>
    where
        R::Card: crate::relation::Paginated,
        P: PaginationArg<'a, V>,
        V: 'a,
    {
        RelationHandle {
            where_sql: self.where_sql,
            order_by_sql: self.order_by_sql,
            limit: Some(n.into_pagination_sql()),
            offset: self.offset,
            nested: self.nested,
            cols: self.cols,
            _marker: PhantomData,
        }
    }

    /// Same as `.limit(1)`: loads at most one row.
    ///
    /// The field keeps its type: still a `Vec`, with at most one element.
    pub fn first(self) -> RelationHandle<'a, V, R, Nested, Cols, Clauses<W, Ord, HasLimit>>
    where
        R::Card: crate::relation::Paginated,
    {
        self.limit(1u32)
    }
}

/// OFFSET requires LIMIT to have been set first.
impl<'a, V: SQLParam, R: RelationDef, Nested, Cols, W, Ord>
    RelationHandle<'a, V, R, Nested, Cols, Clauses<W, Ord, HasLimit>>
{
    /// Sets the OFFSET for the loaded rows. Only available after
    /// `.limit(...)`.
    pub fn offset<P>(
        self,
        n: P,
    ) -> RelationHandle<'a, V, R, Nested, Cols, Clauses<W, Ord, HasOffset>>
    where
        P: PaginationArg<'a, V>,
        V: 'a,
    {
        RelationHandle {
            where_sql: self.where_sql,
            order_by_sql: self.order_by_sql,
            limit: self.limit,
            offset: Some(n.into_pagination_sql()),
            nested: self.nested,
            cols: self.cols,
            _marker: PhantomData,
        }
    }
}

// Column selection can only be chosen once.
impl<'a, V: SQLParam, R: RelationDef, Nested, Cl> RelationHandle<'a, V, R, Nested, AllColumns, Cl>
where
    R::Target: QueryTable,
{
    /// Loads only the given columns of the target table.
    pub fn columns<S: IntoColumnSelection>(
        self,
        selector: S,
    ) -> RelationHandle<'a, V, R, Nested, PartialColumns, Cl> {
        RelationHandle {
            where_sql: self.where_sql,
            order_by_sql: self.order_by_sql,
            limit: self.limit,
            offset: self.offset,
            nested: self.nested,
            cols: PartialColumns {
                columns: selector.into_column_names(),
            },
            _marker: PhantomData,
        }
    }

    /// Loads every column of the target table except the given ones.
    pub fn omit<S: IntoColumnSelection>(
        self,
        selector: S,
    ) -> RelationHandle<'a, V, R, Nested, PartialColumns, Cl> {
        let omitted = selector.into_column_names();
        let columns = <R::Target as QueryTable>::COLUMN_NAMES
            .iter()
            .copied()
            .filter(|c| !omitted.contains(c))
            .collect();
        RelationHandle {
            where_sql: self.where_sql,
            order_by_sql: self.order_by_sql,
            limit: self.limit,
            offset: self.offset,
            nested: self.nested,
            cols: PartialColumns { columns },
            _marker: PhantomData,
        }
    }
}

// =============================================================================
// The relation's rows as a correlated subquery
// =============================================================================

impl<'a, V, R, Cols, Cl> RelationHandle<'a, V, R, (), Cols, Cl>
where
    V: SQLParam + 'a,
    R: RelationDef,
    R::Source: QueryTable,
{
    fn subquery_sql(self, select: SQL<'a, V>) -> SQL<'a, V> {
        super::sql::relation_subquery_sql(
            select,
            <R::Target as QueryTable>::TABLE,
            <R::Source as QueryTable>::TABLE_NAME,
            R::NAME,
            R::junction(),
            R::fk_columns(),
            self.where_sql,
            self.order_by_sql,
            self.limit,
            self.offset,
        )
    }

    /// The related rows' `expr`, as a scalar subquery correlated with the
    /// source row: an aggregate over them, or a column of a one-relation.
    ///
    /// The relation's `where`, `order_by` and `limit` apply first, so
    /// `users.posts().order_by(desc(posts.created_at)).first().select(posts.title)`
    /// is the newest post's title. Use it wherever an expression of the
    /// source table goes, such as a relational query's `order_by`:
    /// `db.query(users).order_by(desc(users.posts().select(count(()))))`.
    ///
    /// The result is nullable: with no related row, a subquery reads NULL.
    #[allow(clippy::type_complexity)]
    pub fn select<E, ScopeProof>(
        self,
        expr: E,
    ) -> crate::expr::SQLExpr<
        'a,
        V,
        E::SQLType,
        crate::expr::Null,
        crate::expr::Scalar,
        crate::Src<R::Source>,
    >
    where
        E: crate::expr::Expr<'a, V>,
        E::Sources: crate::scope::SourcesIn<crate::Cons<R::Target, crate::Nil>, ScopeProof>,
    {
        crate::expr::SQLExpr::new(self.subquery_sql(expr.into_expr_sql()).parens())
    }
}

/// The relation's rows as a subquery, for [`exists`](crate::expr::exists)
/// and [`not_exists`](crate::expr::not_exists): `exists(users.posts())` is
/// true for a user with a post, and the relation's `where` narrows the rows
/// that count.
impl<'a, V, R, Cols, Cl> crate::ToSQL<'a, V> for RelationHandle<'a, V, R, (), Cols, Cl>
where
    V: SQLParam + 'a,
    R: RelationDef,
    R::Source: QueryTable,
{
    fn to_sql(&self) -> SQL<'a, V> {
        RelationHandle::<'a, V, R, (), AllColumns, Cl> {
            where_sql: self.where_sql.clone(),
            order_by_sql: self.order_by_sql.clone(),
            limit: self.limit.clone(),
            offset: self.offset.clone(),
            nested: (),
            cols: AllColumns,
            _marker: PhantomData,
        }
        .into_sql()
    }

    fn into_sql(self) -> SQL<'a, V> {
        self.subquery_sql(SQL::raw("1"))
    }
}

impl<'a, V, R, Cols, Cl> crate::expr::ExprSources for RelationHandle<'a, V, R, (), Cols, Cl>
where
    V: SQLParam,
    R: RelationDef,
{
    type Sources = crate::Src<R::Source>;
}

impl<'a, V, R, Cols, Cl> crate::expr::SelectQuery for RelationHandle<'a, V, R, (), Cols, Cl>
where
    V: SQLParam,
    R: RelationDef,
{
}