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>>
+)