skip to content

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?

level: middleimportance: must knowfreq 62%

answer

  1. PagingData is single-use
  2. rotation versus a reload
  3. multicast with the loaded pages
  4. transform before caching
  5. Attempt to collect twice from pageEventFlow

basics

~20 s

cachedIn(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 lines
kotlin
sealed 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

for a junior

Recall that cachedIn(viewModelScope) is what stops a paged list from reloading on rotation, and that it belongs in the ViewModel.

for a middle

Explain that PagingData is single-use, why cachedIn multicasts it, and why map, filter and insertSeparators go before cachedIn inside the outer Flow.map.

for a senior

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.

for a principal

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