Simplify ListMetadataReader trait with combined ListInfo query

Consolidate 6 separate trait methods into 2:
- `get_list_info()` returns pagination + state via single JOIN query
- `get_items()` returns entity metadata (renamed from `get()`)

This eliminates redundant database queries when accessing multiple
pagination fields (e.g., `has_more_pages()` previously made 2 queries).

Changes:
- Add `ListInfo` struct combining state, pagination fields
- Add `DbListHeaderWithState` for database layer
- Add `get_header_with_state()` JOIN query to repository
- Update `MetadataCollection` to use `list_info()` for all pagination access
- Add new tests for `get_list_info()` trait method

Author: oguzkocer

wp_mobile/src/service/metadata.rs

@@ -10,7 +10,7 @@ use wp_mobile_cache::{
     },
 };
 
-use crate::sync::{EntityMetadata, ListMetadataReader};
+use crate::sync::{EntityMetadata, ListInfo, ListMetadataReader};
 
 use super::WpServiceError;
 
@@ -313,43 +313,23 @@ impl MetadataService {
 /// This allows MetadataCollection to read list structure from the database
 /// through the same trait interface it uses for in-memory stores.
 impl ListMetadataReader for MetadataService {
-    fn get(&self, key: &str) -> Option<Vec<EntityMetadata>> {
-        self.get_metadata(key).ok().flatten()
-    }
-
-    fn get_sync_state(&self, key: &str) -> wp_mobile_cache::list_metadata::ListState {
-        // Delegate to our existing method, default to Idle on error
-        self.get_state(key).unwrap_or_default()
-    }
-
-    fn get_current_page(&self, key: &str) -> i64 {
-        self.get_pagination(key)
-            .ok()
-            .flatten()
-            .map(|p| p.current_page)
-            .unwrap_or(0)
-    }
-
-    fn get_total_pages(&self, key: &str) -> Option<i64> {
-        self.get_pagination(key)
-            .ok()
-            .flatten()
-            .and_then(|p| p.total_pages)
-    }
-
-    fn get_total_items(&self, key: &str) -> Option<i64> {
-        self.get_pagination(key)
+    fn get_list_info(&self, key: &str) -> Option<ListInfo> {
+        self.cache
+            .execute(|conn| self.repo.get_header_with_state(conn, &self.db_site, key))
             .ok()
             .flatten()
-            .and_then(|p| p.total_items)
+            .map(|db| ListInfo {
+                state: db.state,
+                error_message: db.error_message,
+                current_page: db.current_page,
+                total_pages: db.total_pages,
+                total_items: db.total_items,
+                per_page: db.per_page,
+            })
     }
 
-    fn get_per_page(&self, key: &str) -> i64 {
-        self.get_pagination(key)
-            .ok()
-            .flatten()
-            .map(|p| p.per_page)
-            .unwrap_or(20)
+    fn get_items(&self, key: &str) -> Option<Vec<EntityMetadata>> {
+        self.get_metadata(key).ok().flatten()
     }
 }
 
@@ -609,7 +589,7 @@ mod tests {
     }
 
     #[rstest]
-    fn test_list_metadata_reader_trait(test_ctx: TestContext) {
+    fn test_list_metadata_reader_get_items(test_ctx: TestContext) {
         let key = "edit:posts:publish";
         let metadata = vec![
             EntityMetadata::new(100, None, None, None),
@@ -620,16 +600,56 @@ mod tests {
 
         // Access via trait
         let reader: &dyn ListMetadataReader = &test_ctx.service;
-        let result = reader.get(key).unwrap();
+        let result = reader.get_items(key).unwrap();
 
         assert_eq!(result.len(), 2);
         assert_eq!(result[0].id, 100);
         assert_eq!(result[1].id, 200);
     }
 
     #[rstest]
-    fn test_list_metadata_reader_returns_none_for_non_existent(test_ctx: TestContext) {
+    fn test_list_metadata_reader_get_items_returns_none_for_non_existent(test_ctx: TestContext) {
+        let reader: &dyn ListMetadataReader = &test_ctx.service;
+        assert!(reader.get_items("nonexistent").is_none());
+    }
+
+    #[rstest]
+    fn test_list_metadata_reader_get_list_info(test_ctx: TestContext) {
+        let key = "edit:posts:publish";
+
+        // Initially no info
+        let reader: &dyn ListMetadataReader = &test_ctx.service;
+        assert!(reader.get_list_info(key).is_none());
+
+        // Create header via update_pagination (this creates the list metadata entry)
+        test_ctx
+            .service
+            .update_pagination(key, Some(5), Some(100), 1, 20)
+            .unwrap();
+
+        let info = reader.get_list_info(key).unwrap();
+        assert_eq!(info.current_page, 1);
+        assert_eq!(info.per_page, 20);
+        assert_eq!(info.total_pages, Some(5));
+        assert_eq!(info.total_items, Some(100));
+        assert_eq!(info.state, wp_mobile_cache::list_metadata::ListState::Idle);
+    }
+
+    #[rstest]
+    fn test_list_metadata_reader_get_list_info_with_state(test_ctx: TestContext) {
+        let key = "edit:posts:publish";
+        let metadata = vec![EntityMetadata::new(100, None, None, None)];
+        test_ctx.service.set_items(key, &metadata).unwrap();
+
+        // Start a refresh
+        test_ctx.service.begin_refresh(key).unwrap();
+
         let reader: &dyn ListMetadataReader = &test_ctx.service;
-        assert!(reader.get("nonexistent").is_none());
+        let info = reader.get_list_info(key).unwrap();
+
+        assert_eq!(
+            info.state,
+            wp_mobile_cache::list_metadata::ListState::FetchingFirstPage
+        );
     }
 }

wp_mobile/src/sync/list_metadata_reader.rs

@@ -1,38 +1,38 @@
 use super::EntityMetadata;
+use wp_mobile_cache::list_metadata::ListState;
+
+/// Combined list information: pagination + sync state.
+///
+/// Returned by a single JOIN query on `list_metadata` + `list_metadata_state` tables.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ListInfo {
+    /// Current sync state (Idle, FetchingFirstPage, FetchingNextPage, Error)
+    pub state: ListState,
+    /// Error message if state is Error
+    pub error_message: Option<String>,
+    /// Current page that has been loaded (0 = no pages loaded)
+    pub current_page: i64,
+    /// Total number of pages from API response
+    pub total_pages: Option<i64>,
+    /// Total number of items from API response
+    pub total_items: Option<i64>,
+    /// Items per page
+    pub per_page: i64,
+}
 
 /// Read-only access to list metadata.
 ///
 /// This trait allows components (like `MetadataCollection`) to read list structure
 /// without being able to modify it. Only the service layer should write metadata.
 pub trait ListMetadataReader: Send + Sync {
-    /// Get the metadata list for a filter key.
+    /// Get list info (pagination + state) in a single query.
     ///
     /// Returns `None` if no metadata has been stored for this key.
-    fn get(&self, key: &str) -> Option<Vec<EntityMetadata>>;
-
-    /// Get the current sync state for a list.
-    ///
-    /// Returns the current `ListState` (Idle, FetchingFirstPage, FetchingNextPage, Error).
-    /// Used by UI to show loading indicators or error states.
-    fn get_sync_state(&self, key: &str) -> wp_mobile_cache::list_metadata::ListState;
-
-    /// Get the current page number for a list.
-    ///
-    /// Returns 0 if no pages have been fetched yet.
-    fn get_current_page(&self, key: &str) -> i64;
-
-    /// Get the total number of pages for a list.
-    ///
-    /// Returns `None` if unknown (no fetch has completed yet).
-    fn get_total_pages(&self, key: &str) -> Option<i64>;
+    fn get_list_info(&self, key: &str) -> Option<ListInfo>;
 
-    /// Get the total number of items for a list.
+    /// Get the items for a list.
     ///
-    /// Returns `None` if unknown (no fetch has completed yet).
-    fn get_total_items(&self, key: &str) -> Option<i64>;
-
-    /// Get the items per page setting for a list.
-    ///
-    /// Returns the configured per_page value, or a default if not set.
-    fn get_per_page(&self, key: &str) -> i64;
+    /// Returns `None` if no metadata has been stored for this key.
+    /// Returns `Some(vec![])` if the list exists but has no items.
+    fn get_items(&self, key: &str) -> Option<Vec<EntityMetadata>>;
 }

wp_mobile/src/sync/metadata_collection.rs

@@ -4,7 +4,9 @@ use wp_mobile_cache::{DbTable, UpdateHook};
 
 use crate::collection::FetchError;
 
-use super::{CollectionItem, EntityStateReader, ListMetadataReader, MetadataFetcher, SyncResult};
+use super::{
+    CollectionItem, EntityStateReader, ListInfo, ListMetadataReader, MetadataFetcher, SyncResult,
+};
 
 /// Collection that uses metadata-first fetching strategy.
 ///
@@ -114,7 +116,7 @@ where
     /// the metadata with the current fetch state.
     pub fn items(&self) -> Vec<CollectionItem> {
         self.metadata_reader
-            .get(&self.kv_key)
+            .get_items(&self.kv_key)
             .unwrap_or_default()
             .into_iter()
             .map(|metadata| {
@@ -123,6 +125,13 @@ where
             .collect()
     }
 
+    /// Get the combined list info (pagination + sync state) in a single query.
+    ///
+    /// Returns `None` if no metadata has been stored for this key.
+    pub fn list_info(&self) -> Option<ListInfo> {
+        self.metadata_reader.get_list_info(&self.kv_key)
+    }
+
     /// Get the current sync state for this collection.
     ///
     /// Returns the current `ListState`:
@@ -133,7 +142,7 @@ where
     ///
     /// Use this to show loading indicators in the UI.
     pub fn sync_state(&self) -> wp_mobile_cache::list_metadata::ListState {
-        self.metadata_reader.get_sync_state(&self.kv_key)
+        self.list_info().map(|info| info.state).unwrap_or_default()
     }
 
     /// Check if a database update is relevant to this collection (either data or state).
@@ -269,28 +278,28 @@ where
 
     /// Check if there are more pages to load.
     pub fn has_more_pages(&self) -> bool {
-        let current_page = self.current_page();
-        let total_pages = self.total_pages();
-        total_pages
-            .map(|total| current_page < total)
-            .unwrap_or(true) // Unknown total = assume more pages
+        self.list_info()
+            .and_then(|info| info.total_pages.map(|total| info.current_page < total))
+            .unwrap_or(true) // Unknown total or no info = assume more pages
     }
 
     /// Get the current page number (0 = not loaded yet).
     pub fn current_page(&self) -> u32 {
-        self.metadata_reader.get_current_page(&self.kv_key) as u32
+        self.list_info()
+            .map(|info| info.current_page as u32)
+            .unwrap_or(0)
     }
 
     /// Get the total number of pages, if known.
     pub fn total_pages(&self) -> Option<u32> {
-        self.metadata_reader
-            .get_total_pages(&self.kv_key)
+        self.list_info()
+            .and_then(|info| info.total_pages)
             .map(|p| p as u32)
     }
 
     /// Get the total number of items, if known.
     pub fn total_items(&self) -> Option<i64> {
-        self.metadata_reader.get_total_items(&self.kv_key)
+        self.list_info().and_then(|info| info.total_items)
     }
 
     /// Fetch missing and stale items.

wp_mobile/src/sync/mod.rs

@@ -45,7 +45,7 @@ pub use collection_item::CollectionItem;
 pub use entity_metadata::EntityMetadata;
 pub use entity_state::EntityState;
 pub use entity_state_store::{EntityStateReader, EntityStateStore};
-pub use list_metadata_reader::ListMetadataReader;
+pub use list_metadata_reader::{ListInfo, ListMetadataReader};
 pub use metadata_collection::MetadataCollection;
 pub use metadata_fetch_result::MetadataFetchResult;
 pub use metadata_fetcher::MetadataFetcher;

wp_mobile_cache/src/db_types/db_list_metadata.rs

@@ -1,7 +1,9 @@
 use crate::{
     SqliteDbError,
     db_types::row_ext::{ColumnIndex, RowExt},
-    list_metadata::{DbListMetadata, DbListMetadataItem, DbListMetadataState, ListState},
+    list_metadata::{
+        DbListHeaderWithState, DbListMetadata, DbListMetadataItem, DbListMetadataState, ListState,
+    },
 };
 use rusqlite::Row;
 
@@ -119,3 +121,46 @@ impl DbListMetadataState {
         })
     }
 }
+
+/// Column indexes for the header + state JOIN query.
+///
+/// Query: SELECT m.total_pages, m.total_items, m.current_page, m.per_page, s.state, s.error_message
+///        FROM list_metadata m LEFT JOIN list_metadata_state s ON ...
+#[repr(usize)]
+#[derive(Debug, Clone, Copy)]
+pub enum ListHeaderWithStateColumn {
+    TotalPages = 0,
+    TotalItems = 1,
+    CurrentPage = 2,
+    PerPage = 3,
+    State = 4,
+    ErrorMessage = 5,
+}
+
+impl ColumnIndex for ListHeaderWithStateColumn {
+    fn as_index(&self) -> usize {
+        *self as usize
+    }
+}
+
+impl DbListHeaderWithState {
+    /// Construct from a JOIN query row.
+    ///
+    /// Expects columns in order: total_pages, total_items, current_page, per_page, state, error_message
+    pub fn from_row(row: &Row) -> Result<Self, SqliteDbError> {
+        use ListHeaderWithStateColumn as Col;
+
+        // state is nullable due to LEFT JOIN - default to "idle"
+        let state_str: Option<String> = row.get_column(Col::State)?;
+        let state = state_str.map(ListState::from).unwrap_or(ListState::Idle);
+
+        Ok(Self {
+            state,
+            error_message: row.get_column(Col::ErrorMessage)?,
+            current_page: row.get_column(Col::CurrentPage)?,
+            total_pages: row.get_column(Col::TotalPages)?,
+            total_items: row.get_column(Col::TotalItems)?,
+            per_page: row.get_column(Col::PerPage)?,
+        })
+    }
+}

wp_mobile_cache/src/list_metadata.rs

@@ -110,3 +110,22 @@ impl From<String> for ListState {
         ListState::from(s.as_str())
     }
 }
+
+/// Combined header + state from a JOIN query.
+///
+/// Contains pagination info from `list_metadata` and sync state from `list_metadata_state`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DbListHeaderWithState {
+    /// Current sync state (defaults to Idle if no state record exists)
+    pub state: ListState,
+    /// Error message if state is Error
+    pub error_message: Option<String>,
+    /// Current page that has been loaded (0 = no pages loaded)
+    pub current_page: i64,
+    /// Total number of pages from API response
+    pub total_pages: Option<i64>,
+    /// Total number of items from API response
+    pub total_items: Option<i64>,
+    /// Items per page
+    pub per_page: i64,
+}