README.md

paging-common

API discrepancies

A core goal of app.cash.paging:paging-common is to have an identical API to that of androidx.paging:paging-common. Unfortunately, there are a few API discrepancies with androidx.paging:paging-common due to limitations in the Kotlin compiler.

Note

Voting on the respective YouTrack issues may improve the likelihood of them being implemented. This could reduce the number of API discrepancies in future releases.

Nested classes have been made top-level classes

Issue reference

https://youtrack.jetbrains.com/issue/KT-34281

Workaround

Use the newly defined top-level classes.

The following table is an exhaustive list of such mappings.

androidx.paging	app.cash.paging
LoadState.NotLoading	LoadStateNotLoading
LoadState.Loading	LoadStateLoading
LoadState.Error	LoadStateError
PagingSource.LoadParams<Key>	PagingSourceLoadParams<Key>
PagingSource.LoadParams.Refresh<Key>	PagingSourceLoadParamsRefresh<Key>
PagingSource.LoadParams.Append<Key>	PagingSourceLoadParamsAppend<Key>
PagingSource.LoadParams.Prepend<Key>	PagingSourceLoadParamsPrepend<Key>
PagingSource.LoadResult.Error<Key, Value>	PagingSourceLoadResultError<Key, Value>
PagingSource.LoadResult.Invalid<Key, Value>	PagingSourceLoadResultInvalid<Key, Value>
PagingSource.LoadResult.Page<Key, Value>	PagingSourceLoadResultPage<Key, Value>
RemoteMediator.MediatorResult	RemoteMediatorMediatorResult
RemoteMediator.MediatorResult.Error	RemoteMediatorMediatorResultError
RemoteMediator.MediatorResult.Success	RemoteMediatorMediatorResultSuccess
RemoteMediator.InitializeAction	RemoteMediatorInitializeAction

Superclass removed for nested classes in commonMain only

Issue reference

https://youtrack.jetbrains.com/issue/KT-27412

Workaround

Unsafe cast the object to the superclass it should be. For example:

val loadState = LoadStateLoading as LoadState

As LoadStateLoading is a subclass of LoadState in every target, such a cast isn't in fact "unsafe". This cast will cause warnings like the following:

> Task compileCommonMainKotlinMetadata
w: /…/src/commonMain/kotlin/Foo.kt: (99, 11): This cast can never succeed

> Task compileKotlinJvm
w: /…/src/commonMain/kotlin/Foo.kt: (99, 11): No cast needed

> Task compileKotlinIosSimulatorArm64
w: /…/src/commonMain/kotlin/Foo.kt: (99, 11): No cast needed

You can safely ignore these warnings, or you can suppress them with @Suppress("CAST_NEVER_SUCCEEDS", "USELESS_CAST", "KotlinRedundantDiagnosticSuppress").

Nested constants have been top-level constants

Issue reference

https://youtrack.jetbrains.com/issue/KT-18856

Workaround

Use the newly defined top-level constants.

The following table is an exhaustive list of such mappings.

androidx.paging	app.cash.paging
PagingConfig.Companion.MAX_SIZE_UNBOUNDED	MAX_SIZE_UNBOUNDED
PagingSource.LoadResult.Page.Companion.COUNT_UNDEFINED	COUNT_UNDEFINED

Missing copy functions for LoadStates, PagingSourceLoadResultPage, and PagingSourceLoadResultError

Issue references

https://youtrack.jetbrains.com/issue/KT-18565

https://youtrack.jetbrains.com/issue/KT-54786

Workaround

Import the copy extension functions via app.cash.paging.copy.

Missing default values

Issue references

https://youtrack.jetbrains.com/issue/KT-54786 (closed as not planned). Based on https://youtrack.jetbrains.com/issue/KT-57614, this may be fixed when the K2 compiler becomes stable.

Workaround

Consult the following table for guidance based on which APIs are being used.

androidx.paging	app.cash.paging
CombinedLoadStates	Use createCombinedLoadStates.
Pager	Use createPager.
PagingConfig	Use createPagingConfig.
PagingData.Companion.empty(LoadStates, LoadStates?)	Pass in the default value yourself.
PagingData.Companion.from(List<T>, LoadStates, LoadStates?)	Pass in the default value yourself.
PagingDataDiffer	Pass in the default value yourself.
PagingLogger.log(Int, String, Throwable?)	Pass in the default value yourself.
PagingSourceLoadResultPage	Use createPagingSourceLoadResultPage.