nautilus-orm-core 0.1.3

//! Structured argument types for query operations.

use std::collections::HashMap;

use crate::{Expr, OrderBy, Value};

/// Arguments for eagerly loading a single relation in a query.
///
/// ```text
/// include: { posts: { where: { published: true } } }
/// ```
#[derive(Debug, Default, Clone)]
pub struct IncludeRelation {
    /// Optional filter to apply to the included child records.
    pub where_: Option<Expr>,
}

impl IncludeRelation {
    /// Create a plain include with no child filter.
    pub fn plain() -> Self {
        IncludeRelation { where_: None }
    }

    /// Create an include with a child filter.
    pub fn with_filter(filter: Expr) -> Self {
        IncludeRelation {
            where_: Some(filter),
        }
    }
}

/// Arguments accepted by `find_unique` and `find_unique_or_throw` delegate methods.
///
/// Uses a required `where_` filter (no ordering/pagination — implicit LIMIT 1).
///
/// # Example
/// ```rust,ignore
/// let args = FindUniqueArgs::new(
///     User::columns().email.eq("alice@example.com"),
/// );
/// let user = client.user.find_unique(args).await?;
/// ```
#[derive(Debug, Clone)]
pub struct FindUniqueArgs {
    /// WHERE filter expression (required — must reference a unique/PK field).
    pub where_: Expr,
    /// Projection: only return the specified fields.
    ///
    /// If empty, all columns are returned. When specified, PK columns are
    /// always included regardless. Cannot be used together with `include`.
    pub select: HashMap<String, bool>,
}

impl FindUniqueArgs {
    /// Construct with a required filter expression.
    pub fn new(filter: Expr) -> Self {
        FindUniqueArgs {
            where_: filter,
            select: HashMap::new(),
        }
    }
}

/// Arguments accepted by `find_many` and `find_first` delegate methods.
///
/// All fields are optional and default to "no constraint".
///
/// # Example
/// ```rust,ignore
/// let args = FindManyArgs {
///     where_: Some(User::columns().email.eq("alice@example.com")),
///     take: Some(10),
///     ..Default::default()
/// };
/// let users = client.user.find_many(args).await?;
/// ```
#[derive(Debug, Default, Clone)]
pub struct FindManyArgs {
    /// Optional WHERE filter expression.
    pub where_: Option<Expr>,
    /// ORDER BY clauses (applied in order).
    pub order_by: Vec<OrderBy>,
    /// Maximum number of rows to return (LIMIT).
    ///
    /// Positive values paginate **forward**; negative values paginate
    /// **backward** (reverses the result set in application code after
    /// flipping `ORDER BY` directions — no DB-specific SQL needed).
    /// Only meaningful when `cursor` is also set.
    pub take: Option<i32>,
    /// Number of rows to skip (OFFSET), applied relative to the cursor position
    /// when `cursor` is set, or from the start of the result set otherwise.
    pub skip: Option<u32>,
    /// Relations to eager-load, with optional per-relation filters.
    ///
    /// Key is the relation field name (e.g. `"posts"`), value controls
    /// how that relation is included (filter, etc.).
    ///
    /// Cannot be used together with `select`.
    pub include: HashMap<String, IncludeRelation>,
    /// Projection: only return the specified scalar fields.
    ///
    /// Key is the field name (logical name), value must be `true` to include
    /// the field. PK fields are always returned regardless. When empty, all
    /// columns are returned.
    ///
    /// Cannot be used together with `include`.
    pub select: HashMap<String, bool>,
    /// Cursor for stable (keyset) pagination.
    ///
    /// A map of **primary-key field name → value** that identifies the record
    /// from which the page should start.  When
    /// combined with `take` / `skip`, they are applied relative to this anchor
    /// record rather than from the absolute start of the table.
    ///
    /// All primary-key fields of the model must be present in the map.
    pub cursor: Option<HashMap<String, Value>>,
    /// Columns to deduplicate on (SELECT DISTINCT / DISTINCT ON).
    ///
    /// Specifying one or more field names activates column-level deduplication:
    /// - **Postgres**: rendered as `SELECT DISTINCT ON (col, ...)` with those
    ///   columns automatically prepended to `ORDER BY` as required by Postgres.
    /// - **SQLite / MySQL**: rendered as plain `SELECT DISTINCT` (full-row
    ///   deduplication — most effective when combined with `select` projection).
    ///
    /// When empty (the default), no deduplication is applied.
    pub distinct: Vec<String>,
}