Documetation for the executor module

src/executor/delete.rs

@@ -4,13 +4,16 @@ use crate::{
 use sea_query::DeleteStatement;
 use std::future::Future;
 
+/// Handles DELETE operations in a ActiveModel using [DeleteStatement]
 #[derive(Clone, Debug)]
 pub struct Deleter {
     query: DeleteStatement,
 }
 
+/// The result of a DELETE operation
 #[derive(Clone, Debug)]
 pub struct DeleteResult {
+    /// The number of rows affected by the DELETE operation
     pub rows_affected: u64,
 }
 
@@ -18,6 +21,7 @@ impl<'a, A: 'a> DeleteOne<A>
 where
     A: ActiveModelTrait,
 {
+    /// Execute a DELETE operation on one ActiveModel
     pub fn exec<C>(self, db: &'a C) -> impl Future<Output = Result<DeleteResult, DbErr>> + '_
     where
         C: ConnectionTrait<'a>,
@@ -31,6 +35,7 @@ impl<'a, E> DeleteMany<E>
 where
     E: EntityTrait,
 {
+    /// Execute a DELETE operation on many ActiveModels
     pub fn exec<C>(self, db: &'a C) -> impl Future<Output = Result<DeleteResult, DbErr>> + '_
     where
         C: ConnectionTrait<'a>,
@@ -41,10 +46,12 @@ where
 }
 
 impl Deleter {
+    /// Instantiate a new [Deleter] by passing it a [DeleteStatement]
     pub fn new(query: DeleteStatement) -> Self {
         Self { query }
     }
 
+    /// Execute a DELETE operation
     pub fn exec<'a, C>(self, db: &'a C) -> impl Future<Output = Result<DeleteResult, DbErr>> + '_
     where
         C: ConnectionTrait<'a>,

src/executor/execute.rs

@@ -1,16 +1,24 @@
+/// Defines the result of executing an operation
 #[derive(Debug)]
 pub struct ExecResult {
+    /// The type of result from the execution depending on the feature flag enabled
+    /// to choose a database backend
     pub(crate) result: ExecResultHolder,
 }
 
+/// Holds a result depending on the database backend chosen by the feature flag
 #[derive(Debug)]
 pub(crate) enum ExecResultHolder {
+    /// Holds the result of executing an operation on a MySQL database
     #[cfg(feature = "sqlx-mysql")]
     SqlxMySql(sqlx::mysql::MySqlQueryResult),
+    /// Holds the result of executing an operation on a PostgreSQL database
     #[cfg(feature = "sqlx-postgres")]
     SqlxPostgres(sqlx::postgres::PgQueryResult),
+    /// Holds the result of executing an operation on a SQLite database
     #[cfg(feature = "sqlx-sqlite")]
     SqlxSqlite(sqlx::sqlite::SqliteQueryResult),
+    /// Holds the result of executing an operation on the Mock database
     #[cfg(feature = "mock")]
     Mock(crate::MockExecResult),
 }
@@ -18,6 +26,7 @@ pub(crate) enum ExecResultHolder {
 // ExecResult //
 
 impl ExecResult {
+    /// Get the last id after `AUTOINCREMENT` is done on the primary key
     pub fn last_insert_id(&self) -> u64 {
         match &self.result {
             #[cfg(feature = "sqlx-mysql")]
@@ -40,6 +49,7 @@ impl ExecResult {
         }
     }
 
+    /// Get the number of rows affedted by the operation
     pub fn rows_affected(&self) -> u64 {
         match &self.result {
             #[cfg(feature = "sqlx-mysql")]

src/executor/insert.rs

@@ -5,6 +5,7 @@ use crate::{
 use sea_query::{FromValueTuple, InsertStatement, ValueTuple};
 use std::{future::Future, marker::PhantomData};
 
+/// Defines a structure to perform INSERT operations in an ActiveModel
 #[derive(Debug)]
 pub struct Inserter<A>
 where
@@ -15,11 +16,13 @@ where
     model: PhantomData<A>,
 }
 
+/// The result of an INSERT operation on an ActiveModel
 #[derive(Debug)]
 pub struct InsertResult<A>
 where
     A: ActiveModelTrait,
 {
+    /// The id performed when AUTOINCREMENT was performed on the PrimaryKey
     pub last_insert_id: <<<A as ActiveModelTrait>::Entity as EntityTrait>::PrimaryKey as PrimaryKeyTrait>::ValueType,
 }
 
@@ -27,6 +30,7 @@ impl<A> Insert<A>
 where
     A: ActiveModelTrait,
 {
+    /// Execute an insert operation
     #[allow(unused_mut)]
     pub fn exec<'a, C>(self, db: &'a C) -> impl Future<Output = Result<InsertResult<A>, DbErr>> + '_
     where
@@ -53,6 +57,7 @@ impl<A> Inserter<A>
 where
     A: ActiveModelTrait,
 {
+    /// Instantiate a new insert operation
     pub fn new(primary_key: Option<ValueTuple>, query: InsertStatement) -> Self {
         Self {
             primary_key,
@@ -61,6 +66,7 @@ where
         }
     }
 
+    /// Execute an insert operation
     pub fn exec<'a, C>(self, db: &'a C) -> impl Future<Output = Result<InsertResult<A>, DbErr>> + '_
     where
         C: ConnectionTrait<'a>,

src/executor/paginator.rs

@@ -4,8 +4,10 @@ use futures::Stream;
 use sea_query::{Alias, Expr, SelectStatement};
 use std::{marker::PhantomData, pin::Pin};
 
+/// Pin a Model so that stream operations can be performed on the model
 pub type PinBoxStream<'db, Item> = Pin<Box<dyn Stream<Item = Item> + 'db>>;
 
+/// Defined a structure to handle pagination of a result from a query operation on a Model
 #[derive(Clone, Debug)]
 pub struct Paginator<'db, C, S>
 where

src/executor/query.rs

@@ -3,6 +3,7 @@ use crate::debug_print;
 use crate::{DbErr, SelectGetableValue, SelectorRaw, Statement};
 use std::fmt;
 
+/// Defines the result of a query operation on a Model
 #[derive(Debug)]
 pub struct QueryResult {
     pub(crate) row: QueryResultRow,
@@ -19,13 +20,18 @@ pub(crate) enum QueryResultRow {
     Mock(crate::MockRow),
 }
 
+/// Constrain any type trying to get a Row in a database
 pub trait TryGetable: Sized {
+    /// Ensure the type implements this method
     fn try_get(res: &QueryResult, pre: &str, col: &str) -> Result<Self, TryGetError>;
 }
 
+/// An error from trying to get a row from a Model
 #[derive(Debug)]
 pub enum TryGetError {
+    /// A database error was encountered as defined in [crate::DbErr]
     DbErr(DbErr),
+    /// A null value was encountered
     Null,
 }
 
@@ -41,6 +47,7 @@ impl From<TryGetError> for DbErr {
 // QueryResult //
 
 impl QueryResult {
+    /// Get a Row from a Column
     pub fn try_get<T>(&self, pre: &str, col: &str) -> Result<T, DbErr>
     where
         T: TryGetable,
@@ -48,6 +55,7 @@ impl QueryResult {
         Ok(T::try_get(self, pre, col)?)
     }
 
+    /// Perform query operations on multiple Columns
     pub fn try_get_many<T>(&self, pre: &str, cols: &[String]) -> Result<T, DbErr>
     where
         T: TryGetableMany,
@@ -306,7 +314,9 @@ try_getable_all!(uuid::Uuid);
 
 // TryGetableMany //
 
+/// Perform a query on multiple columns
 pub trait TryGetableMany: Sized {
+    /// THe method to perform a query on multiple columns
     fn try_get_many(res: &QueryResult, pre: &str, cols: &[String]) -> Result<Self, TryGetError>;
 
     /// ```
@@ -453,8 +463,9 @@ fn try_get_many_with_slice_len_of(len: usize, cols: &[String]) -> Result<(), Try
 }
 
 // TryFromU64 //
-
+/// Try to convert a type to a u64
 pub trait TryFromU64: Sized {
+    /// The method to convert the type to a u64
     fn try_from_u64(n: u64) -> Result<Self, DbErr>;
 }
 

src/executor/select.rs

@@ -11,6 +11,7 @@ use std::pin::Pin;
 #[cfg(feature = "with-json")]
 use crate::JsonValue;
 
+/// Defines a type to do `SELECT` operations though a [SelectStatement] on a Model
 #[derive(Clone, Debug)]
 pub struct Selector<S>
 where
@@ -20,6 +21,7 @@ where
     selector: S,
 }
 
+/// Performs a raw `SELECT` operation on a model
 #[derive(Clone, Debug)]
 pub struct SelectorRaw<S>
 where
@@ -29,12 +31,16 @@ where
     selector: S,
 }
 
+/// Used to enforce constraints on any type that wants to perform SELECT queries
 pub trait SelectorTrait {
+    #[allow(missing_docs)]
     type Item: Sized;
 
+    /// The method to perform a query on a Model
     fn from_raw_query_result(res: QueryResult) -> Result<Self::Item, DbErr>;
 }
 
+/// Perform an operation on an entity that can yield a Value
 #[derive(Debug)]
 pub struct SelectGetableValue<T, C>
 where
@@ -45,6 +51,7 @@ where
     model: PhantomData<T>,
 }
 
+/// Defines a type to get a Model
 #[derive(Debug)]
 pub struct SelectModel<M>
 where
@@ -53,6 +60,7 @@ where
     model: PhantomData<M>,
 }
 
+/// Defines a type to get two Modelss
 #[derive(Clone, Debug)]
 pub struct SelectTwoModel<M, N>
 where
@@ -105,6 +113,7 @@ impl<E> Select<E>
 where
     E: EntityTrait,
 {
+    /// Perform a Select operation on a Model using a [Statement]
     #[allow(clippy::wrong_self_convention)]
     pub fn from_raw_sql(self, stmt: Statement) -> SelectorRaw<SelectModel<E::Model>> {
         SelectorRaw {
@@ -113,6 +122,7 @@ where
         }
     }
 
+    /// Return a [Selector] from `Self` that wraps a [SelectModel]
     pub fn into_model<M>(self) -> Selector<SelectModel<M>>
     where
         M: FromQueryResult,
@@ -123,6 +133,7 @@ where
         }
     }
 
+    /// Get a selectable Model as a [JsonValue] for SQL JSON operations
     #[cfg(feature = "with-json")]
     pub fn into_json(self) -> Selector<SelectModel<JsonValue>> {
         Selector {
@@ -239,6 +250,7 @@ where
         Selector::<SelectGetableValue<T, C>>::with_columns(self.query)
     }
 
+    /// Get one Model from a SELECT operation
     pub async fn one<'a, C>(self, db: &C) -> Result<Option<E::Model>, DbErr>
     where
         C: ConnectionTrait<'a>,
@@ -246,6 +258,7 @@ where
         self.into_model().one(db).await
     }
 
+    /// Get all the Models from a SELECT operation
     pub async fn all<'a, C>(self, db: &C) -> Result<Vec<E::Model>, DbErr>
     where
         C: ConnectionTrait<'a>,
@@ -253,6 +266,7 @@ where
         self.into_model().all(db).await
     }
 
+    /// Stream the results of a SELECT operation on a Model
     pub async fn stream<'a: 'b, 'b, C>(
         self,
         db: &'a C,
@@ -263,6 +277,7 @@ where
         self.into_model().stream(db).await
     }
 
+    /// Paginate the results of a SELECT operation on a Model
     pub fn paginate<'a, C>(
         self,
         db: &'a C,
@@ -274,6 +289,7 @@ where
         self.into_model().paginate(db, page_size)
     }
 
+    /// Perform a `COUNT` operation on a items on a Model using pagination
     pub async fn count<'a, C>(self, db: &'a C) -> Result<usize, DbErr>
     where
         C: ConnectionTrait<'a>,
@@ -287,6 +303,7 @@ where
     E: EntityTrait,
     F: EntityTrait,
 {
+    /// Perform a conversion into a [SelectTwoModel]
     pub fn into_model<M, N>(self) -> Selector<SelectTwoModel<M, N>>
     where
         M: FromQueryResult,
@@ -298,6 +315,7 @@ where
         }
     }
 
+    /// Convert the Models into JsonValue
     #[cfg(feature = "with-json")]
     pub fn into_json(self) -> Selector<SelectTwoModel<JsonValue, JsonValue>> {
         Selector {
@@ -306,6 +324,7 @@ where
         }
     }
 
+    /// Get one Model from a Select operation
     pub async fn one<'a, C>(self, db: &C) -> Result<Option<(E::Model, Option<F::Model>)>, DbErr>
     where
         C: ConnectionTrait<'a>,
@@ -313,6 +332,7 @@ where
         self.into_model().one(db).await
     }
 
+    /// Get all Models from a Select operation
     pub async fn all<'a, C>(self, db: &C) -> Result<Vec<(E::Model, Option<F::Model>)>, DbErr>
     where
         C: ConnectionTrait<'a>,
@@ -320,6 +340,7 @@ where
         self.into_model().all(db).await
     }
 
+    /// Stream the results of a Select operation on a Model
     pub async fn stream<'a: 'b, 'b, C>(
         self,
         db: &'a C,
@@ -330,6 +351,7 @@ where
         self.into_model().stream(db).await
     }
 
+    /// Paginate the results of a select operation on two models
     pub fn paginate<'a, C>(
         self,
         db: &'a C,
@@ -341,6 +363,7 @@ where
         self.into_model().paginate(db, page_size)
     }
 
+    /// Perform a count on the paginated results
     pub async fn count<'a, C>(self, db: &'a C) -> Result<usize, DbErr>
     where
         C: ConnectionTrait<'a>,
@@ -354,6 +377,7 @@ where
     E: EntityTrait,
     F: EntityTrait,
 {
+    /// Performs a conversion to [Selector]
     fn into_model<M, N>(self) -> Selector<SelectTwoModel<M, N>>
     where
         M: FromQueryResult,
@@ -365,6 +389,7 @@ where
         }
     }
 
+    /// Convert the results to JSON
     #[cfg(feature = "with-json")]
     pub fn into_json(self) -> Selector<SelectTwoModel<JsonValue, JsonValue>> {
         Selector {
@@ -373,6 +398,7 @@ where
         }
     }
 
+    /// Select one Model
     pub async fn one<'a, C>(self, db: &C) -> Result<Option<(E::Model, Option<F::Model>)>, DbErr>
     where
         C: ConnectionTrait<'a>,
@@ -380,6 +406,7 @@ where
         self.into_model().one(db).await
     }
 
+    /// Stream the result of the operation
     pub async fn stream<'a: 'b, 'b, C>(
         self,
         db: &'a C,
@@ -390,6 +417,7 @@ where
         self.into_model().stream(db).await
     }
 
+    /// Get all the Models from the select operation
     pub async fn all<'a, C>(self, db: &C) -> Result<Vec<(E::Model, Vec<F::Model>)>, DbErr>
     where
         C: ConnectionTrait<'a>,
@@ -428,6 +456,7 @@ where
         }
     }
 
+    /// Get a Model from a Select operation
     pub async fn one<'a, C>(mut self, db: &C) -> Result<Option<S::Item>, DbErr>
     where
         C: ConnectionTrait<'a>,
@@ -441,6 +470,7 @@ where
         }
     }
 
+    /// Get all results from a Select operation
     pub async fn all<'a, C>(self, db: &C) -> Result<Vec<S::Item>, DbErr>
     where
         C: ConnectionTrait<'a>,
@@ -454,6 +484,7 @@ where
         Ok(models)
     }
 
+    /// Stream the results of the operation
     pub async fn stream<'a: 'b, 'b, C>(
         self,
         db: &'a C,
@@ -469,6 +500,7 @@ where
         })))
     }
 
+    /// Paginate the result of a select operation on a Model
     pub fn paginate<'a, C>(self, db: &'a C, page_size: usize) -> Paginator<'a, C, S>
     where
         C: ConnectionTrait<'a>,
@@ -499,7 +531,7 @@ where
         }
     }
 
-    /// Create `SelectorRaw` from Statment and columns. Executing this `SelectorRaw` will
+    /// Create `SelectorRaw` from Statement and columns. Executing this `SelectorRaw` will
     /// return a type `T` which implement `TryGetableMany`.
     pub fn with_columns<T, C>(stmt: Statement) -> SelectorRaw<SelectGetableValue<T, C>>
     where

src/executor/update.rs

@@ -4,14 +4,17 @@ use crate::{
 use sea_query::UpdateStatement;
 use std::future::Future;
 
+/// Defines an update operation
 #[derive(Clone, Debug)]
 pub struct Updater {
     query: UpdateStatement,
     check_record_exists: bool,
 }
 
+/// The result of an update operation on an ActiveModel
 #[derive(Clone, Debug, PartialEq)]
 pub struct UpdateResult {
+    /// The rows affected by the update operation
     pub rows_affected: u64,
 }
 
@@ -19,6 +22,7 @@ impl<'a, A: 'a> UpdateOne<A>
 where
     A: ActiveModelTrait,
 {
+    /// Execute an update operation on an ActiveModel
     pub async fn exec<'b, C>(self, db: &'b C) -> Result<A, DbErr>
     where
         C: ConnectionTrait<'b>,
@@ -32,6 +36,7 @@ impl<'a, E> UpdateMany<E>
 where
     E: EntityTrait,
 {
+    /// Execute an update operation on multiple ActiveModels
     pub fn exec<C>(self, db: &'a C) -> impl Future<Output = Result<UpdateResult, DbErr>> + '_
     where
         C: ConnectionTrait<'a>,
@@ -42,6 +47,7 @@ where
 }
 
 impl Updater {
+    /// Instantiate an update using an [UpdateStatement]
     pub fn new(query: UpdateStatement) -> Self {
         Self {
             query,
@@ -49,11 +55,13 @@ impl Updater {
         }
     }
 
+    /// Check if a record exists on the ActiveModel to perform the update operation on
     pub fn check_record_exists(mut self) -> Self {
         self.check_record_exists = true;
         self
     }
 
+    /// Execute an update operation
     pub fn exec<'a, C>(self, db: &'a C) -> impl Future<Output = Result<UpdateResult, DbErr>> + '_
     where
         C: ConnectionTrait<'a>,