Mutator
2.0.0indexedLibrary aids in managing state using unidirectional data flow principles, offering tools to mutate state over time via `StateMutator` implementations. Supports MVVM and MVI patterns.
68
Stars
1
Used by
dependents
—
Health
/ 100
Mutator
Please note, this is not an official Google repository. It is a Kotlin multiplatform experiment that makes no guarantees about API stability or long term support. None of the works presented here are production tested, and should not be taken as anything more than its face value.
Introduction
Mutator is a Kotlin multiplatform library that provides a suite of tools that help with producing state while following unidirectional data flow (UDF) principles. More specifically it provides implementations of the paradigm newState = oldState + Δstate.
Where StateHolders are defined as:
interface StateHolder<State : Any> {
val state: State
}
and Δstate represents state changes over time and is expressed in Kotlin with the type:
typealias Mutation<State> = State.() -> State
At the moment, there are two implementations:
fun <State : Any> CoroutineScope.stateFlowMutator(
initialState: State,
started: SharingStarted,
inputs: List<Flow<Mutation<State>>>
): StateHolder<StateFlow<State>>
and
fun <Action : Any, State : Any> CoroutineScope.actionStateFlowMutator(
initialState: State,
started: SharingStarted,
inputs: List<Flow<Mutation<State>>>,
actionTransform: (Flow<Action>) -> Flow<Mutation<State>>
): StateHolder<StateFlow<State>>
stateFlowMutator is well suited for MVVM style applications and actionStateFlowMutator for MVI like approaches.
Foreground execution limits
Both implementations enforce that coroutines launched in them are only active as specified by the SharingStarted
policies passed to them. For most UI StateHolders, this is typically SharingStarted.whileSubscribed(duration).
Any work launched that does not fit into this policy (a photo upload for example) should be queued to be run with the
appropriate API on the platform you're working on. On Android, this is WorkManager.
Download
implementation("com.tunjid.mutator:core:version")
implementation("com.tunjid.mutator:coroutines:version")
Where the latest version is indicated by the badge at the top of this file.
Examples and sample code
Please refer to the project website for an interactive walk through of the problem space this library operates in and visual examples.
CoroutineScope.stateFlowMutator
CoroutineScope.stateFlowMutator returns a class that allows for mutating an initial state over time, by providing a List of Flows that contribute to state changes. A simple example follows:
CoroutineScope.actionStateFlowMutator
The actionStateFlowMutator function transforms a Flow of Action into a Flow of State by first
mapping each into a of , and then reducing the into an
initial state within the provided .
The above is typically achieved with the toMutationStream extension function which allows for
the splitting of a source Action stream, into individual streams of each Action subtype. These
subtypes may then be transformed independently, for example, given a sealed class representative of
simple arithmetic actions:
sealed class Action {
abstract val value: Int
data class Add(override val value: Int) : Action()
data class Subtract(override val value: ) : Action()
}
and a State representative of the cumulative result of the application of those Actions:
data class State(
val count: Int = 0
)
A StateFlow Mutator of the above can be created by:
val mutator = scope.actionStateFlowMutator<Action, State>(
initialState = State(),
started = SharingStarted.WhileSubscribed(),
transform = { actions ->
actions.toMutationStream {
when (val action = type()) {
is Action.Add -> action.flow
.map {
mutationOf { copy(count = count + value) }
}
is Action.Subtract -> action.flow
.map {
mutationOf { copy(count = count - value) }
}
}
}
}
)
Non trivially, given an application that fetches data for a query that can be sorted on demand. Its
State and Action may be defined by:
data class State(
val comparator: Comparator<Item>,
val items: List<Item> = listOf()
)
sealed class Action {
data class Fetch(val query: Query) : Action()
data class Sort(val comparator: Comparator<Item>) : Action()
}
In the above, fetching may need to be done consecutively, whereas only the most recently received
sorting request should be honored. A StateFlow Mutator for the above therefore may resemble:
val mutator = scope.actionStateFlowMutator<Action, State>(
initialState = State(comparator = defaultComparator),
started = SharingStarted.WhileSubscribed(),
transform = { actions ->
actions.toMutationStream {
when (val action = type()) {
is Action.Fetch -> action.flow
.map { fetch ->
val fetched = repository.get(fetch.query)
mutationOf {
copy(
items = (items + fetched).sortedWith(comparator),
)
}
}
is Action.Sort -> action.flow
.mapLatest { sort ->
mutationOf {
copy(
comparator = sort.comparator,
items = items.sortedWith(comparator)
)
}
}
}
}
}
)
In the above, by splitting the Action Flow into independent Flows of it's subtypes,
Mutation instances are easily generated that can be reduced into the current State.
A more robust example can be seen in the Me project.
Nuanced use cases
Sometimes when splitting an Action into a Mutation stream, the Action type may need to be
split by it's super class and not it's actual class. Take the following Action and State
pairing:
By default, all 4 Actions will need to have their resulting Flows defined. To help group them
into Flows of their super types, a keySelector can be used:
val actions = MutableSharedFlow<Action>()
actions
.toMutationStream(
keySelector = { action ->
when (action) {
is IntAction -> "IntAction"
is DoubleAction -> "DoubleAction"
}
}
) {
when (val type = type()) {
is IntAction -> type.flow
.map { it.mutation }
is DoubleAction -> type.flow
.map { it.mutation }
}
}
In the above the two distinct keys map to the IntAction and DoubleAction super types allowing
for granular control of the ensuing Mutation stream.
Ultimately a Mutator serves to produce a stream of State from a stream of Actions,
the implementation of which is completely open ended.
License
Copyright 2021 Google LLC
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https:
Unless applicable law agreed to writing, software
distributed under the License distributed an BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
See the License the specific language governing permissions
limitations under the License.