diff --git a/paging/core/src/commonMain/kotlin/org/mobilenativefoundation/paging/core/AggregatingStrategy.kt b/paging/core/src/commonMain/kotlin/org/mobilenativefoundation/paging/core/AggregatingStrategy.kt new file mode 100644 index 000000000..d835a782c --- /dev/null +++ b/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, 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, + prefetchPosition: PagingKey?, + pagingConfig: PagingConfig, + pagingBuffer: PagingBuffer, + ): PagingItems +} \ No newline at end of file diff --git a/paging/core/src/commonMain/kotlin/org/mobilenativefoundation/paging/core/ErrorHandlingStrategy.kt b/paging/core/src/commonMain/kotlin/org/mobilenativefoundation/paging/core/ErrorHandlingStrategy.kt new file mode 100644 index 000000000..906ccb124 --- /dev/null +++ b/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 +} \ No newline at end of file diff --git a/paging/core/src/commonMain/kotlin/org/mobilenativefoundation/paging/core/FetchingStrategy.kt b/paging/core/src/commonMain/kotlin/org/mobilenativefoundation/paging/core/FetchingStrategy.kt new file mode 100644 index 000000000..54d7fe705 --- /dev/null +++ b/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, 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, + prefetchPosition: PagingKey?, + pagingConfig: PagingConfig, + pagingBuffer: PagingBuffer, + ): Boolean +} diff --git a/paging/core/src/commonMain/kotlin/org/mobilenativefoundation/paging/core/PagingConfig.kt b/paging/core/src/commonMain/kotlin/org/mobilenativefoundation/paging/core/PagingConfig.kt new file mode 100644 index 000000000..481057c81 --- /dev/null +++ b/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, + } +} \ No newline at end of file diff --git a/paging/core/src/commonMain/kotlin/org/mobilenativefoundation/paging/core/PagingItems.kt b/paging/core/src/commonMain/kotlin/org/mobilenativefoundation/paging/core/PagingItems.kt new file mode 100644 index 000000000..c1077a8b2 --- /dev/null +++ b/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, K : Any, P : Any, D : Any>( + val data: List> +)