icydb_core/db/query/

session.rs

use crate::{
    db::{
        DbSession,
        query::{
            Query, QueryError,
            plan::{ExecutablePlan, ExplainPlan},
            predicate::Predicate,
        },
        response::Response,
    },
    key::Key,
    traits::{CanisterKind, EntityKind},
    view::View,
};

///
/// SessionLoadQuery
///
/// Fluent, session-bound load query wrapper that keeps intent pure
/// while routing execution through the `DbSession` boundary.
///

pub struct SessionLoadQuery<'a, C: CanisterKind, E: EntityKind<Canister = C>> {
    session: &'a DbSession<C>,
    query: Query<E>,
}

impl<'a, C: CanisterKind, E: EntityKind<Canister = C>> SessionLoadQuery<'a, C, E> {
    pub(crate) const fn new(session: &'a DbSession<C>, query: Query<E>) -> Self {
        Self { session, query }
    }

    // ------------------------------------------------------------------
    // Intent inspection
    // ------------------------------------------------------------------

    /// Return a reference to the underlying query intent.
    #[must_use]
    pub const fn query(&self) -> &Query<E> {
        &self.query
    }

    // ------------------------------------------------------------------
    // Intent builders (pure, no execution)
    // ------------------------------------------------------------------

    /// Filter by primary key.
    #[must_use]
    pub fn key(mut self, key: impl Into<Key>) -> Self {
        self.query = self.query.by_key(key.into());
        self
    }

    /// Load multiple entities by primary key.
    ///
    /// Semantics:
    /// - Equivalent to `WHERE pk IN (…)`
    /// - Uses key-based access (ByKey / ByKeys)
    /// - Missing keys are ignored in MissingOk mode
    /// - Strict mode treats missing rows as corruption
    #[must_use]
    pub fn many<I>(mut self, keys: I) -> Self
    where
        I: IntoIterator<Item = E::PrimaryKey>,
    {
        self.query = self.query.by_keys(keys.into_iter().map(Into::into));
        self
    }

    /// Add a predicate, implicitly AND-ing with any existing predicate.
    #[must_use]
    pub fn filter(mut self, predicate: Predicate) -> Self {
        self.query = self.query.filter(predicate);
        self
    }

    /// Append an ascending sort key.
    #[must_use]
    pub fn order_by(mut self, field: impl AsRef<str>) -> Self {
        self.query = self.query.order_by(field);
        self
    }

    /// Append a descending sort key.
    #[must_use]
    pub fn order_by_desc(mut self, field: impl AsRef<str>) -> Self {
        self.query = self.query.order_by_desc(field);
        self
    }

    /// Apply a load limit to bound result size.
    #[must_use]
    pub fn limit(mut self, limit: u32) -> Self {
        self.query = self.query.limit(limit);
        self
    }

    /// Apply a load offset.
    #[must_use]
    pub fn offset(mut self, offset: u64) -> Self {
        self.query = self.query.offset(offset);
        self
    }

    // ------------------------------------------------------------------
    // Planning / diagnostics
    // ------------------------------------------------------------------

    /// Explain this query without executing it.
    pub fn explain(&self) -> Result<ExplainPlan, QueryError> {
        self.query.explain()
    }

    /// Plan this query into an executor-ready plan.
    pub fn plan(&self) -> Result<ExecutablePlan<E>, QueryError> {
        self.query.plan()
    }

    // ------------------------------------------------------------------
    // Execution (single boundary)
    // ------------------------------------------------------------------

    /// Execute this query using the session's policy settings.
    pub fn execute(&self) -> Result<Response<E>, QueryError> {
        self.session.execute_query(self.query())
    }

    // ------------------------------------------------------------------
    // Execution terminals (interpretation)
    // ------------------------------------------------------------------

    /// Return whether any rows match this query.
    pub fn exists(&self) -> Result<bool, QueryError> {
        Ok(self.count()? > 0)
    }

    /// Execute and return the number of matching rows.
    pub fn count(&self) -> Result<u64, QueryError> {
        Ok(self.execute()?.count())
    }

    /// Execute and return all entities.
    pub fn all(&self) -> Result<Vec<E>, QueryError> {
        Ok(self.execute()?.entities())
    }

    /// Execute and return all results as views.
    pub fn views(&self) -> Result<Vec<View<E>>, QueryError> {
        Ok(self.execute()?.views())
    }

    /// Execute and require exactly one entity.
    pub fn one(&self) -> Result<E, QueryError> {
        self.execute()?.entity().map_err(QueryError::Execute)
    }

    /// Execute and require exactly one view.
    pub fn view(&self) -> Result<View<E>, QueryError> {
        self.execute()?.view().map_err(QueryError::Execute)
    }

    /// Execute and return zero or one entity.
    pub fn one_opt(&self) -> Result<Option<E>, QueryError> {
        self.execute()?.try_entity().map_err(QueryError::Execute)
    }

    /// Execute and return zero or one view.
    pub fn view_opt(&self) -> Result<Option<View<E>>, QueryError> {
        self.execute()?.view_opt().map_err(QueryError::Execute)
    }
}

impl<C: CanisterKind, E: EntityKind<Canister = C, PrimaryKey = ()>> SessionLoadQuery<'_, C, E> {
    /// Load the singleton entity identified by the unit primary key `()`.
    ///
    /// Semantics:
    /// - Equivalent to `WHERE pk = ()`
    /// - Uses key-based access (ByKey)
    /// - Does not allow predicates
    /// - MissingOk mode returns empty
    /// - Strict mode treats missing row as corruption
    #[must_use]
    pub fn only(mut self) -> Self {
        self.query = self.query.only();
        self
    }
}

///
/// SessionDeleteQuery
///
/// Fluent, session-bound delete query wrapper that keeps query intent pure
/// while routing execution through the `DbSession` boundary.
///

pub struct SessionDeleteQuery<'a, C: CanisterKind, E: EntityKind<Canister = C>> {
    session: &'a DbSession<C>,
    query: Query<E>,
}

impl<'a, C: CanisterKind, E: EntityKind<Canister = C>> SessionDeleteQuery<'a, C, E> {
    pub(crate) const fn new(session: &'a DbSession<C>, query: Query<E>) -> Self {
        Self { session, query }
    }

    // ------------------------------------------------------------------
    // Intent inspection
    // ------------------------------------------------------------------

    #[must_use]
    pub const fn query(&self) -> &Query<E> {
        &self.query
    }

    // ------------------------------------------------------------------
    // Intent builders
    // ------------------------------------------------------------------

    /// Delete by primary key.
    #[must_use]
    pub fn key(mut self, key: impl Into<Key>) -> Self {
        self.query = self.query.by_key(key.into());
        self
    }

    /// Delete multiple entities by primary key.
    ///
    /// Semantics:
    /// - Equivalent to `WHERE pk IN (…)`
    /// - Uses key-based access (ByKey / ByKeys)
    /// - Missing keys are ignored in MissingOk mode
    /// - Strict mode treats missing rows as corruption
    #[must_use]
    pub fn many<I>(mut self, keys: I) -> Self
    where
        I: IntoIterator<Item = E::PrimaryKey>,
    {
        self.query = self.query.by_keys(keys.into_iter().map(Into::into));
        self
    }

    /// Add a predicate, implicitly AND-ing with any existing predicate.
    #[must_use]
    pub fn filter(mut self, predicate: Predicate) -> Self {
        self.query = self.query.filter(predicate);
        self
    }

    /// Append an ascending sort key.
    #[must_use]
    pub fn order_by(mut self, field: impl AsRef<str>) -> Self {
        self.query = self.query.order_by(field);
        self
    }

    /// Append a descending sort key.
    #[must_use]
    pub fn order_by_desc(mut self, field: impl AsRef<str>) -> Self {
        self.query = self.query.order_by_desc(field);
        self
    }

    /// Apply a delete limit to bound mutation size.
    #[must_use]
    pub fn limit(mut self, limit: u32) -> Self {
        self.query = self.query.limit(limit);
        self
    }

    // ------------------------------------------------------------------
    // Planning / diagnostics
    // ------------------------------------------------------------------

    pub fn explain(&self) -> Result<ExplainPlan, QueryError> {
        self.query.explain()
    }

    pub fn plan(&self) -> Result<ExecutablePlan<E>, QueryError> {
        self.query.plan()
    }

    // ------------------------------------------------------------------
    // Execution
    // ------------------------------------------------------------------

    pub fn execute(&self) -> Result<Response<E>, QueryError> {
        self.session.execute_query(self.query())
    }

    /// Execute a delete query and return the deleted rows.
    pub fn delete_rows(&self) -> Result<Response<E>, QueryError> {
        self.execute()
    }
}

impl<C: CanisterKind, E: EntityKind<Canister = C, PrimaryKey = ()>> SessionDeleteQuery<'_, C, E> {
    /// Delete the singleton entity identified by the unit primary key `()`.
    ///
    /// Semantics:
    /// - Equivalent to `DELETE … WHERE pk = ()`
    /// - Uses key-based access (ByKey)
    /// - MissingOk mode is idempotent
    /// - Strict mode treats missing row as corruption
    #[must_use]
    pub fn only(mut self) -> Self {
        self.query = self.query.only();
        self
    }
}