Skip to content
CAI
Software that uses CAICheck a score

jamal-wia/Paginator

54.4

Adequate · 22 October 2026

20.7k

lines of production code

Kotlin

primary language

9

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

What this system is

This system is a Kotlin Multiplatform pagination library that provides both offset-based and cursor-based strategies for managing paginated data across Android, iOS, JVM, Desktop, JS, and Wasm. It offers dedicated UI bindings for Jetpack Compose and Android RecyclerViews, handling scroll-driven prefetching, scroll position preservation, and reactive error management. The architecture is modularized into distinct core, strategy, and UI modules to support independent development and consumption.

How it got here

2024 — Paginator KMP library release and modularization

5 changes.

The period centered on the initial release of the Paginator KMP pagination library, introducing offset and cursor-based strategies with UI bindings for Jetpack Compose and RecyclerView. The project underwent significant structural changes, migrating to Gradle Version Catalogs and splitting the monolithic module into distinct multiplatform artifacts. Concurrently, the demo application was enhanced with deterministic load controls and state persistence to facilitate reproducible testing of pagination scenarios.

2026 — Cursor pagination and scroll preservation

11 changes.

This period focused on introducing cursor-based pagination support across Compose, View, and core modules, alongside new offset-based composables for Lazy lists. Significant enhancements included implementing scroll position preservation across configuration changes and process death, as well as adding reactive caching and UI interweaving capabilities to the core paginator.

Features

Core paginator library refactored with reactive cache and UI interweaving

The paginator-core module has been restructured to introduce a reactive caching system and UI decoration capabilities. A new \PaginatorReactiveCache\ interface and \SnapshotReactiveCache\ implementation allow the paginator to consume live data source changes (inserts, updates, removes, moves) via \ReactiveEvent\ streams, automatically keeping the local cache in sync without re-fetching. Additionally, an \interweave\ feature enables inserting meta-elements (like date headers or dividers) into the paginated item stream using an \Interweaver\ strategy, while new extension functions simplify mapping \PageState\ snapshots to high-level \PaginatorUiState\ objects for UI consumption.

paginator-core · high confidence

Cursor-based pagination support added

A new cursor-based pagination strategy is now available alongside the existing offset-based paginator. This includes a \CursorPaginator\ for read-only, linked-list-style navigation using opaque server-issued bookmarks, and a \MutableCursorPaginator\ that adds element-level CRUD operations (add, remove, set) with automatic neighbor relinking. The implementation features a dedicated cache layer with chainable eviction strategies (LRU, FIFO, TTL, and context-window-based) and handles edge cases such as maintaining the context window on partial pages and re-anchoring after feed deletions.

paginator-cursor/src/commonMain · high confidence

Cursor-based pagination support for Android View-based RecyclerViews

This release adds a new \paginator-view-cursor\ module that brings cursor-based pagination to Android apps using the View system (RecyclerView). It provides extension functions like \bindPaginated\ and \bindPrefetchToRecyclerView\ for \CursorPaginator\, allowing developers to wire up cursor-driven data loading with automatic prefetching and scroll-position preservation. The module includes a \PrefetchBinding\ handle to manage the controller and scroll binding, and internal utilities like \DataItemCountTracker\ to keep the UI in sync with the paginator's state.

paginator-view-cursor · high confidence

Cursor-paginator support for Compose Lazy lists and grids

This update introduces a complete set of turnkey composables for cursor-based pagination in Jetpack Compose, mirroring the existing offset-paginator API. Developers can now use \PaginatedLazyColumn\, \PaginatedLazyRow\, \PaginatedLazyGrid\, and \PaginatedLazyStaggeredGrid\ to automatically handle scroll-driven prefetching, loading indicators, and edge-gated boundary animations. The library also provides \BindToLazyList\, \BindToLazyGrid\, and \BindToLazyStaggeredGrid\ extension functions for custom implementations, along with a \paginated\ DSL scope that simplifies header and footer management. Additionally, \PaginatedLazyColumn\ and \PaginatedLazyRow\ now feature automatic scroll-to-jump behavior, ensuring the list scrolls to the correct position when navigation events trigger page jumps.

paginator-compose-cursor · high confidence

Initial release of Paginator KMP pagination library

This change introduces the Paginator library, a Kotlin Multiplatform pagination solution supporting Android, iOS, JVM, Desktop, JS, and WasmJs. It provides two distinct pagination strategies—offset-based (\Paginator\/\MutablePaginator\) and cursor-based (\CursorPaginator\/\MutableCursorPaginator\)—alongside UI bindings for Jetpack Compose and Android RecyclerView. The release includes a Bill of Materials (BOM) for simplified dependency management, comprehensive documentation, and an MIT license.

(repo-wide) · high confidence

New View-based offset paginator with scroll preservation

The \paginator-view-offset\ module introduces a new set of Kotlin APIs for binding offset-based pagination to Android \RecyclerView\s, providing \bindPaginated\, \bindPrefetchToRecyclerView\, and \bindToRecyclerView\ entry points. These functions automatically manage lifecycle-scoped prefetch controllers, scroll listeners, and layout change listeners to handle data loading and index remapping. A key addition is the \preserveScroll\ parameter, which allows the paginator to snapshot and restore the \RecyclerView\'s scroll position across lifecycle events or process death, improving user experience during configuration changes.

paginator-view-offset · high confidence

New offset-based pagination composables for LazyList and LazyGrid

This module introduces turnkey Compose components for offset-based pagination, including \PaginatedLazyColumn\, \PaginatedLazyRow\, \PaginatedLazyVerticalGrid\, \PaginatedLazyHorizontalGrid\, and their staggered grid counterparts. These composables automatically bind the paginator's prefetch controller to the list's scroll state, handle scroll-driven prefetching, and provide scroll-anchor-safe loading indicators to prevent list jumping. Additionally, a low-level \paginated\ DSL is provided for \LazyList\ and \LazyGrid\ scopes, allowing developers to manually wire pagination into custom list implementations while automatically tracking header and footer counts for accurate prefetch calculations.

paginator-compose-offset · high confidence

Scroll position preservation and reactive error handling for Android View bindings

The paginator-view-core module now supports preserving RecyclerView scroll positions across configuration changes and process death, mirroring the behavior available in the Compose suite. This is achieved through a new \RecyclerViewScrollSnapshotRegistry\ that stores LayoutManager state snapshots, integrated into the \ScrollBinding\ interface via \saveScrollState\ and \restoreScrollState\ methods. Additionally, a new \PrefetchErrorChannel\ class provides a reactive, Flow-based mechanism for handling prefetch errors, replacing synchronous callbacks to allow for better lifecycle-aware error surfacing in the UI.

paginator-view-core · high confidence

Removals

Paginator module removed from project

The \paginator\ module has been completely deleted from the codebase. This removal includes the core \Paginator.kt\ implementation, associated unit and instrumented tests, and build configuration files such as \.gitignore\ and \proguard-rules.pro\. Users will no longer have access to the pagination library or its features.

paginator · high confidence

Behavioural changes

Demo app replaces random network simulation with deterministic, user-controlled load choices

The demo application now uses a \LoadController\ to pause page loads and present a dialog where the user explicitly selects the backend response (Full, Incomplete, Empty, or Error), replacing the previous random behavior. This allows for reproducible testing of pagination scenarios. The UI has been updated with a new Material 3 Scaffold, a control panel, and an inspector bottom sheet to display pagination state details. Additionally, the \MainViewModel\ now persists and restores paginator state across process death using \SavedStateHandle\ and JSON serialization.

app/src · high confidence

Offset paginator introduces automatic window re-anchoring and navigation event emissions

The offset-based paginator now automatically re-anchors the visible context window after a refresh or data mutation (such as element removal) that would otherwise leave the UI on a blank or stale page range. Additionally, the paginator now emits navigation events via a dedicated flow, allowing UI layers to react to bookmark jumps (e.g., by scrolling the list to the new position) regardless of where the navigation was triggered.

paginator-offset/src/commonMain · high confidence

Scroll position preservation and improved edge indicators in Paginator

The paginator now preserves the user's scroll position when navigating away from and back to a paginated screen, and when the app process is killed and restored. This is achieved through new core composables (\BindLazyListScrollPreservation\, \BindLazyGridScrollPreservation\, \BindLazyStaggeredGridScrollPreservation\) that save the scroll state to an in-memory registry and, optionally, to Compose's \rememberSaveable\ for process-death survival. Additionally, the \PaginatorScrollEdgeIndicators\ composable has been redesigned to prevent visual blinking by keeping the lazy viewport size constant and placing loading/error indicators outside the scroll anchor. It also now supports rendering boundary errors (e.g., failed page loads) at the start or end of the list, allowing users to retry without causing the list to jump.

paginator-compose-core · high confidence

Test coverage

Cursor paginator test suite added; Offset paginator test suite expanded with regression and edge-case coverage.

Dependencies

Gradle wrapper updated to version 9.4.1

The Gradle wrapper configuration has been upgraded from version 8.2 to 9.4.1. This change ensures that the project uses the newer Gradle distribution for builds, which may include performance improvements, new features, and compatibility updates associated with the Gradle 9.x release line.

gradle · high confidence

Migrated to Gradle Version Catalogs and modularized Paginator into multiplatform artifacts

The project has been refactored to use Gradle Version Catalogs (defined in \gradle/libs.versions.toml\) for centralized dependency management, replacing hardcoded version strings in build scripts. The monolithic \paginator\ module has been split into distinct, independently publishable modules: \paginator-core\, \paginator-offset\, \paginator-cursor\, \paginator-view-core\, \paginator-view-offset\, \paginator-view-cursor\, \paginator-compose-core\, \paginator-compose-offset\, \paginator-compose-cursor\, and a \paginator-bom\ for alignment. These modules are now built as Kotlin Multiplatform libraries targeting Android, iOS, JVM, JS, and Wasm, with the Android application updated to depend on the new \paginator-offset\ module and use the Compose BOM.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

How this codebase got here

Score

  • CAI 61 → 54 (-6.8)
  • Rubric changed (rubric-2026.10.1 → rubric-2026.10.5) — scores are not directly comparable.

Lenses

  • Code Health 91 → 93 (+2.2)
  • Architecture 98 → 98 (+0.0)
  • Maturity 66 → 41 (-24.2)
  • Readiness 46 → 47 (+1.2)
  • Security 77 → 77 (+0.0)
  • Performance 78 → 78 (+0.0)

Resolved (250)

  • Documentation: written for insiders (docs/8. logger.md)
  • Dual API for prefetch configuration. Users can configure prefetch either via the high-level bindPrefetchToRecyclerView extension (which handles lifecycle and RecyclerView attachment) or via prefetchController extension (which returns a controller object). The bindPrefetchToRecyclerView method internally likely creates a controller, but exposing both allows for inconsistent configuration paths. If bindPrefetchToRecyclerView is the intended high-level API, the lower-level prefetchController should be internal or clearly marked as advanced usage to avoid confusion about which one to use.
  • Duplicate intent across modules with different underlying types. The paginator-view-offset and paginator-view-cursor modules expose identical top-level extension functions (bindPaginated, bindToRecyclerView, etc.) that differ only by the generic type constraints (Offset vs Cursor). This forces users to import from different packages for conceptually identical UI binding operations, increasing cognitive load and import complexity.
  • Inconsistent removal semantics and naming. MutablePaginator has removeState (removes a whole page) and removeElement (removes a specific item by index). However, PaginatorCrudExtKt also has removeElement but it takes a predicate. The naming collision between MutablePaginator.removeElement (index-based) and PaginatorCrudExtKt.removeElement (predicate-based) is confusing. Additionally, removeState is a low-level cache operation, while removeElement is a data operation; mixing these in the same class without clear distinction between 'cache management' and 'data manipulation' is inconsistent.
  • Outdated (compile): com.github.ben-manes.caffeine:caffeine
  • Outdated (compile): com.google.accompanist:accompanist-drawablepainter
  • Outdated (compile): com.google.api.grpc:proto-google-common-protos
  • Outdated (compile): com.google.auto:auto-common
  • Outdated (compile): com.google.code.gson:gson
  • Outdated (compile): com.google.crypto.tink:tink
  • Outdated (compile): com.google.dagger:dagger
  • Outdated (compile): com.google.errorprone:error_prone_annotations
  • Outdated (compile): com.google.guava:failureaccess
  • Outdated (compile): com.google.guava:guava
  • Outdated (compile): com.google.j2objc:j2objc-annotations
  • Outdated (compile): com.google.jimfs:jimfs
  • Outdated (compile): com.google.protobuf:protobuf-java
  • Outdated (compile): com.google.protobuf:protobuf-java-util
  • Outdated (compile): com.google.protobuf:protobuf-kotlin
  • Outdated (compile): com.squareup.okhttp3:okhttp
  • …and 230 more

New (8)

  • Dependency hygiene PARTLY measured — Maven/Gradle declarations read, no dependency graph resolved
  • Duplicate intent across modules with different type parameters. The paginator-view-offset and paginator-view-cursor modules expose identical extension functions named bindPaginated but for different paginator types (Offset vs Cursor). This forces users to import from different packages for conceptually identical operations, increasing cognitive load and import complexity.
  • Duplicate intent across modules. Similar to bindPaginated, bindToRecyclerView exists in both offset and cursor view modules with identical signatures relative to their respective paginator types. This creates redundant API surface area.
  • Duplicate intent across modules. bindPrefetchToRecyclerView is duplicated in both offset and cursor view modules.
  • Inconsistent mutation API. MutablePaginator has setElement and addElement as direct methods, while Paginator (immutable) exposes these via extension functions in PaginatorCrudExtKt. However, MutablePaginator also has replaceAllElements and addAllElements, while the extension functions provide updateAll, updateWhere, etc. The naming and grouping of CRUD operations differ between the mutable class and the extension functions for the immutable class.
  • Redundant query methods. Both Paginator and PagingCore expose contains(page: Int) and get(page: Int). Since PagingCore is a property of Paginator, users can access the core directly, but exposing the same methods on both levels without clear delegation semantics is inconsistent.
  • Redundant state management methods. Paginator exposes saveState and restoreState, while its internal PagingCore also exposes identical saveState and restoreState methods. Since Paginator delegates to PagingCore, exposing both creates confusion about which layer should be used for serialization. The Paginator level likely wraps the PagingCore state, but the API surface suggests two independent state mechanisms.
  • Workflow token permissions not restricted (.github/workflows/publish.yml)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Survey your own repository

jamal-wia/Paginator was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.

About this page

  • The score is its most recent published measurement, taken on 22 October 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
  • Measured at commit c31cac0831f33d4654ce4c4d65cd297653cddc76 — the exact code this score is about.
  • Scored under rubric-2026.10.5 — the same rubric and the same method as every other entry in this index.
  • Measured by watchdog.canine.dev using codehealth-analyzer measure-2026.10.3+preprod-fddbc92cb8df.