Introducing a solution for paging in KMP projects. Motivations:
Seamless integration with Store and Mutable Store
Support for local mutations and streaming of child items within the list of paging items
Support for custom reducer, middleware, and post-reducer effects
Type of Change
[x] New feature (non-breaking change which adds functionality)
[x] This change requires a documentation update
Test Plan
Unit tests
Checklist:
Before submitting your PR, please review and check all of the following:
[x] I have performed a self-review of my own code
[x] I have commented my code, particularly in hard-to-understand areas
[x] I have made corresponding changes to the documentation
[x] My changes generate no new warnings
[x] I have added tests that prove my change is effective
[x] New and existing unit tests pass locally with my changes
Additional Notes:
Paging Technical Design Doc
1. Overview
Modular and flexible architecture. Using builder, reducer, middleware, and post-reducer effect patterns. Unidirectional
data flow. The Pager is the main component. Actions are dispatched through the Pager. The PagerBuilder creates
the Pager. It allows configuration of the paging behavior. The PagingSource defines the data loading logic. The FetchingStrategy determines when to fetch the next page. The AggregatingStrategy combines loaded pages into a single list. The Reducer handles state changes based on actions. When an action is dispatched, it goes through the middleware pipeline. The middleware can modify the action. The reducer then updates the state based on the action. After the reducer, we invoke post-reducer effects associated with the action and new state. The updated state is sent back the Pager and emitted to the UI.
2. Key Components
Pager: The main entry point for the paging library. It coordinates the paging process and provides access to the paging state and data.
PagingState: Represents the current state of the paging data, including loaded pages, errors, and loading status.
PagingAction: Defines the actions that can be dispatched to modify the paging state.
Reducer: Responsible for taking the current paging state and a dispatched action, and producing a new paging state based on the action and the current state.
Middleware: Intercepts and modifies paging actions before they reach the reducer, allowing for pre-processing, logging, or any other custom logic.
Effect: Represents side effects or additional actions that need to be performed after the state has been reduced based on a dispatched action.
PagingSource: Represents a data source that provides paged data, emitting a stream of load results.
PagingBuffer: A custom data structure for efficiently storing and retrieving paging data.
3. Customizations
Providing many extension points and customization options to tailor behavior. Main customization points:
PagingConfig: Allows configuring the paging behavior, such as page size, prefetch distance, and insertion strategy.
FetchingStrategy: Determines whether to fetch more data based on the current state of the pager.
AggregatingStrategy: Defines how loaded pages of data should be combined and ordered to form a coherent list of paging items.
ErrorHandlingStrategy: Specifies different strategies for handling errors during the paging process.
UserCustomActionReducer: Allows defining custom reducers for handling user-defined actions.
4. Data Flow
Unidirectional data flow. Main steps:
Pager is configured using PagerBuilder and provided an initial key, flow of anchor position, and paging config.
Pager subscribes to the PagingSource to receive paging data updates.
When a PagingAction is dispatched, it goes through the configured Middleware chain. This enables interception and modification of the action.
The modified action reaches the Reducer, which reduces the current PagingState based on the action and returns a new PagingState.
After reduction, any configured Effect instances are launched, enabling side effects to be performed based on the new PagingState.
Pager updates StateManager with the new PagingState.
FetchingStrategy determines when to fetch the next page of data based on the PagingConfig and current PagingState.
When a new page needs to be fetched, QueueManager enqueues the page key, and the JobCoordinator coordinates the execution of the paging job.
PagingSource loads the requested page and emits the loaded data through the PagingSourceStreamProvider.
The loaded page is stored in the MutablePagingBuffer for efficient retrieval and aggregation.
The AggregatingStrategy aggregates the loaded pages into a single list, which is then emitted through the Pager for consumption by the UI.
OliverRhyme
commented
2 weeks ago
Context:
Description
Introducing a solution for paging in KMP projects. Motivations:
Type of Change
Test Plan
Unit tests
Checklist:
Before submitting your PR, please review and check all of the following:
Additional Notes:
Paging Technical Design Doc
1. Overview
Modular and flexible architecture. Using builder, reducer, middleware, and post-reducer effect patterns. Unidirectional data flow. The
Pageris the main component. Actions are dispatched through thePager. ThePagerBuildercreates thePager. It allows configuration of the paging behavior. ThePagingSourcedefines the data loading logic. TheFetchingStrategydetermines when to fetch the next page. TheAggregatingStrategycombines loaded pages into a single list. TheReducerhandles state changes based on actions. When an action is dispatched, it goes through the middleware pipeline. The middleware can modify the action. The reducer then updates the state based on the action. After the reducer, we invoke post-reducer effects associated with the action and new state. The updated state is sent back thePagerand emitted to the UI.2. Key Components
Pager: The main entry point for the paging library. It coordinates the paging process and provides access to the paging state and data.PagingState: Represents the current state of the paging data, including loaded pages, errors, and loading status.PagingAction: Defines the actions that can be dispatched to modify the paging state.Reducer: Responsible for taking the current paging state and a dispatched action, and producing a new paging state based on the action and the current state.Middleware: Intercepts and modifies paging actions before they reach the reducer, allowing for pre-processing, logging, or any other custom logic.Effect: Represents side effects or additional actions that need to be performed after the state has been reduced based on a dispatched action.PagingSource: Represents a data source that provides paged data, emitting a stream of load results.PagingBuffer: A custom data structure for efficiently storing and retrieving paging data.3. Customizations
Providing many extension points and customization options to tailor behavior. Main customization points:
PagingConfig: Allows configuring the paging behavior, such as page size, prefetch distance, and insertion strategy.FetchingStrategy: Determines whether to fetch more data based on the current state of the pager.AggregatingStrategy: Defines how loaded pages of data should be combined and ordered to form a coherent list of paging items.ErrorHandlingStrategy: Specifies different strategies for handling errors during the paging process.UserCustomActionReducer: Allows defining custom reducers for handling user-defined actions.4. Data Flow
Unidirectional data flow. Main steps:
Pageris configured usingPagerBuilderand provided an initial key, flow of anchor position, and paging config.Pagersubscribes to thePagingSourceto receive paging data updates.PagingActionis dispatched, it goes through the configuredMiddlewarechain. This enables interception and modification of the action.Reducer, which reduces the currentPagingStatebased on the action and returns a newPagingState.Effectinstances are launched, enabling side effects to be performed based on the newPagingState.PagerupdatesStateManagerwith the newPagingState.FetchingStrategydetermines when to fetch the next page of data based on thePagingConfigand currentPagingState.QueueManagerenqueues the page key, and theJobCoordinatorcoordinates the execution of the paging job.PagingSourceloads the requested page and emits the loaded data through thePagingSourceStreamProvider.MutablePagingBufferfor efficient retrieval and aggregation.AggregatingStrategyaggregates the loaded pages into a single list, which is then emitted through thePagerfor consumption by the UI.5. Sample Code
See https://github.com/MobileNativeFoundation/Store/tree/paging/paging