feat(core): QuerySet support

Author: LeoBorai

src/domain/src/common/mod.rs

@@ -0,0 +1 @@
+pub mod query_set;

src/domain/src/common/query_set.rs

@@ -0,0 +1,122 @@
+use std::ops::Deref;
+
+#[derive(Debug, Default, Clone)]
+pub struct QuerySetMeta {
+    pub page: u32,
+    pub per_page: u32,
+    pub total_pages: u32,
+}
+
+/// Represents the result from a database query along with metadata
+#[derive(Debug, Default, Clone)]
+pub struct QuerySet<T: Clone> {
+    records: Vec<T>,
+    count: u32,
+    metadata: QuerySetMeta,
+}
+
+impl<T: Clone> Deref for QuerySet<T> {
+    type Target = Vec<T>;
+
+    fn deref(&self) -> &Self::Target {
+        &self.records
+    }
+}
+
+impl<T: Clone, E: Clone> QuerySet<Result<T, E>> {
+    pub fn transmute(self) -> Result<QuerySet<T>, E> {
+        let records = self.records.into_iter().collect::<Result<Vec<T>, E>>()?;
+        Ok(QuerySet {
+            records,
+            count: self.count,
+            metadata: self.metadata,
+        })
+    }
+}
+
+impl<T: Clone> QuerySet<T> {
+    /// Creates a new instance of `QuerySet` with it's records and `count`.
+    ///
+    /// The `count` value is used to determine the amount of records found
+    /// in the query, that may or may not be the total amount of records in
+    /// this `QuerySet` instance.
+    pub fn new(records: Vec<T>, metadata: QuerySetMeta) -> Self {
+        Self {
+            count: records.len() as u32,
+            records,
+            metadata,
+        }
+    }
+
+    /// Subset of records matched by the database query and also included as
+    /// part of the pagination process
+    #[inline]
+    pub fn records(&self) -> Vec<T> {
+        self.records.to_owned()
+    }
+
+    /// Total amount of records in the database matched by the query
+    #[inline]
+    pub fn count(&self) -> u32 {
+        self.count.to_owned()
+    }
+
+    /// Current page of the `QuerySet`
+    #[inline]
+    pub fn page(&self) -> u32 {
+        self.metadata.page
+    }
+
+    /// Amount of records per page
+    #[inline]
+    pub fn per_page(&self) -> u32 {
+        self.metadata.per_page
+    }
+
+    /// Total amount of pages available
+    #[inline]
+    pub fn total_pages(&self) -> u32 {
+        self.metadata.total_pages
+    }
+
+    /// Creates an empty `QuerySet`. This is useful for results where `T`
+    /// doesn't implement `Default`.
+    pub fn empty() -> Self {
+        Self {
+            records: Vec::new(),
+            count: 0,
+            metadata: QuerySetMeta::default(),
+        }
+    }
+
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.count == 0
+    }
+
+    /// Maps records stored internally
+    pub fn inner_map<B, F>(self, f: F) -> QuerySet<B>
+    where
+        B: Clone,
+        F: FnMut(T) -> B,
+    {
+        QuerySet {
+            records: self.records.into_iter().map(f).collect::<Vec<B>>(),
+            count: self.count,
+            metadata: self.metadata,
+        }
+    }
+
+    /// Maps records stored internally
+    pub fn inner_map_while<B, F>(self, f: F) -> QuerySet<B>
+    where
+        B: Clone,
+        F: FnMut(T) -> Option<B>,
+    {
+        QuerySet {
+            records: self.records.into_iter().map_while(f).collect::<Vec<B>>(),
+            count: self.count,
+            metadata: self.metadata,
+        }
+    }
+}

src/domain/src/lib.rs

@@ -1 +1,2 @@
+pub mod common;
 pub mod mtg;

src/domain/src/mtg/service.rs

@@ -4,6 +4,7 @@ use anyhow::Result;
 use bytes::Bytes;
 use uuid::Uuid;
 
+use crate::common::query_set::QuerySet;
 use crate::mtg::model::{Card, Deck};
 
 #[derive(Clone, Debug, Default)]
@@ -25,8 +26,8 @@ pub struct FindImageFilter {
 
 #[allow(async_fn_in_trait)]
 pub trait MtgDataAccessLayer: Clone + Send + Sync {
-    async fn find_cards(&self, filter: FindCardsFilter) -> Result<Vec<Card>>;
-    async fn find_decks(&self, filter: FindDecksFilter) -> Result<Vec<Deck>>;
+    async fn find_cards(&self, filter: FindCardsFilter) -> Result<QuerySet<Card>>;
+    async fn find_decks(&self, filter: FindDecksFilter) -> Result<QuerySet<Deck>>;
     async fn find_image(&self, filter: FindImageFilter) -> Result<Bytes>;
 }
 
@@ -39,12 +40,12 @@ impl<T: MtgDataAccessLayer> MtgService<T> {
         MtgService { repo }
     }
 
-    pub async fn get_cards(&self, filter: FindCardsFilter) -> Result<Vec<Card>> {
+    pub async fn get_cards(&self, filter: FindCardsFilter) -> Result<QuerySet<Card>> {
         let cards = self.repo.find_cards(filter).await?;
         Ok(cards)
     }
 
-    pub async fn get_decks(&self, filter: FindDecksFilter) -> Result<Vec<Deck>> {
+    pub async fn get_decks(&self, filter: FindDecksFilter) -> Result<QuerySet<Deck>> {
         let decks = self.repo.find_decks(filter).await?;
         Ok(decks)
     }

src/server/src/modules/mtg/repository.rs

@@ -7,25 +7,60 @@ use reqwest::{StatusCode, Url};
 use sqlx::sqlite::SqliteRow;
 use sqlx::{QueryBuilder, Row, SqlitePool};
 
+use deckmaster_domain::common::query_set::{QuerySet, QuerySetMeta};
 use deckmaster_domain::mtg::model::{Card, Deck};
 use deckmaster_domain::mtg::service::{FindCardsFilter, FindDecksFilter};
 use deckmaster_domain::mtg::service::{FindImageFilter, MtgDataAccessLayer};
 
+#[derive(Clone)]
+struct Counters {
+    cards: u32,
+    decks: u32,
+}
+
 #[derive(Clone)]
 pub struct MtgRepository {
     db: Arc<SqlitePool>,
     storage_url: Url,
+    counters: Counters,
 }
 
 impl MtgRepository {
     pub async fn new(db: Arc<SqlitePool>, storage_url: Url) -> Result<Self> {
-        Ok(MtgRepository { db, storage_url })
+        let mut repo = MtgRepository {
+            db,
+            storage_url,
+            counters: Counters { cards: 0, decks: 0 },
+        };
+
+        repo.count_tables().await?;
+
+        Ok(repo)
+    }
+
+    // The `mtg` table is immutable, so we can cache the count of rows
+    // to avoid running a COUNT(*) query every time we need it.
+    async fn count_tables(&mut self) -> Result<()> {
+        let mut conn = self.db.acquire().await?.detach();
+        let row: (i64,) = sqlx::query_as("SELECT COUNT(*) FROM cards")
+            .fetch_one(&mut conn)
+            .await?;
+        self.counters.cards = row.0 as u32;
+
+        let row: (i64,) = sqlx::query_as("SELECT COUNT(*) FROM decks")
+            .fetch_one(&mut conn)
+            .await?;
+        self.counters.decks = row.0 as u32;
+
+        Ok(())
     }
 }
 
 impl MtgDataAccessLayer for MtgRepository {
-    async fn find_cards(&self, filter: FindCardsFilter) -> Result<Vec<Card>> {
+    async fn find_cards(&self, filter: FindCardsFilter) -> Result<QuerySet<Card>> {
         let mut conn = self.db.acquire().await?.detach();
+        let page = filter.page.unwrap_or(1);
+        let offset = page * 20;
         let mut query = QueryBuilder::new(
             r#"SELECT
                 id,
@@ -47,7 +82,6 @@ impl MtgDataAccessLayer for MtgRepository {
         }
 
         query.push(" FROM cards");
-        let offset = (filter.page.unwrap_or(1).saturating_sub(1)) * 20;
         query.push(" LIMIT 20 OFFSET ");
         query.push_bind(offset as i64);
 
@@ -86,21 +120,33 @@ impl MtgDataAccessLayer for MtgRepository {
             });
         }
 
-        Ok(cards)
+        Ok(QuerySet::new(
+            cards,
+            QuerySetMeta {
+                page,
+                per_page: 20,
+                total_pages: self.counters.cards.div_ceil(20),
+            },
+        ))
     }
 
-    async fn find_decks(&self, _: FindDecksFilter) -> Result<Vec<Deck>> {
+    async fn find_decks(&self, filter: FindDecksFilter) -> Result<QuerySet<Deck>> {
         let mut conn = self.db.acquire().await?.detach();
-        let rows: Vec<SqliteRow> = sqlx::query(
+        let page = filter.page.unwrap_or(1);
+        let offset = page * 20;
+        let mut query = QueryBuilder::new(
             r#"SELECT
                 id,
                 name,
                 code,
                 release
             FROM decks"#,
-        )
-        .fetch_all(&mut conn)
-        .await?;
+        );
+
+        query.push(" LIMIT 20 OFFSET ");
+        query.push_bind(offset as i64);
+
+        let rows: Vec<SqliteRow> = query.build().fetch_all(&mut conn).await?;
         let mut decks = Vec::new();
 
         for row in rows {
@@ -119,7 +165,14 @@ impl MtgDataAccessLayer for MtgRepository {
             });
         }
 
-        Ok(decks)
+        Ok(QuerySet::new(
+            decks,
+            QuerySetMeta {
+                page,
+                per_page: 20,
+                total_pages: self.counters.decks.div_ceil(20),
+            },
+        ))
     }
 
     async fn find_image(&self, filter: FindImageFilter) -> Result<Bytes> {
@@ -128,7 +181,6 @@ impl MtgDataAccessLayer for MtgRepository {
                 "magic-the-gathering/images/cards/{}/{}.jpg",
                 deck_id, card_id
             ))?;
-            println!("{}", image_url);
             let response = reqwest::get(image_url).await?;
 
             if response.status() == StatusCode::OK {

src/server/src/router/api/v0/mod.rs

@@ -1,10 +1,11 @@
 mod mtg;
 
 use axum::Router;
-
 use serde::{Deserialize, Serialize};
 use utoipa::{IntoParams, OpenApi, ToSchema, schema};
 
+use deckmaster_domain::common::query_set::QuerySet;
+
 use crate::router::api::v0::mtg::{Card, Deck};
 
 #[derive(Debug, Serialize, Deserialize, ToSchema)]
@@ -20,32 +21,36 @@ pub struct ApiError {
 #[derive(Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "camelCase")]
 pub struct PaginatedResponse<T> {
-    pub total: u64,
     pub page: u32,
-    pub limit: u32,
+    pub total: u32,
     pub total_pages: u32,
     pub data: Vec<T>,
 }
 
+impl<T: Clone> From<QuerySet<T>> for PaginatedResponse<T> {
+    fn from(qs: QuerySet<T>) -> Self {
+        let data = qs.records().into_iter().collect();
+
+        PaginatedResponse {
+            total: qs.count(),
+            page: qs.page(),
+            total_pages: qs.total_pages(),
+            data,
+        }
+    }
+}
+
 #[derive(Default, Debug, Deserialize, IntoParams)]
 pub struct PaginationParams {
     /// Page number (starts from 1)
     #[param(example = 1, minimum = 1)]
     pub(self) page: Option<u32>,
-    /// Number of items per page
-    #[param(example = 20, minimum = 1, maximum = 100)]
-    pub(self) limit: Option<u32>,
 }
 
 impl PaginationParams {
     #[inline]
     pub fn page(&self) -> u32 {
-        self.page.unwrap_or(1).min(1)
-    }
-
-    #[inline]
-    pub fn limit(&self) -> u32 {
-        self.limit.unwrap_or(20).max(100)
+        self.page.unwrap_or(1)
     }
 }
 

src/server/src/router/api/v0/mtg/retrieve_cards.rs

@@ -24,8 +24,7 @@ pub async fn handler(
     Query(pagination): Query<PaginationParams>,
 ) -> Result<Json<PaginatedResponse<Card>>, StatusCode> {
     let page = pagination.page();
-    let limit = pagination.limit();
-    let cards: Vec<Card> = services
+    let cards_qs = services
         .mtg
         .get_cards(FindCardsFilter {
             deck_id: None,
@@ -35,19 +34,10 @@ pub async fn handler(
         .map_err(|err| {
             tracing::error!("Failed to retrieve cards: {:?}", err);
             StatusCode::INTERNAL_SERVER_ERROR
-        })?
-        .into_iter()
-        .map(Card::from)
-        .collect();
-    let total = cards.len() as u64;
-    let total_pages = (total as f64 / limit as f64).ceil() as u32;
-    let paginated_response = PaginatedResponse {
-        data: cards,
-        total,
-        page,
-        limit,
-        total_pages,
-    };
+        })?;
+
+    let cards_qs = cards_qs.inner_map(Card::from);
+    let paginated_response = PaginatedResponse::from(cards_qs);
 
     Ok(Json(paginated_response))
 }