Facilitates declarative network communication, ensuring up-to-date client data while conserving server resources. Supports sophisticated UX patterns, automatic data loading, caching, request deduplication, and integrates with ViewModel and Decompose.
While libraries such as Retrofit and Kotlin Serialization help to make network requests, Replica takes on another challenges.
It is important to keep data up to date on a client. But we shouldn't call network requests too frequently to not waste server resources.
Modern Android applications need sophisticated UX-patterns such as stale-while-revalidate, pull-to-refresh, pagination and optimistic updates. Developers have to implement it over and over again without the right tool at hand.
Classical imperative approach to networking is complex and error-prone. It is hard to achieve desired behavior by manually orchestrating individual network calls.
To summarize, Replica helps to:
Replica provides:
dependencies {
def replicaVersion = '1.8.0-alpha'
// Basic usage
implementation "com.github.aartikov:replica-core:$replicaVersion"
// Automatic reaction on changes of network connection status
implementation "com.github.aartikov:replica-android-network:$replicaVersion"
// Transforming and combining replicas
implementation "com.github.aartikov:replica-algebra:$replicaVersion"
// Integration with ViewModel library
implementation "com.github.aartikov:replica-view-model:$replicaVersion"
// Integration with Decompose library
implementation "com.github.aartikov:replica-decompose:$replicaVersion"
// Debug tool
debugImplementation "com.github.aartikov:replica-devtools:$replicaVersion"
releaseImplementation "com.github.aartikov:replica-devtools-noop:$replicaVersion"
}
The library is based on a concept called data replication. The idea is simple. There is some data on a server. A client needs this data. Replica automatically represent server data on a client side and keeps it in sync.
Replica provides data replication primitives called replicas. Each replica targets some chunk of data on a server and replicates it on a client.
And the last concept is replica observers. Replica observers are required to display data on UI. An observer connects to a replica and transfers its state to UI. A replica knows how many observers it has and performs complex behaviour based on this information.
Typical code with Replica looks like that:
class PokemonRepository(
replicaClient: ReplicaClient,
api: PokemonApi
) {
val pokemonsReplica: Replica<List<Pokemon>> = replicaClient.createReplica(
name = "pokemons",
settings = ReplicaSettings(staleTime = 1.minutes),
fetcher = {
api.getPokemons().toDomain()
}
)
}
class PokemonListViewModel(
private val pokemonsReplica: Replica<List<Pokemon>>,
errorHandler: ErrorHandler
) : ViewModel(), Activable by activable() {
val pokemonsState = pokemonsReplica.observe(this, errorHandler)
}
viewLifecycleOwner.lifecycleScope.launch {
repeatOnLifecycle(Lifecycle.State.STARTED) {
viewModel.pokemonsState.collect { state ->
val (loading, data, error) = state
when {
data != null -> {
// show a list of pokemons
}
loading -> {
// show a fullscreen progress
}
error != null -> {
// show a fullscreen error
}
}
}
}
}
Replica has a debug tool integrated to Android Studio. It allows to monitor replicas, their states and observers.
Of course, dark theme is supported.
Replica Documentation - a website with detailed documentation (WIP).
Artur Artikov
telegram - @aartikov, email - a.artikov@gmail.com
To Egor Belov for the help with Replica DevTools and Unit tests.
The MIT License (MIT)
Copyright (c) 2023 Artur Artikov, Egor Belov
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.
Surfaced from shared tags and platforms — no rankings paid for.