Define PagingConfig and Paging Strategies (#619)

Signed-off-by: mramotar <[email protected]>

paging/core/src/commonMain/kotlin/org/mobilenativefoundation/paging/core/AggregatingStrategy.kt

@@ -0,0 +1,31 @@
+package org.mobilenativefoundation.paging.core
+
+/**
+ * Represents a strategy for aggregating loaded pages of data into a single instance of [PagingItems].
+ *
+ * The [AggregatingStrategy] determines how the loaded pages of data should be combined and ordered to form a coherent list of [PagingData.Single] items.
+ * It takes into account the anchor position, prefetch position, paging configuration, and the current state of the paging buffer.
+ *
+ * @param Id The type of the unique identifier for each item in the paged data.
+ * @param K The type of the key used for paging.
+ * @param P The type of the parameters associated with each page of data.
+ * @param D The type of the data items.
+ */
+interface AggregatingStrategy<Id : Comparable<Id>, K : Any, P : Any, D : Any> {
+
+    /**
+     * Aggregates the loaded pages of data into a single instance of [PagingItems].
+     *
+     * @param anchorPosition The current anchor position in the paged data.
+     * @param prefetchPosition The position to prefetch data from, or `null` if no prefetching is needed.
+     * @param pagingConfig The configuration of the pager, including page size and prefetch distance.
+     * @param pagingBuffer The current state of the paging buffer, containing the loaded data.
+     * @return The aggregated list of [PagingItems] representing the combined and ordered paging data.
+     */
+    fun aggregate(
+        anchorPosition: PagingKey<K, P>,
+        prefetchPosition: PagingKey<K, P>?,
+        pagingConfig: PagingConfig,
+        pagingBuffer: PagingBuffer<Id, K, P, D>,
+    ): PagingItems<Id, K, P, D>
+}

paging/core/src/commonMain/kotlin/org/mobilenativefoundation/paging/core/ErrorHandlingStrategy.kt

@@ -0,0 +1,25 @@
+package org.mobilenativefoundation.paging.core
+
+/**
+ * Represents different strategies for handling errors during the paging process.
+ */
+sealed interface ErrorHandlingStrategy {
+    /**
+     * Ignores errors and continues with the previous state.
+     */
+    data object Ignore : ErrorHandlingStrategy
+
+    /**
+     * Passes the error to the UI layer for handling.
+     */
+    data object PassThrough : ErrorHandlingStrategy
+
+    /**
+     * Retries the last failed load operation.
+     *
+     * @property maxRetries The maximum number of retries before passing the error to the UI. Default is 3.
+     */
+    data class RetryLast(
+        val maxRetries: Int = 3
+    ) : ErrorHandlingStrategy
+}

paging/core/src/commonMain/kotlin/org/mobilenativefoundation/paging/core/FetchingStrategy.kt

@@ -0,0 +1,34 @@
+package org.mobilenativefoundation.paging.core
+
+/**
+ * Represents a strategy for determining whether to fetch more data based on the current state of the pager.
+ * The fetching strategy is responsible for deciding whether to fetch more data based on the anchor position,
+ * prefetch position, paging configuration, and the current state of the paging buffer.
+ *
+ * Implementing a custom [FetchingStrategy] allows you to define your own logic for when to fetch more data.
+ * For example, you can fetch more data when the user scrolls near the end of the currently loaded data, or when a certain number of items are remaining in the buffer.
+ *
+ * @param Id The type of the unique identifier for each item in the paged data.
+ * @param K The type of the key used for paging.
+ * @param P The type of the parameters associated with each page of data.
+ * @param D The type of the data items.
+ */
+interface FetchingStrategy<Id : Comparable<Id>, K : Any, P : Any, D : Any> {
+
+    /**
+     * Determines whether to fetch more data based on the current state of the pager.
+     * The [shouldFetch] implementation should determine whether more data should be fetched based on the provided parameters.
+     *
+     * @param anchorPosition The current anchor position in the paged data.
+     * @param prefetchPosition The position to prefetch data from, or `null` if no prefetching is needed.
+     * @param pagingConfig The configuration of the pager, including page size and prefetch distance.
+     * @param pagingBuffer The current state of the paging buffer, containing the loaded data.
+     * @return `true` if more data should be fetched, `false` otherwise.
+     */
+    fun shouldFetch(
+        anchorPosition: PagingKey<K, P>,
+        prefetchPosition: PagingKey<K, P>?,
+        pagingConfig: PagingConfig,
+        pagingBuffer: PagingBuffer<Id, K, P, D>,
+    ): Boolean
+}

paging/core/src/commonMain/kotlin/org/mobilenativefoundation/paging/core/PagingConfig.kt

@@ -0,0 +1,34 @@
+package org.mobilenativefoundation.paging.core
+
+/**
+ * Represents the configuration for paging behavior.
+ *
+ * @property pageSize The number of items to load per page.
+ * @property prefetchDistance The distance from the edge of the loaded data at which to prefetch more data.
+ * @property insertionStrategy The strategy for inserting new data into the paging buffer.
+ */
+data class PagingConfig(
+    val pageSize: Int,
+    val prefetchDistance: Int,
+    val insertionStrategy: InsertionStrategy
+) {
+    /**
+     * Represents different insertion strategies for adding new data to the paging buffer.
+     */
+    enum class InsertionStrategy {
+        /**
+         * Appends new data to the end of the buffer.
+         */
+        APPEND,
+
+        /**
+         * Prepends new data to the beginning of the buffer.
+         */
+        PREPEND,
+
+        /**
+         * Replaces the existing data in the buffer with the new data.
+         */
+        REPLACE,
+    }
+}

paging/core/src/commonMain/kotlin/org/mobilenativefoundation/paging/core/PagingItems.kt

@@ -0,0 +1,14 @@
+package org.mobilenativefoundation.paging.core
+
+/**
+ * Represents a list of paging items.
+ *
+ * @param Id The type of the unique identifier for each item in the paged data.
+ * @param K The type of the key used for paging.
+ * @param P The type of the parameters associated with each page of data.
+ * @param D The type of the data items.
+ * @property data The list of [PagingData.Single] items representing the paging data.
+ */
+data class PagingItems<Id : Comparable<Id>, K : Any, P : Any, D : Any>(
+    val data: List<PagingData.Single<Id, K, P, D>>
+)