Обновление Paginator с 3.x до 8.x

repositories {
    maven { setUrl("https://jitpack.io") }
}
dependencies {
    implementation("com.github.jamal-wia:Paginator:3.3.0")
}

repositories {
    mavenCentral() // JitPack больше не нужен
}
dependencies {
    implementation(platform("io.github.jamal-wia:paginator-bom:8.6.2"))
    implementation("io.github.jamal-wia:paginator")           // ядро, обязательно
    implementation("io.github.jamal-wia:paginator-compose")   // опционально — Compose / CMP
    implementation("io.github.jamal-wia:paginator-view")      // опционально — Android Views
}

// 3.3.0
paginator.setPageState(page = 1u, ...)
paginator.bookmarks += BookmarkUInt(page = 5u)
// 8.6.2
paginator.setState(page = 1, ...)
paginator.bookmarks += BookmarkInt(page = 5)

val paginator = Paginator { page: UInt ->
    repo.loadPage(page.toInt()) // возвращает List
}

val paginator = Paginator { page: Int ->
    LoadResult(repo.loadPage(page))
    // или с метаданными API:
    // LoadResult(items, MyMetadata(totalCount = response.total))
}

• Paginator — read-only, только навигация (jump*, goNextPage, goPreviousPage, restart, refresh).
  
• MutablePaginator — наследник, в нём CRUD по элементам, resize, setState.

• com.jamal_aliev.paginator.page.PageState (+ PlaceholderPageState, PaginatorUiState)
  
• com.jamal_aliev.paginator.bookmark.BookmarkInt
  
• com.jamal_aliev.paginator.exception.LockedException.*, FinalPageExceededException, LoadGuardedException
  
• com.jamal_aliev.paginator.load.LoadResult, Metadata
  
• com.jamal_aliev.paginator.cache.PagingCache и стратегии кэша
  
• com.jamal_aliev.paginator.logger.PaginatorLogger

• finalPage: Int — верхняя граница пагинации, кидает FinalPageExceededException (5.1.0). Полезно, когда API сообщает общее число страниц.
  
• loadGuard — колбэк, который может «зарубить» загрузку до сетевого запроса, кидая LoadGuardedException. Заменяет самописные флаги «можно ли сейчас грузить».
  
• Стратегии кэша — LRU / FIFO / TTL / SlidingWindow / Composite через PagingCache. В 3.3.0 единственной ручкой был capacity.
  
• Сериализация состояния — paginator.saveState(...) / restoreState(...) поверх kotlinx.serialization. Заменяет ручной танец «сохрани последние номера страниц в SavedStateHandle» при процесс-смерти.
  
• PaginatorUiState — единый Flow для UI-слоя (loading / data / error / empty), рекомендуется в новом Quick Start вместо ручной сборки snapshot + флагов загрузки.
  
• PlaceholderProgressPage — встроенная поддержка skeleton/shimmer-строк.
  
• PaginatorLogger — pluggable логирование (AndroidLogger, NoOpLogger).
  
• DSL-builder — paginator { … } вместо позиционного конструктора (8.1+).
  
• paginator-compose — автоматический prefetch для LazyColumn / LazyRow / LazyVerticalGrid / LazyVerticalStaggeredGrid. Никаких больше LaunchedEffect + snapshotFlow.
  
• paginator-view — bindPaginated / bindPrefetchToRecyclerView для Android Views.
  
• CursorPaginator/MutableCursorPaginator — параллельный курсорный режим (prev / self / next), под GraphQL connections, чаты и любые API, которые вместо номеров страниц возвращают курсоры (8.3+). Если ваш бэкенд уже умеет курсоры — это строго лучше, чем эмулировать их поверх offset-пагинации.
  
• Dirty pages — трекинг «грязных» страниц для частичной инвалидации вместо сноса всего кэша.

class MainViewModel : ViewModel() {
    private val paginator = Paginator { page: UInt ->
        SampleRepository.loadPage(page.toInt())
    }
    init { viewModelScope.launch { paginator.jumpForward() } }
    override fun onCleared() {
        paginator.release()
        super.onCleared()
    }
}

class MainViewModel : ViewModel() {
    private val paginator = MutablePaginator { page: Int ->
        LoadResult(SampleRepository.loadPage(page))
    }.apply {
        // logger = AndroidLogger()
        // finalPage = 50
    }
    val uiState = paginator.uiState // Flow>
    init { viewModelScope.launch { paginator.jumpForward() } }
    override fun onCleared() {
        paginator.release()
        super.onCleared()
    }
}

• Сначала Gradle. Убрать JitPack, добавить mavenCentral(), перейти на BOM и нужные артефакты.
  
• Импорты. Paginator.PageState.* → com.jamal_aliev.paginator.page.PageState.* и аналогично для остальных переехавших типов (§7).
  
• UInt→Int везде — страницы, закладки, параметры, возвращаемые типы (BookmarkUInt → BookmarkInt).
  
• Обернуть источник данных. source = { … } с List → load = { … } с LoadResult(...).
  
• Сменить тип переменной наMutablePaginator, если вы вызываете какой-нибудь CRUD / setState / resize.
  
• Прогнать переименования из §6 (setPageState→setState, getPageState→getStateOf, ignoreCapacity→isCapacityUnlimited, enforceCapacity→coerceToCapacity, …).
  
• Скомпилировать. Компилятор подсветит остаток (в основном extension-функции, которые раньше были методами).
  
• Проверить runtime-поведение на репрезентативных данных. Контракт страницы теперь page >= 1, 0 означает «ещё не начали»; lock-флаги и исключения живут в пакете exception.
  
• Опционально, но имеет смысл: перейти на uiState, выбрать стратегию PagingCache, подцепить saveState / restoreState, DSL-builder и — если API курсорный — CursorPaginator.

• docs/1. core-concepts.md
  
• docs/3. state.md — новый PaginatorUiState
  
• docs/5. serialization.md — saveState / restoreState
  
• docs/6. caching.md — стратегии кэша
  
• docs/11. dsl-builder.md
  
• docs/13. cursor-pagination.md и docs/14. paginator-vs-cursor.md

• координаты артефакта и переезд на Maven Central + BOM,
  
• UInt → Int для всех номеров страниц,
  
• source: () -> List → load: () -> LoadResult,
  
• разделение на Paginator / MutablePaginator,
  
• партия переименований из 5.0.0,
  
• перепаковка PageState, Bookmark, исключений и кэша.