Paginator is a powerful, flexible pagination library for Kotlin Multiplatform (KMP) that goes far beyond simple "load next page" patterns. It provides a full-featured page management system with support for jumping to arbitrary pages, bidirectional navigation, bookmarks, page caching, element-level CRUD, incomplete page handling, capacity management, and reactive state via Kotlin Flows.

Supported targets: Android · JVM · iosX64 · iosArm64 · iosSimulatorArm64

Telegram Community | YouTube Tutorial (RU)

• Features
• Installation
• Quick Start
• Core Concepts
  • PageState
  • Paginator vs MutablePaginator
  • Context Window
  • Bookmarks
  • Capacity & Incomplete Pages
  • Final Page Limit
• Navigation
  • goNextPage
  • goPreviousPage
  • jump
  • jumpForward / jumpBack
  • restart
  • refresh
• Dirty Pages
• Reactive State
  • Snapshot Flow
  • Cache Flow
• Element-Level Operations
• Custom PageState Subclasses
• State Serialization
• Lock Flags
• Logger
• Extension Functions
  • PageState Extensions
  • Paginator Extensions
• Full Example
• API Reference
• Releasing a New Version
• License

• Bidirectional pagination -- navigate forward (goNextPage) and backward (goPreviousPage)
• Jump to any page -- jump to arbitrary pages with jump(bookmark)
• Bookmark system -- define bookmarks and cycle through them with jumpForward / jumpBack, with optional recycling (wrap-around)
• Incomplete page handling -- when the server returns fewer items than expected, the paginator detects this and re-requests the page on the next goNextPage, showing cached data with a loading indicator
• Final page limit -- set finalPage to enforce a maximum page boundary (typically from backend metadata), throwing FinalPageExceededException when exceeded
• Page caching -- loaded pages are cached in a sorted map for instant access
• Reactive state -- observe page changes via snapshot Flow (visible pages) or asFlow() ( entire cache)
• Element-level CRUD -- get, set, add, remove, and replace individual elements within pages, with automatic page rebalancing
• Capacity management -- resize pages on the fly with automatic data redistribution
• Custom PageState subclasses -- extend SuccessPage, ErrorPage, ProgressPage, or EmptyPage with your own types via initializer lambdas
• Dirty pages -- mark pages as "dirty" so they are automatically refreshed (fire-and-forget) on the next navigation (goNextPage, goPreviousPage, jump). CRUD operations can also mark pages dirty via the isDirty flag
• Two-tier API -- Paginator (read-only navigation, dirty tracking, release) and MutablePaginator (element-level CRUD, resize, public setState)
• Lock flags -- prevent specific operations at runtime (lockJump, lockGoNextPage, lockGoPreviousPage, lockRestart, lockRefresh)
• Parallel loading -- preload multiple pages concurrently with loadOrGetPageState
• Pluggable logging -- implement the PaginatorLogger interface to receive detailed logs about navigation, state changes, and element-level operations. No logging by default (null)
• State serialization -- save and restore the paginator's cache to/from JSON via kotlinx.serialization, enabling seamless recovery after process death on any KMP target
• Context window -- the paginator tracks a contiguous range of successfully loaded pages ( startContextPage..endContextPage), which defines the visible snapshot

The library is published to Maven Central. No additional repository configuration needed.

Add the dependency to commonMain in your module's build.gradle.kts:

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.github.jamal-wia:paginator:7.2.1")
        }
    }
}

Gradle automatically resolves the correct platform artifact (android, jvm, iosArm64, etc.) from the KMP metadata.

dependencies {
    implementation("io.github.jamal-wia:paginator:7.2.1")
}

dependencies {
    implementation("io.github.jamal-wia:paginator-jvm:7.2.1")
}

Create a MutablePaginator in your ViewModel or Presenter, providing a data source lambda:

class MyViewModel : ViewModel() {

    private val paginator = MutablePaginator<Item>(source = { page ->
        repository.loadPage(page)
    })
}

The source lambda receives an Int page number and should return a List<T>.

Subscribe to the snapshot Flow to receive UI updates, then start the paginator by jumping to the first page:

init {
    paginator.snapshot
        .filter { it.isNotEmpty() }
        .onEach { pages -> updateUI(pages) }
        .flowOn(Dispatchers.Main)
        .launchIn(viewModelScope)

    viewModelScope.launch {
        paginator.jump(bookmark = BookmarkInt(page = 1))
    }
}

// Load next page (triggered by scroll reaching the end)
fun loadMore() {
    viewModelScope.launch { paginator.goNextPage() }
}

// Load previous page (triggered by scroll reaching the top)
fun loadPrevious() {
    viewModelScope.launch { paginator.goPreviousPage() }
}

When the paginator is no longer needed, release its resources:

override fun onCleared() {
    paginator.release()
    super.onCleared()
}

PageState<E> is a sealed class representing the state of a single page. Every page has a page: Int number, data: List<E> items, and a unique id: Long.

All PageState subclasses are open, so you can create your own custom types:

class MyCustomProgress<T>(
    page: Int,
    data: List<T>,
    val progressPercent: Int = 0
) : PageState.ProgressPage<T>(page, data)

The library provides two classes with different levels of access:

When to use Paginator: Use it when you only need to navigate and observe pages (e.g., a read-only list screen). It keeps setState protected, preventing accidental cache mutations from outside the class hierarchy.

When to use MutablePaginator: Use it when you need element-level CRUD, capacity resizing, or direct state manipulation. Most use cases will use this class.

// Most common: full-featured paginator
val paginator = MutablePaginator<String>(source = { page ->
    api.fetchItems(page)
})

// Read-only: only navigation, no element mutations
val readOnlyPaginator = Paginator<String>(source = { page ->
    api.fetchItems(page)
})

The constructor takes a single source lambda -- a suspending function that loads data for a given page. The receiver is the paginator itself, giving you access to its properties during loading.

The paginator maintains a context window defined by startContextPage and endContextPage. This represents the contiguous range of successfully loaded pages visible to the user. Thesnapshot Flow emits only pages within (and adjacent to) this window.

When you call goNextPage, the window expands forward. When you call goPreviousPage, it expands backward. When you jump, the window resets to the target page and expands outward.

Bookmarks are predefined page targets for quick navigation:

paginator.bookmarks.addAll(
    listOf(
        BookmarkInt(5),
        BookmarkInt(10),
        BookmarkInt(15),
    )
)
paginator.recyclingBookmark = true // Wrap around when reaching the end

Navigate through bookmarks with:

• jumpForward() -- moves to the next bookmark
• jumpBack() -- moves to the previous bookmark

You can also implement the Bookmark interface for custom bookmark types.

capacity defines the expected number of items per page (default: 20). This is critical for the paginator to determine whether a page is filled (complete) or incomplete.

paginator.core.resize(capacity = 10, resize = false, silently = true)

When a page returns fewer items than capacity, the paginator considers it incomplete. On the next goNextPage call, instead of advancing to a new page, the paginator re-requests the same page. During this re-request, it creates a ProgressPage containing the previously cached data, so the UI can show the existing items alongside a loading indicator.

This is useful when a backend occasionally returns partial results.

Set capacity to UNLIMITED_CAPACITY (0) to disable capacity checks entirely.

Set finalPage to enforce an upper boundary on pagination:

paginator.finalPage = 20 // Typically from backend metadata

Any attempt to navigate beyond this page (via goNextPage, jump, etc.) throws FinalPageExceededException:

try {
    paginator.goNextPage()
} catch (e: FinalPageExceededException) {
    showMessage("Reached page ${e.finalPage}, no more data")
}

Loads the page after the current endContextPage. If the paginator hasn't started, it automatically jumps to page 1.

suspend fun goNextPage(): PageState<T>

Behavior:

1. Expands endContextPage to find the true end of contiguous success pages
2. Determines the next page number
3. If the next page exceeds finalPage, throws FinalPageExceededException
4. If the next page is already a ProgressPage, returns immediately (deduplication)
5. Otherwise, sets a ProgressPage, loads from source, and updates the cache

Loads the page before the current startContextPage. Requires the paginator to be started.

suspend fun goPreviousPage(): PageState<T>

Behavior mirrors goNextPage but in the backward direction. Shows a loading indicator at the top.

Jumps directly to any page by bookmark:

suspend fun jump(bookmark: Bookmark): Pair<Bookmark, PageState<T>>

If the target page is already cached as a filled success page, returns immediately without reloading. Otherwise, resets the context window to the target page and loads it.

Navigate through the bookmark list:

suspend fun jumpForward(): Pair<Bookmark, PageState<T>>?  // null if no more bookmarks
suspend fun jumpBack(): Pair<Bookmark, PageState<T>>?     // null if no more bookmarks

When recyclingBookmark = true, the iterator wraps around.

Clears all cached pages except page 1's structure, resets the context to page 1, and reloads it:

suspend fun restart()

Ideal for swipe-to-refresh.

Reloads specific pages in parallel without clearing the cache:

suspend fun refresh(pages: List<Int>)

Sets all specified pages to ProgressPage (preserving cached data), then reloads them concurrently. Use the extension refreshAll() to refresh every cached page.

Pages can be marked as dirty to indicate that their data is stale and needs to be refreshed. When a navigation function (jump, goNextPage, goPreviousPage) completes, it automatically checks for dirty pages within the current context window (startContextPage..endContextPage) and launches a fire-and-forget refresh for them in parallel.

// Mark a single page
paginator.core.markDirty(3)

// Mark multiple pages
paginator.core.markDirty(listOf(1, 2, 3))

// CRUD operations can also mark the affected page as dirty
paginator.setElement(updatedItem, page = 3, index = 0, isDirty = true)
paginator.removeElement(page = 3, index = 2, isDirty = true)
paginator.addAllElements(listOf(newItem), targetPage = 3, index = 0, isDirty = true)

// Clear a single page
paginator.core.clearDirty(3)

// Clear multiple pages
paginator.core.clearDirty(listOf(1, 2))

// Clear all dirty flags
paginator.core.clearAllDirty()

Dirty flags are also automatically cleared:

• After refresh() completes for the refreshed pages
• After release() resets the paginator

paginator.core.isDirty(3)     // true if page 3 is dirty
paginator.core.dirtyPages      // Set<Int> snapshot of all dirty page numbers

When navigation completes (e.g., goNextPage loads page 5 successfully):

1. The paginator checks dirtyPages for pages in startContextPage..endContextPage
2. If any dirty pages are found, they are removed from the dirty set
3. A refresh(pages = dirtyInContext) is launched in a separate coroutine (fire-and-forget)
4. The navigation function returns immediately -- it does not wait for the dirty refresh

This ensures the user sees the navigation result instantly while stale pages are silently refreshed in the background.

The primary way to observe the paginator's visible state:

val snapshot: Flow<List<PageState<T>>>

Emits a list of PageState objects within the context window whenever a navigation action completes. This is what your UI should collect.

paginator.snapshot
    .onEach { pages -> adapter.submitList(pages) }
    .launchIn(scope)

For advanced use cases, observe the entire cache:

val cacheFlow: Flow<List<PageState<T>>> = paginator.core.asFlow()

This emits the complete cache list (all pages, including those outside the context window).

The paginator supports CRUD operations on individual items within pages:

// Get an element
val item: T? = paginator.core.getElement(page = 3, index = 0)

// Set/replace an element
paginator.setElement(element = updatedItem, page = 3, index = 0)

// Remove an element (auto-rebalances pages)
val removed: T = paginator.removeElement(page = 3, index = 2)

// Add elements (overflows cascade to next pages)
paginator.addAllElements(
    elements = listOf(newItem),
    targetPage = 3,
    index = 0
)

// Replace all matching elements across all pages
paginator.replaceAllElements(
    providerElement = { current, _, _ -> current.copy(read = true) },
    predicate = { current, _, _ -> current.id == targetId }
)

When removing elements causes a page to drop below capacity, items are pulled from the next page to fill the gap. When adding elements causes overflow beyond capacity, excess items cascade to subsequent pages.

All mutating operations (setElement, removeElement, addAllElements) accept an optional isDirty: Boolean = false parameter. When set to true, the affected page is marked as dirty and will be automatically refreshed on the next navigation (see Dirty Pages).

You can create custom PageState subclasses and use them via the initializer lambdas:

// Custom progress page with additional metadata
class DetailedProgress<T>(
    page: Int,
    data: List<T>,
    val source: String = "network"
) : PageState.ProgressPage<T>(page, data)

// Register the custom initializer
paginator.initializerProgressPage = { page, data ->
    DetailedProgress(page = page, data = data, source = "api")
}

Available initializer properties:

• initializerProgressPage: (page: Int, data: List<T>) -> ProgressPage<T>
• initializerSuccessPage: (page: Int, data: List<T>) -> SuccessPage<T>
• initializerEmptyPage: (page: Int, data: List<T>) -> EmptyPage<T>
• initializerErrorPage: (exception: Exception, page: Int, data: List<T>) -> ErrorPage<T>

Use isRealProgressState(MyCustomProgress::class) and similar extension functions to check for specific subclasses with smart-casting.

The paginator supports saving and restoring its full state via kotlinx.serialization. This is essential for surviving Android/iOS process death -- when the system kills your app, you can save the paginator state to SavedStateHandle or a file and restore it when the user returns.

There are two levels of serialization:

• Paginator-level (recommended) — saves everything: cache, context window, capacity, dirty pages, finalPage, bookmarks, bookmark position, lock flags
• PagingCore-level — saves only the cache layer (cache, context window, capacity, dirty pages)

Your element type T must be annotated with @Serializable:

@Serializable
data class Article(val id: Long, val title: String, val body: String)

Use saveStateToJson to serialize the entire Paginator state into a JSON string. This is a suspend function that acquires the navigation mutex for thread-safety:

val json: String = paginator.saveStateToJson(Article.serializer())

To save only pages within the current context window (reduces snapshot size):

val json: String = paginator.saveStateToJson(Article.serializer(), contextOnly = true)

Persist it using whatever mechanism fits your platform:

// Android — SavedStateHandle (survives process death)
savedStateHandle["paginator_state"] = json

// Any KMP target — file storage
// (use expect/actual or a KMP file I/O library)

Use restoreStateFromJson to rebuild the full state from a previously saved JSON string. The snapshot is validated before restoration — invalid data throws IllegalArgumentException:

val json: String? = savedStateHandle["paginator_state"]
if (json != null) {
    paginator.restoreStateFromJson(json, Article.serializer())
}

After restoration, the paginator is ready to use immediately — the snapshot flow emits the restored pages, and navigation (goNextPage, goPreviousPage, jump) works as normal.

ErrorPage and ProgressPage cannot be serialized as-is (Exception is not serializable, and in-flight loads are meaningless after process death). During save, these pages are converted:

• Their cached data is preserved (e.g., stale data shown before the error/reload)
• The error message (exception.message) is preserved in the errorMessage field of PageEntry, so the UI can display the error reason after restoration
• They are restored as SuccessPage (or EmptyPage if data was empty)
• They are automatically marked as dirty, so the next navigation triggers a fire-and-forget refresh to re-fetch fresh data from the source

When restoring from a snapshot, the following validations are performed:

• capacity must be > 0
• startContextPage and endContextPage must be >= 0
• startContextPage must be <= endContextPage (unless both are 0)
• All page numbers must be >= 1
• No duplicate page numbers are allowed

Invalid snapshots throw IllegalArgumentException.

For advanced use cases, you can work with PagingCore directly. These methods are not suspend and do not acquire the mutex — ensure proper synchronization if calling concurrently:

// Save to a snapshot object
val snapshot: PagingCoreSnapshot<Article> = paginator.core.saveState()

// Save only context window pages
val snapshot: PagingCoreSnapshot<Article> = paginator.core.saveState(contextOnly = true)

// Restore from a snapshot object
paginator.core.restoreState(snapshot)

// JSON round-trip
val json: String = paginator.core.saveStateToJson(Article.serializer())
paginator.core.restoreStateFromJson(json, Article.serializer())

For custom serialization formats or non-JSON persistence:

// Save to a snapshot object (suspend, thread-safe)
val snapshot: PaginatorSnapshot<Article> = paginator.saveState()

// Restore from a snapshot object (suspend, thread-safe)
paginator.restoreState(snapshot)

Prevent specific operations at runtime:

paginator.lockGoNextPage = true // Temporarily prevent forward pagination

All locks are reset to false on release().

The paginator supports pluggable logging via the PaginatorLogger interface. By default, no logging is performed (logger is null). Implement the interface and assign it to paginator.logger to receive logs about navigation, state changes, and element-level operations.

interface PaginatorLogger {
    fun log(tag: String, message: String)
}

import com.jamal_aliev.paginator.logger.PaginatorLogger

// Platform-agnostic (works on all KMP targets)
object ConsoleLogger : PaginatorLogger {
    override fun log(tag: String, message: String) {
        println("[$tag] $message")
    }
}

// Android-specific
object AndroidLogger : PaginatorLogger {
    override fun log(tag: String, message: String) {
        android.util.Log.d(tag, message)
    }
}

val paginator = MutablePaginator<String>(source = { page ->
    api.fetchItems(page)
}).apply {
    logger = ConsoleLogger // or AndroidLogger on Android
}

Type-checking with Kotlin contracts for smart-casting:

pageState.isProgressState()  // true if ProgressPage
pageState.isSuccessState()   // true if SuccessPage (but NOT EmptyPage)
pageState.isEmptyState()     // true if EmptyPage
pageState.isErrorState()     // true if ErrorPage

// Check for specific custom subclasses
pageState.isRealProgressState(MyCustomProgress::class)

Distance calculations:

pageA near pageB  // true if pages are 0 or 1 apart
pageA far pageB   // true if pages are more than 1 apart
pageA gap pageB   // Int distance between page numbers

// Search for elements
paginator.indexOfFirst { it.id == targetId }    // Returns Pair<Int, Int>? (page, index)
paginator.indexOfLast { it.name == "test" }     // Search in reverse
paginator.getElement { it.id == targetId }             // Get first matching element

// Modify elements
paginator.setElement(updatedItem) { it.id == targetId }
paginator.removeElement { it.id == targetId }
paginator.addElement(newItem)  // Append to last page

// Iteration
paginator.forEach { pageState -> /* ... */ }
paginator.smartForEach { states, index, currentState -> /* continue? */ true }

// Traversal
paginator.walkForwardWhile(startState) { it.isSuccessState() }
paginator.walkBackwardWhile(endState) { it.isSuccessState() }

// Refresh all cached pages
paginator.refreshAll()

A complete ViewModel demonstrating all major features:

class PaginatorViewModel : ViewModel() {

    private val _uiState = MutableStateFlow<List<PageState<String>>>(emptyList())
    val uiState = _uiState.asStateFlow()

    private val paginator = MutablePaginator<String>(source = { page ->
        repository.loadPage(page)
    }).apply {
        core.resize(capacity = 5, resize = false, silently = true)
        finalPage = 20
        bookmarks.addAll(listOf(BookmarkInt(5), BookmarkInt(10), BookmarkInt(15)))
        recyclingBookmark = true
        logger = object : PaginatorLogger {
            override fun log(tag: String, message: String) {
                println("[$tag] $message")
            }
        }
    }

    init {
        paginator.snapshot
            .filter { it.isNotEmpty() }
            .onEach { _uiState.value = it }
            .flowOn(Dispatchers.Main)
            .launchIn(viewModelScope)

        viewModelScope.launch {
            paginator.jump(BookmarkInt(1))
        }
    }

    // 1. Forward pagination (loading indicator at bottom)
    fun loadNextPage() = viewModelScope.launch {
        try {
            paginator.goNextPage()
        } catch (e: FinalPageExceededException) {
            showError("No more pages")
        }
    }

    // 2. Backward pagination (loading indicator at top)
    fun loadPreviousPage() = viewModelScope.launch {
        paginator.goPreviousPage()
    }

    // 3. Jump to a user-specified page
    fun jumpToPage(page: Int) = viewModelScope.launch {
        try {
            paginator.jump(BookmarkInt(page))
        } catch (e: FinalPageExceededException) {
            showError("Page exceeds limit")
        }
    }

    // 4. Navigate bookmarks
    fun nextBookmark() = viewModelScope.launch { paginator.jumpForward() }
    fun prevBookmark() = viewModelScope.launch { paginator.jumpBack() }

    // 5. Swipe-to-refresh
    fun restart() = viewModelScope.launch { paginator.restart() }

    // 6. Retry on error
    fun retryPage(page: Int) = viewModelScope.launch {
        paginator.refresh(pages = listOf(page))
    }

    override fun onCleared() {
        paginator.release()
        super.onCleared()
    }
}

Rendering in Compose:

@Composable
fun PaginatedList(pages: List<PageState<String>>) {
    LazyColumn {
        pages.forEach { pageState ->
            when {
                pageState.isSuccessState() -> {
                    items(pageState.data.size) { index ->
                        Text(pageState.data[index])
                    }
                }
                pageState.isProgressState() -> {
                    // Show cached data (if any) + loading indicator
                    items(pageState.data.size) { index ->
                        Text(pageState.data[index], color = Color.Gray)
                    }
                    item { CircularProgressIndicator() }
                }
                pageState.isErrorState() -> {
                    item {
                        ErrorCard(
                            message = pageState.exception.message,
                            onRetry = { retryPage(pageState.page) }
                        )
                    }
                }
                pageState.isEmptyState() -> {
                    item { Text("No data on page ${pageState.page}") }
                }
            }
        }
    }
}

Step-by-step guide for publishing a new release of the library to Maven Central.

Make sure the following GitHub Secrets are configured in the repository (Settings → Secrets and variables → Actions → Repository secrets):

In paginator/build.gradle.kts, change the version property:

version = "7.2.1" // ← new version

Update the version in all implementation(...) snippets in this README (sections KMP, Android-only, and JVM) to match the new version.

git add -A
git commit -m "Bump version to 7.2.1"
git push origin master

1. Go to Releases → New release
2. Click "Choose a tag" and type the new version (e.g. 7.2.1), then select "Create new tag on publish"
3. Set Release title (e.g. 7.2.1)
4. Describe the changes in the description
5. Click "Publish release"

This triggers the Publish to Maven Central GitHub Actions workflow automatically.

1. Go to Actions and open the running workflow
2. Wait for the workflow to complete successfully (green checkmark)

1. Go to Sonatype Central Portal → Deployments
2. The deployment should appear with status PUBLISHING → PUBLISHED
3. Once PUBLISHED, the artifact is available at:

   io.github.jamal-wia:paginator:<version>
   

4. It may take 5–30 minutes for the artifact to become resolvable via Gradle after status changes to PUBLISHED

If you need to publish from your local machine instead of CI:

1. Add credentials to ~/.gradle/gradle.properties (NOT the project's gradle.properties):

   mavenCentralUsername=<your-sonatype-token-username>
   mavenCentralPassword=<your-sonatype-token-password>
   signing.keyId=<last-8-chars-of-gpg-key>
   signing.password=<gpg-key-passphrase>
   signing.secretKeyRingFile=<path-to-secring.gpg>

2. Run:

   ./gradlew :paginator:publishAndReleaseToMavenCentral --no-configuration-cache

3. The automaticRelease = true flag in build.gradle.kts ensures the deployment is automatically released after validation. No manual "Release" button click is needed.

The MIT License (MIT)

Copyright (c) 2023 Jamal Aliev

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.