diff --git a/src/executor/delete.rs b/src/executor/delete.rs index c4a8c7de..7577b976 100644 --- a/src/executor/delete.rs +++ b/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 where A: ActiveModelTrait, { + /// Execute a DELETE operation on one ActiveModel pub fn exec(self, db: &'a C) -> impl Future> + '_ where C: ConnectionTrait<'a>, @@ -31,6 +35,7 @@ impl<'a, E> DeleteMany where E: EntityTrait, { + /// Execute a DELETE operation on many ActiveModels pub fn exec(self, db: &'a C) -> impl Future> + '_ 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> + '_ where C: ConnectionTrait<'a>, diff --git a/src/executor/execute.rs b/src/executor/execute.rs index 46ba2d69..f3168180 100644 --- a/src/executor/execute.rs +++ b/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")] diff --git a/src/executor/insert.rs b/src/executor/insert.rs index 9e186ccd..64b6c145 100644 --- a/src/executor/insert.rs +++ b/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 where @@ -15,11 +16,13 @@ where model: PhantomData, } +/// The result of an INSERT operation on an ActiveModel #[derive(Debug)] pub struct InsertResult where A: ActiveModelTrait, { + /// The id performed when AUTOINCREMENT was performed on the PrimaryKey pub last_insert_id: <<::Entity as EntityTrait>::PrimaryKey as PrimaryKeyTrait>::ValueType, } @@ -27,6 +30,7 @@ impl Insert where A: ActiveModelTrait, { + /// Execute an insert operation #[allow(unused_mut)] pub fn exec<'a, C>(self, db: &'a C) -> impl Future, DbErr>> + '_ where @@ -53,6 +57,7 @@ impl Inserter where A: ActiveModelTrait, { + /// Instantiate a new insert operation pub fn new(primary_key: Option, 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, DbErr>> + '_ where C: ConnectionTrait<'a>, diff --git a/src/executor/paginator.rs b/src/executor/paginator.rs index 28f8574b..fd8e822c 100644 --- a/src/executor/paginator.rs +++ b/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 + '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 diff --git a/src/executor/query.rs b/src/executor/query.rs index a164e911..96455945 100644 --- a/src/executor/query.rs +++ b/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; } +/// 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 for DbErr { // QueryResult // impl QueryResult { + /// Get a Row from a Column pub fn try_get(&self, pre: &str, col: &str) -> Result 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(&self, pre: &str, cols: &[String]) -> Result 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; /// ``` @@ -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; } diff --git a/src/executor/select.rs b/src/executor/select.rs index 78786b76..5acdae02 100644 --- a/src/executor/select.rs +++ b/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 where @@ -20,6 +21,7 @@ where selector: S, } +/// Performs a raw `SELECT` operation on a model #[derive(Clone, Debug)] pub struct SelectorRaw 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; } +/// Perform an operation on an entity that can yield a Value #[derive(Debug)] pub struct SelectGetableValue where @@ -45,6 +51,7 @@ where model: PhantomData, } +/// Defines a type to get a Model #[derive(Debug)] pub struct SelectModel where @@ -53,6 +60,7 @@ where model: PhantomData, } +/// Defines a type to get two Modelss #[derive(Clone, Debug)] pub struct SelectTwoModel where @@ -105,6 +113,7 @@ impl Select 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> { SelectorRaw { @@ -113,6 +122,7 @@ where } } + /// Return a [Selector] from `Self` that wraps a [SelectModel] pub fn into_model(self) -> Selector> 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> { Selector { @@ -239,6 +250,7 @@ where Selector::>::with_columns(self.query) } + /// Get one Model from a SELECT operation pub async fn one<'a, C>(self, db: &C) -> Result, 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, 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 where C: ConnectionTrait<'a>, @@ -287,6 +303,7 @@ where E: EntityTrait, F: EntityTrait, { + /// Perform a conversion into a [SelectTwoModel] pub fn into_model(self) -> Selector> where M: FromQueryResult, @@ -298,6 +315,7 @@ where } } + /// Convert the Models into JsonValue #[cfg(feature = "with-json")] pub fn into_json(self) -> Selector> { Selector { @@ -306,6 +324,7 @@ where } } + /// Get one Model from a Select operation pub async fn one<'a, C>(self, db: &C) -> Result)>, 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)>, 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 where C: ConnectionTrait<'a>, @@ -354,6 +377,7 @@ where E: EntityTrait, F: EntityTrait, { + /// Performs a conversion to [Selector] fn into_model(self) -> Selector> where M: FromQueryResult, @@ -365,6 +389,7 @@ where } } + /// Convert the results to JSON #[cfg(feature = "with-json")] pub fn into_json(self) -> Selector> { Selector { @@ -373,6 +398,7 @@ where } } + /// Select one Model pub async fn one<'a, C>(self, db: &C) -> Result)>, 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)>, 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, 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, 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(stmt: Statement) -> SelectorRaw> where diff --git a/src/executor/update.rs b/src/executor/update.rs index c228730b..402f29ac 100644 --- a/src/executor/update.rs +++ b/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 where A: ActiveModelTrait, { + /// Execute an update operation on an ActiveModel pub async fn exec<'b, C>(self, db: &'b C) -> Result where C: ConnectionTrait<'b>, @@ -32,6 +36,7 @@ impl<'a, E> UpdateMany where E: EntityTrait, { + /// Execute an update operation on multiple ActiveModels pub fn exec(self, db: &'a C) -> impl Future> + '_ 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> + '_ where C: ConnectionTrait<'a>,