In Paging 3, why does a ViewModel end its Pager.flow chain with cachedIn(viewModelScope), and where do map and insertSeparators go relative to it?
answer
- PagingData is single-use
- rotation versus a reload
- multicast with the loaded pages
- transform before caching
- Attempt to collect twice from pageEventFlow
basics
~20 scachedIn(viewModelScope) shares the PagingData stream and keeps its loaded pages alive in the ViewModel, so a rotated screen gets them back instead of reloading. Put map, filter and insertSeparators before it so their results are cached too.
solid answer
~40 s`Pager.flow` is cold and each `PagingData` it emits can only be presented once. Without caching, a recreated Activity or Fragment collects the flow again and Paging starts from scratch, and an operator that replays the latest value, such as `combine`, collects one `PagingData` twice and fails with an `IllegalStateException` that literally asks whether you forgot `cachedIn`. `cachedIn(scope)` multicasts the stream and keeps the loaded data for as long as the scope is active, so the scope must outlive the UI: `viewModelScope`, not an Activity's `lifecycleScope`. It caches the results of every transformation placed before it, so per-item work such as `PagingData.map`, `filter` and `insertSeparators` goes inside `flow.map { pagingData -> ... }` ahead of `cachedIn`.
code
kotlin · 24 linessealed interface WineRow {
data class Item(val wine: Wine) : WineRow
data class VarietyHeader(val grape: String) : WineRow
}
class WineListViewModel(api: WineApi) : ViewModel() {
private val pager = Pager(PagingConfig(pageSize = 10)) { WinePagingSource(api) }
val rows: Flow<PagingData<WineRow>> = pager.flow
.map { pagingData ->
pagingData
.map { wine -> WineRow.Item(wine) }
.insertSeparators<WineRow.Item, WineRow> { before, after ->
when {
after == null -> null
before == null || before.wine.grape != after.wine.grape ->
WineRow.VarietyHeader(after.wine.grape)
else -> null
}
}
}
.cachedIn(viewModelScope)
}go deeper
Recall that cachedIn(viewModelScope) is what stops a paged list from reloading on rotation, and that it belongs in the ViewModel.
Explain that PagingData is single-use, why cachedIn multicasts it, and why map, filter and insertSeparators go before cachedIn inside the outer Flow.map.
Diagnose the collect-twice IllegalStateException from a combine, a cache tied to the wrong scope, and headers that appear late because separators wait for adjacent pages or the end of pagination.
Standardise where paging streams are built and cached, one Pager per ViewModel with transformations before cachedIn, so each screen does not reinvent the order and leak caches.
## Why PagingData needs caching A `Pager` exposes `flow`, a **cold** `Flow<PagingData<Value>>`. Two properties of that stream cause most Paging bugs on Android: - **Collecting it again starts over.** Each new collection of `Pager.flow` begins a fresh generation and loads from the start. On a rotation the new Activity or Fragment collects again, so without a cache the user waits for the first page again and loses their place. - **A `PagingData` is single-use.** The `Pager.flow` documentation says instances "are not re-usable and cannot be submitted multiple times". If two collectors reach the same instance, for example because `combine` replays the latest `PagingData` downstream, Paging fails with `IllegalStateException: Attempt to collect twice from pageEventFlow, which is an illegal operation. Did you forget to call Flow<PagingData<*>>.cachedIn(coroutineScope)?` ## What cachedIn does **`Flow<PagingData<T>>.cachedIn(scope: CoroutineScope)`** fixes both: 1. It **multicasts** the stream, so every downstream collector shares the same underlying loading. 2. It **caches** the pages loaded so far and hands each new collector a new `PagingData` pre-loaded with them, so a recreated screen shows the list immediately. 3. It keeps that cache alive **as long as `scope` is active**. The KDoc says to use a scope that is already managed, like a ViewModel's, or to cancel it yourself to avoid leaks. The scope choice is the whole point: | Scope passed to `cachedIn` | What survives a rotation | |---|---| | `viewModelScope` | everything: the ViewModel outlives the configuration change | | an Activity's `lifecycleScope` | nothing: the scope is cancelled with the old Activity | | no `cachedIn` at all | nothing, and double collection can crash | Keep **one `Pager` per ViewModel**, stored in a property. A repository function that builds a `Pager(...).flow.cachedIn(viewModelScope)` on every call creates a new stream, and a new cache that lives until the scope ends, each time it is called. ## Where transformations go `PagingData` has its own operators, applied to items as pages load: `map`, `filter`, `flatMap` and `insertSeparators`. They run on a `PagingData`, so you apply them inside the outer `Flow.map`: ```kotlin pager.flow .map { pagingData -> pagingData.filter { it.inStock }.map { WineRow.Item(it) } } .cachedIn(viewModelScope) ``` The Android guide on transforming streams states that `cachedIn()` caches the results of the transformations that occur **before** it. Anything placed after it runs again for every collector and after every configuration change. So: - put expensive or stable per-item work **before** `cachedIn`; - put a `combine` with another flow, such as a set of favourite ids that changes often, **after** `cachedIn`, which is also what makes combining safe, because each collection then gets a fresh `PagingData`. ## insertSeparators across pages `insertSeparators(terminalSeparatorType, generator)` calls `generator(before, after)` for each adjacent pair and inserts whatever non-null item it returns. For a winery catalogue sorted by grape, the generator returns a `VarietyHeader` whenever `before` and `after` have different grapes. Three behaviours to know: - **Between pages, the generator runs only once both pages are loaded**, as the KDoc states. The header between the last Malbec of page 3 and the first Merlot of page 4 appears when page 4 arrives. - **Terminal separators wait for the end of pagination.** `before == null` is the header slot and `after == null` the footer slot. With the default `TerminalSeparatorType.FULLY_COMPLETE`, they appear only once the prepend (header) or append (footer) end is reached by the `PagingSource` and, when one is set, the `RemoteMediator`. `SOURCE_COMPLETE` waits for the `PagingSource` alone. - **Type parameters matter.** `insertSeparators<T : R, R : Any>` returns `PagingData<R>`, so items and separators share a sealed parent type, and the adapter or lazy list renders one view type per subclass. ## Ordering the chain A typical ViewModel chain for a winery catalogue reads top to bottom like this: 1. a query or filter flow, `flatMapLatest`-ed into `Pager(...).flow`, so a new query starts a new stream; 2. `map { pagingData -> ... }` with `filter`, `map` and `insertSeparators` on the `PagingData`; 3. `cachedIn(viewModelScope)`; 4. optionally `combine` with fast-changing UI state, mapping each `PagingData` again. Separators placed in step 2 are computed once per loaded page and replayed from the cache after a rotation. A filter placed in step 4 would rerun for every collector and after every rotation.
- How do you page search results for a query the user can change, without losing caching?Hold the query in a `MutableStateFlow` in the ViewModel and `flatMapLatest` it into a new `Pager(...).flow` per query, then apply `cachedIn(viewModelScope)` to the result. `flatMapLatest` cancels the old query's stream when a new one arrives, and `cachedIn` at the end shares and caches whichever generation is current.
- Why combine a favourites flow after cachedIn rather than before it?`combine` re-emits the latest `PagingData` every time the favourites change. After `cachedIn`, each emission is a fresh `PagingData` backed by the shared cache, so presenting it again is legal and the pages are not reloaded. Before `cachedIn`, the replayed instance would be collected twice and fail with the collect-twice `IllegalStateException`.
- cachedIn with the Activity's lifecycleScope keeps the list across rotation
- Calling cachedIn first and mapping items afterwards to keep the cache smaller
- Building a new Pager inside a function the Fragment calls on every start
- The header separator should appear with the very first page
- A PagingData can safely be submitted to two adapters at once