icydb 0.202.1

//! Module: db::session::delete
//!
//! Responsibility: public session and fluent query facade.
//! Does not own: core execution, storage engines, or planner semantics.
//! Boundary: wraps core sessions with stable generated-code and application APIs.

use crate::{
    db::{
        DbSession,
        query::{CompiledQuery, ExplainPlan, FilterExpr, PlannedQuery, QueryTracePlan},
        response::RowProjectionOutput,
        session::macros::impl_session_query_shape_methods,
    },
    error::Error,
    traits::{Entity, SingletonEntity},
    types::Id,
};

use icydb_core as core;

///
/// SessionDeleteQuery
///
/// Session-bound fluent wrapper for typed delete queries.
/// This facade keeps delete query shaping and execution on the public
/// `icydb` surface while delegating planning and enforcement to `icydb-core`.
///

pub struct SessionDeleteQuery<'a, E: Entity> {
    pub(crate) inner: core::db::FluentDeleteQuery<'a, E>,
}

// Fluent delete returning selection kept private so the public surface only
// exposes the query wrapper types and the shared row projection payload.
#[derive(Clone, Debug)]
enum DeleteReturningSelection {
    All,
    Fields(Vec<String>),
}

impl DeleteReturningSelection {
    const fn selected_fields(&self) -> Option<&[String]> {
        match self {
            Self::All => None,
            Self::Fields(fields) => Some(fields.as_slice()),
        }
    }
}

///
/// SessionDeleteReturningQuery
///
/// Session-bound fluent wrapper for typed delete queries that explicitly
/// request deleted rows. This keeps fluent `DELETE ... RETURNING` on the same
/// outward projection contract as the typed write-returning helpers instead of
/// inventing a second row-returning result family.
///

pub struct SessionDeleteReturningQuery<'a, E: Entity> {
    inner: core::db::FluentDeleteQuery<'a, E>,
    selection: DeleteReturningSelection,
}

impl<'a, E: Entity> SessionDeleteQuery<'a, E> {
    // ------------------------------------------------------------------
    // Primary-key access (query shaping)
    // ------------------------------------------------------------------

    impl_session_query_shape_methods!();

    // ------------------------------------------------------------------
    // Query refinement
    // ------------------------------------------------------------------

    /// Set the maximum number of rows this delete may affect.
    #[must_use]
    pub fn max_affected(mut self, limit: u32) -> Self {
        self.inner = self.inner.max_affected(limit);
        self
    }

    /// Return the stable plan hash for this query.
    pub fn plan_hash_hex(&self) -> Result<String, Error> {
        Ok(self.inner.plan_hash_hex()?)
    }

    /// Build one trace payload without executing the query.
    pub fn trace(&self) -> Result<QueryTracePlan, Error> {
        Ok(self.inner.trace()?)
    }

    /// Build logical explain metadata for the current query.
    pub fn explain(&self) -> Result<ExplainPlan, Error> {
        Ok(self.inner.explain()?)
    }

    /// Build the validated logical plan without compiling execution details.
    pub fn planned(&self) -> Result<PlannedQuery<E>, Error> {
        Ok(self.inner.planned()?)
    }

    /// Build the compiled executable plan for this query.
    pub fn plan(&self) -> Result<CompiledQuery<E>, Error> {
        Ok(self.inner.plan()?)
    }

    /// Return every declared field from each deleted row.
    #[must_use]
    pub fn returning_all(self) -> SessionDeleteReturningQuery<'a, E> {
        SessionDeleteReturningQuery {
            inner: self.inner,
            selection: DeleteReturningSelection::All,
        }
    }

    /// Return one explicit field list from each deleted row.
    #[must_use]
    pub fn returning<I, S>(self, fields: I) -> SessionDeleteReturningQuery<'a, E>
    where
        I: IntoIterator<Item = S>,
        S: AsRef<str>,
    {
        SessionDeleteReturningQuery {
            inner: self.inner,
            selection: DeleteReturningSelection::Fields(
                fields
                    .into_iter()
                    .map(|field| field.as_ref().to_string())
                    .collect(),
            ),
        }
    }

    /// Execute this delete and return the affected-row count.
    pub fn execute(&self) -> Result<u32, Error>
    where
        E: Entity,
    {
        Ok(self.inner.execute()?)
    }

    /// Return true when no rows were affected.
    pub fn is_empty(&self) -> Result<bool, Error>
    where
        E: Entity,
    {
        Ok(self.execute()? == 0)
    }

    /// Return the affected-row count.
    pub fn count(&self) -> Result<u32, Error>
    where
        E: Entity,
    {
        self.execute()
    }

    /// Require exactly one affected row.
    pub fn require_one(&self) -> Result<(), Error>
    where
        E: Entity,
    {
        Ok(self.inner.require_one()?)
    }

    /// Require at least one affected row.
    pub fn require_some(&self) -> Result<(), Error>
    where
        E: Entity,
    {
        Ok(self.inner.require_some()?)
    }
}

impl<E: Entity + SingletonEntity> SessionDeleteQuery<'_, E> {
    /// Delete the singleton entity.
    #[must_use]
    pub fn singleton(mut self) -> Self
    where
        E::Key: Default,
    {
        self.inner = self.inner.singleton();
        self
    }
}

impl<E: Entity> SessionDeleteReturningQuery<'_, E> {
    // ------------------------------------------------------------------
    // Primary-key access (query shaping)
    // ------------------------------------------------------------------

    impl_session_query_shape_methods!();

    // ------------------------------------------------------------------
    // Query refinement
    // ------------------------------------------------------------------

    /// Set the maximum number of rows this delete may affect.
    #[must_use]
    pub fn max_affected(mut self, limit: u32) -> Self {
        self.inner = self.inner.max_affected(limit);
        self
    }

    /// Return the stable plan hash for this query.
    pub fn plan_hash_hex(&self) -> Result<String, Error> {
        Ok(self.inner.plan_hash_hex()?)
    }

    /// Build one trace payload without executing the query.
    pub fn trace(&self) -> Result<QueryTracePlan, Error> {
        Ok(self.inner.trace()?)
    }

    /// Build logical explain metadata for the current query.
    pub fn explain(&self) -> Result<ExplainPlan, Error> {
        Ok(self.inner.explain()?)
    }

    /// Build the validated logical plan without compiling execution details.
    pub fn planned(&self) -> Result<PlannedQuery<E>, Error> {
        Ok(self.inner.planned()?)
    }

    /// Build the compiled executable plan for this query.
    pub fn plan(&self) -> Result<CompiledQuery<E>, Error> {
        Ok(self.inner.plan()?)
    }

    /// Execute this delete and return one row projection payload.
    pub fn execute(&self) -> Result<RowProjectionOutput, Error>
    where
        E: Entity,
    {
        // Phase 1: materialize deleted entities on the shared typed delete
        // executor boundary so fluent returning follows the same delete
        // semantics as typed query execution.
        let deleted = self.inner.execute_rows()?.entities();

        // Phase 2: narrow those deleted entities onto the explicit
        // row-returning projection contract requested by the fluent surface.
        DbSession::<E::Canister>::row_projection_output_from_entities::<E>(
            E::PATH.to_string(),
            deleted,
            self.selection.selected_fields(),
            |entity, slots| {
                self.inner
                    .project_entity_output_values(entity, slots)
                    .map_err(Error::from)
            },
        )
    }

    /// Return true when the returning payload contains no rows.
    pub fn is_empty(&self) -> Result<bool, Error>
    where
        E: Entity,
    {
        Ok(self.execute()?.row_count == 0)
    }

    /// Return the number of deleted rows included in the returning payload.
    pub fn count(&self) -> Result<u32, Error>
    where
        E: Entity,
    {
        Ok(self.execute()?.row_count)
    }
}

impl<E: Entity + SingletonEntity> SessionDeleteReturningQuery<'_, E> {
    /// Delete the singleton entity and return deleted rows.
    #[must_use]
    pub fn singleton(mut self) -> Self
    where
        E::Key: Default,
    {
        self.inner = self.inner.singleton();
        self
    }
}