Metadata Collection Prototype

native/kotlin/api/kotlin/src/integrationTest/kotlin/WordPressApiCacheTest.kt

@@ -10,6 +10,6 @@ class WordPressApiCacheTest {
 
     @Test
     fun testThatMigrationsWork() = runTest {
-        assertEquals(6, WordPressApiCache().performMigrations())
+        assertEquals(7, WordPressApiCache().performMigrations())
     }
 }

native/kotlin/api/kotlin/src/main/kotlin/rs/wordpress/cache/kotlin/DatabaseChangeNotifier.kt

@@ -15,13 +15,14 @@ import java.util.concurrent.CopyOnWriteArraySet
  * the observable's is_relevant_update closure handles all the matching logic in Rust.
  *
  * **Lifecycle Management**: Observables are registered when created and should be closed
- * when no longer needed. [ObservableEntity] and [ObservableCollection] implement [AutoCloseable]
- * and will automatically unregister when closed. Use `.use { }` blocks for automatic cleanup,
- * or call `.close()` manually.
+ * when no longer needed. [ObservableEntity], [ObservableCollection], and [ObservableMetadataCollection]
+ * implement [AutoCloseable] and will automatically unregister when closed. Use `.use { }` blocks
+ * for automatic cleanup, or call `.close()` manually.
  */
 object DatabaseChangeNotifier : DatabaseDelegate {
     private val observableEntities = CopyOnWriteArraySet<ObservableEntity<*>>()
     private val observableCollections = CopyOnWriteArraySet<ObservableCollection<*>>()
+    private val observableMetadataCollections = CopyOnWriteArraySet<ObservableMetadataCollection>()
 
     /**
      * Register an ObservableEntity to receive database change notifications.
@@ -57,14 +58,32 @@ object DatabaseChangeNotifier : DatabaseDelegate {
         observableCollections.remove(collection)
     }
 
+    /**
+     * Register an ObservableMetadataCollection to receive database change notifications.
+     *
+     * The collection will be notified of all database updates and can decide internally
+     * whether the update is relevant to it.
+     */
+    fun register(collection: ObservableMetadataCollection) {
+        observableMetadataCollections.add(collection)
+    }
+
+    /**
+     * Unregister an ObservableMetadataCollection from receiving database change notifications.
+     */
+    fun unregister(collection: ObservableMetadataCollection) {
+        observableMetadataCollections.remove(collection)
+    }
+
     /**
      * Called by WpApiCache when a database update occurs.
      *
-     * Notifies all registered observables (entities and collections), which will check if the update
-     * is relevant to them using their is_relevant_update() methods.
+     * Notifies all registered observables (entities, collections, and metadata collections),
+     * which will check if the update is relevant to them using their is_relevant_update() methods.
      */
     override fun didUpdate(updateHook: UpdateHook) {
         observableEntities.forEach { it.notifyIfRelevant(updateHook) }
         observableCollections.forEach { it.notifyIfRelevant(updateHook) }
+        observableMetadataCollections.forEach { it.notifyIfRelevant(updateHook) }
     }
 }

native/kotlin/api/kotlin/src/main/kotlin/rs/wordpress/cache/kotlin/ObservableMetadataCollection.kt

@@ -0,0 +1,242 @@
+package rs.wordpress.cache.kotlin
+
+import uniffi.wp_mobile.ListInfo
+import uniffi.wp_mobile.PostMetadataCollectionItem
+import uniffi.wp_mobile.PostMetadataCollectionWithEditContext
+import uniffi.wp_mobile.SyncResult
+import uniffi.wp_mobile_cache.ListState
+import uniffi.wp_mobile_cache.UpdateHook
+import java.util.concurrent.CopyOnWriteArrayList
+
+/**
+ * Check if there are more pages to load.
+ *
+ * Returns `true` if:
+ * - Total pages is unknown (assume more)
+ * - Current page is less than total pages
+ */
+val ListInfo.hasMorePages: Boolean
+    get() = totalPages?.let { currentPage < it } ?: true
+
+/**
+ * Check if a sync operation is in progress.
+ */
+val ListInfo.isSyncing: Boolean
+    get() = state == ListState.FETCHING_FIRST_PAGE || state == ListState.FETCHING_NEXT_PAGE
+
+/**
+ * Create an observable metadata collection that notifies observers when data changes.
+ *
+ * This helper automatically registers the collection with [DatabaseChangeNotifier].
+ * Use service extension functions (e.g., `getObservablePostMetadataCollectionWithEditContext`)
+ * instead of calling this directly.
+ *
+ * **Lifecycle Management**: Collections implement [AutoCloseable] and should be closed when
+ * no longer needed to prevent memory accumulation. In ViewModels, call `.close()` in
+ * `onCleared()`. For short-lived usage, use `.use { }` blocks. For app-lifecycle-scoped
+ * observables, explicit cleanup may not be necessary.
+ *
+ * Example (ViewModel):
+ * ```
+ * class MyViewModel : ViewModel() {
+ *     private val observableCollection = postService.getObservablePostMetadataCollectionWithEditContext(filter)
+ *
+ *     init {
+ *         observableCollection.addObserver { /* update UI */ }
+ *         viewModelScope.launch { observableCollection.refresh() }
+ *     }
+ *
+ *     override fun onCleared() {
+ *         super.onCleared()
+ *         observableCollection.close()
+ *     }
+ * }
+ * ```
+ */
+fun createObservableMetadataCollection(
+    collection: PostMetadataCollectionWithEditContext
+): ObservableMetadataCollection = ObservableMetadataCollection(
+    collection = collection
+).also {
+    DatabaseChangeNotifier.register(it)
+}
+
+/**
+ * Observable wrapper around a metadata collection that notifies observers when changes occur.
+ *
+ * This is similar to [ObservableCollection] but designed for the "metadata-first" sync strategy:
+ * - Items include fetch state (Missing, Fetching, Cached, Stale, Failed)
+ * - Sync operations (refresh, loadNextPage) are exposed for explicit control
+ * - Data is optional per item (present only when Cached)
+ *
+ * The metadata collection uses a two-phase sync:
+ * 1. Fetch lightweight metadata (id + modified_gmt) to define list structure
+ * 2. Selectively fetch full data for missing or stale items
+ *
+ * This allows showing cached items immediately while loading only what's needed.
+ *
+ * Create instances using [createObservableMetadataCollection] or service extension functions
+ * rather than the constructor directly.
+ *
+ * Implements [AutoCloseable] to support cleanup. Call [close] when done (typically in
+ * ViewModel.onCleared()) to unregister from [DatabaseChangeNotifier].
+ */
+@Suppress("TooManyFunctions") // Observer pattern requires multiple add/remove/notify methods
+class ObservableMetadataCollection(
+    private val collection: PostMetadataCollectionWithEditContext
+) : AutoCloseable {
+    private val dataObservers = CopyOnWriteArrayList<() -> Unit>()
+    private val listInfoObservers = CopyOnWriteArrayList<() -> Unit>()
+
+    /**
+     * Add an observer for data changes (list contents changed).
+     *
+     * Data observers are notified when:
+     * - Entity data changes (posts updated, deleted, etc.)
+     * - List metadata items change (list structure changed)
+     *
+     * Use this for refreshing list contents in the UI.
+     */
+    fun addDataObserver(observer: () -> Unit) {
+        dataObservers.add(observer)
+    }
+
+    /**
+     * Add an observer for list info changes (pagination or sync state changed).
+     *
+     * ListInfo observers are notified when:
+     * - Pagination info changes (current page, total pages updated after fetch)
+     * - Sync state changes (Idle -> FetchingFirstPage, etc.)
+     *
+     * Use this for updating pagination display and loading indicators in the UI.
+     */
+    fun addListInfoObserver(observer: () -> Unit) {
+        listInfoObservers.add(observer)
+    }
+
+    /**
+     * Add an observer for both data and list info changes.
+     *
+     * This is a convenience method that registers the observer for both
+     * data and list info updates. Use this when you want to refresh the entire
+     * UI on any change.
+     */
+    fun addObserver(observer: () -> Unit) {
+        dataObservers.add(observer)
+        listInfoObservers.add(observer)
+    }
+
+    /**
+     * Remove a data observer.
+     */
+    fun removeDataObserver(observer: () -> Unit) {
+        dataObservers.remove(observer)
+    }
+
+    /**
+     * Remove a list info observer.
+     */
+    fun removeListInfoObserver(observer: () -> Unit) {
+        listInfoObservers.remove(observer)
+    }
+
+    /**
+     * Remove an observer from both data and list info lists.
+     */
+    fun removeObserver(observer: () -> Unit) {
+        dataObservers.remove(observer)
+        listInfoObservers.remove(observer)
+    }
+
+    /**
+     * Load all items with their current states and data.
+     *
+     * Returns items in list order with type-safe state representation.
+     * Each item's `state` is a [PostItemState] sealed class that encodes both
+     * sync status and data availability:
+     *
+     * - [PostItemState.Cached]: Fresh data, no fetch needed
+     * - [PostItemState.Stale]: Outdated data, could benefit from refresh
+     * - [PostItemState.FetchingWithData]: Refresh in progress, showing cached data
+     * - [PostItemState.FailedWithData]: Fetch failed, showing last known data
+     * - [PostItemState.Missing]: Needs fetch, no cached data
+     * - [PostItemState.Fetching]: Fetch in progress, no cached data
+     * - [PostItemState.Failed]: Fetch failed, no cached data
+     *
+     * This is a suspend function that reads from cache on a background thread.
+     */
+    suspend fun loadItems(): List<PostMetadataCollectionItem> = collection.loadItems()
+
+    /**
+     * Refresh the collection (fetch page 1, replace metadata).
+     *
+     * This:
+     * 1. Fetches metadata from the network (page 1)
+     * 2. Replaces existing metadata in the store
+     * 3. Fetches missing/stale entities
+     *
+     * Returns sync statistics including counts and pagination info.
+     *
+     * This is a suspend function and should be called from a coroutine or background thread.
+     */
+    suspend fun refresh(): SyncResult = collection.refresh()
+
+    /**
+     * Load the next page of items.
+     *
+     * This:
+     * 1. Fetches metadata for the next page
+     * 2. Appends to existing metadata in the store
+     * 3. Fetches missing/stale entities from the new page
+     *
+     * Returns a no-op result if already on the last page.
+     *
+     * This is a suspend function and should be called from a coroutine or background thread.
+     */
+    suspend fun loadNextPage(): SyncResult = collection.loadNextPage()
+
+    /**
+     * Get combined list info (pagination + sync state) in a single query.
+     *
+     * Returns `null` if the list hasn't been created yet.
+     *
+     * The returned [ListInfo] contains:
+     * - `state`: Current sync state (IDLE, FETCHING_FIRST_PAGE, FETCHING_NEXT_PAGE, ERROR)
+     * - `errorMessage`: Error message if state is ERROR
+     * - `currentPage`: Current page number (0 = not loaded yet)
+     * - `totalPages`: Total pages if known
+     * - `totalItems`: Total items if known
+     * - `perPage`: Items per page setting
+     *
+     * Use [ListInfo.hasMorePages] extension to check if more pages are available.
+     */
+    fun listInfo(): ListInfo? = collection.listInfo()
+
+    /**
+     * Internal method called by DatabaseChangeNotifier when a database update occurs.
+     *
+     * Checks relevance and notifies appropriate observers:
+     * - Data updates -> dataObservers
+     * - List info updates -> listInfoObservers
+     */
+    internal fun notifyIfRelevant(hook: UpdateHook) {
+        val isDataRelevant = collection.isRelevantDataUpdate(hook)
+        val isListInfoRelevant = collection.isRelevantListInfoUpdate(hook)
+        if (isDataRelevant) {
+            dataObservers.forEach { it() }
+        }
+        if (isListInfoRelevant) {
+            listInfoObservers.forEach { it() }
+        }
+    }
+
+    /**
+     * Unregister this collection from receiving database change notifications.
+     *
+     * Call this when the collection is no longer needed, or use `.use { }` for automatic cleanup.
+     * After calling close(), the collection will no longer notify observers of database changes.
+     */
+    override fun close() {
+        DatabaseChangeNotifier.unregister(this)
+    }
+}

native/kotlin/api/kotlin/src/main/kotlin/rs/wordpress/cache/kotlin/PostServiceExtensions.kt

@@ -1,7 +1,9 @@
 package rs.wordpress.cache.kotlin
 
+import uniffi.wp_api.PostEndpointType
 import uniffi.wp_mobile.AnyPostFilter
 import uniffi.wp_mobile.FullEntityAnyPostWithEditContext
+import uniffi.wp_mobile.PostListFilter
 import uniffi.wp_mobile.PostService
 import uniffi.wp_mobile_cache.EntityId
 
@@ -34,3 +36,28 @@ fun PostService.getObservablePostCollectionWithEditContext(
         isRelevantUpdate = collection::isRelevantUpdate
     )
 }
+
+/**
+ * Create an observable metadata collection for posts with edit context.
+ *
+ * This uses the "metadata-first" sync strategy:
+ * 1. Fetch lightweight metadata (id + modified_gmt) to define list structure
+ * 2. Selectively fetch full data for missing or stale items
+ *
+ * Unlike [getObservablePostCollectionWithEditContext] which fetches full data for all items,
+ * this collection shows cached items immediately and fetches only what's needed.
+ *
+ * Items include fetch state (Missing, Fetching, Cached, Stale, Failed) so the UI
+ * can show appropriate feedback for each item.
+ *
+ * @param endpointType The post endpoint type (Posts, Pages, or Custom)
+ * @param filter Filter parameters (status, author, categories, etc.)
+ * @return Observable metadata collection that notifies on database changes
+ */
+fun PostService.getObservablePostMetadataCollectionWithEditContext(
+    endpointType: PostEndpointType,
+    filter: PostListFilter
+): ObservableMetadataCollection {
+    val collection = this.createPostMetadataCollectionWithEditContext(endpointType, filter)
+    return createObservableMetadataCollection(collection)
+}

native/kotlin/example/composeApp/src/commonMain/kotlin/rs/wordpress/example/shared/App.kt

@@ -10,6 +10,7 @@ import rs.wordpress.example.shared.ui.login.LoginScreen
 import rs.wordpress.example.shared.ui.plugins.PluginListScreen
 import rs.wordpress.example.shared.ui.plugins.PluginListViewModel
 import rs.wordpress.example.shared.ui.postcollection.PostCollectionScreen
+import rs.wordpress.example.shared.ui.postmetadatacollection.PostMetadataCollectionScreen
 import rs.wordpress.example.shared.ui.site.SiteScreen
 import rs.wordpress.example.shared.ui.stresstest.StressTestScreen
 import rs.wordpress.example.shared.ui.users.UserListScreen
@@ -57,6 +58,9 @@ fun App(authenticationEnabled: Boolean, authenticateSite: (String) -> Unit) {
                     },
                     onPostCollectionClicked = {
                         navController.navigate("postcollection")
+                    },
+                    onPostMetadataCollectionClicked = {
+                        navController.navigate("postmetadatacollection")
                     }
                 )
             }
@@ -70,7 +74,14 @@ fun App(authenticationEnabled: Boolean, authenticateSite: (String) -> Unit) {
                 StressTestScreen()
             }
             composable("postcollection") {
-                PostCollectionScreen()
+                PostCollectionScreen(
+                    onBackClicked = { navController.popBackStack() }
+                )
+            }
+            composable("postmetadatacollection") {
+                PostMetadataCollectionScreen(
+                    onBackClicked = { navController.popBackStack() }
+                )
             }
         }
     }