Implements The ELM Architecture, standardizing typed sync/async event handling, state/effect/command modeling, reducer+actor flow, and deterministic, testable state mutations via Modifier/ReducerResult.
GELM is a Kotlin Multiplatform (KMP) library for the popular presentation approach The ELM Architecture (TEA).
Targets: Android, iOS, JVM.
The library standardizes the work with sending and processing synchronous and asynchronous events. All inputs and outputs to library are strictly defined, which makes it easier to develop and test.
Version: 2.0.0.
Transitive dependency: org.jetbrains.androidx.lifecycle:lifecycle-viewmodel (KMP ViewModel).
Minimum Kotlin 2.1.x; AGP 8.x. Android: compileSdk/targetSdk 36, minSdk 23. For Compose projects
with Kotlin 2.0+,
the Compose Compiler plugin
is required in app modules.
When conflicting with androidx.lifecycle in your app (e.g. a different ViewModel version), you
can exclude GELM’s transitive dependency on lifecycle and add the desired version manually:
implementation("io.github.gymbay:gelm:2.0.0") {
exclude(group = "org.jetbrains.androidx.lifecycle", module = "lifecycle-viewmodel")
}
// then add your preferred version explicitly if needed
implementation("org.jetbrains.androidx.lifecycle:lifecycle-viewmodel:...")
Library is published to Maven Central. Add Maven Central to your settings.gradle.kts:
pluginManagement {
repositories {
mavenCentral()
google() // for Android projects
}
}
dependencyResolutionManagement {
repositories {
mavenCentral()
google() // for Android projects
}
}
Then add the dependency in your module's build.gradle.kts:
implementation("io.github.gymbay:gelm:2.0.0") — Gradle will resolve the Android
variant.io.github.gymbay:gelm:2.0.0 — use the iOS source set of the
library.implementation("io.github.gymbay:gelm:2.0.0") — JVM variant.Example (Android app):
dependencies {
implementation("io.github.gymbay:gelm:2.0.0")
}
This guide helps you to understand how library works.
Library works with 5 generic types, some types may be optional. Optional types can be defined as Kotlin Nothing type.
All types applied in GelmStore.
Gelm works with 4 main and 2 additional components. In main components only 2 required and others optional.
Minimum work configuration required GelmStore and GelmExternalReducer.
Central entity for GELM architecture. Holder for architecture components. Responsible for coordinate
flow of external and internal events. Inherited from ViewModel (KMP:
org.jetbrains.androidx.lifecycle:lifecycle-viewmodel).
import io.github.gymbay.gelm.utils.GelmStore
// Minimum configuration
GelmStore(
initialState = ExampleState(),
externalReducer = ExampleExternalReducer()
)
You can pass Events from UI to GelmStore using sendEvent(event: Event) function. All that
event
will be handled by GelmExternalReducer.
OutlinedTextField(
onValueChange = {
store.sendEvent(ExampleEvent.TypeText(it))
}
)
And then you can observe changes in State subscribed on state: StateFlow<State>.
val state by store.state.collectAsStateWithLifecycle()
OutlinedTextField(
value = state.editField,
onValueChange = {
store.sendEvent(ExampleEvent.TypeText(it))
}
)
At the end you can use effect: Flow<Effect> to observe one-shot events.
// A little life-hack to simplify observing in Compose
@Composable
fun <T> CollectEffect(
effect: Flow<T>,
context: CoroutineContext = EmptyCoroutineContext,
block: (T) -> Unit
) {
LaunchedEffect(key1 = Unit) {
effect.onEach(block).flowOn(context).launchIn(this)
}
}
CollectEffect(store.effect) { effect ->
(effect) {
ExampleEffect.NavigateToScreen -> {
Toast.makeText(context, , Toast.LENGTH_LONG).show()
}
}
}
Reducer is an entity responsible for handling external events (UI or another GelmStore).
The reducer is a pure function, and therefore it should be stateless. Adding stored properties is a bad practice.
To define your external reducer you can inherit GelmExternalReducer abstract class
and override processEvent(currentState: State, event: Event)
or/and processInit(currentState: State) functions.
And then pass reducer to GelmStore
import io.github.gymbay.gelm.utils.GelmStore
GelmStore(
initialState = ExampleState(),
externalReducer = ExampleExternalReducer()
)
Use Modifier in override functions to produce new state, effects and commands. As a result of
reducer work will be produced ReducerResult data class. More detailed
in Modifier and ReducerResult section.
On every invoke GelmStore passed actual current state and event to reducer. currentState is
immutable, state mutations accumulates in Modifier.
Optional entity responsible for handling async or heavy computing commands from reducers. For example, request to server or database. Component use Flow to publish results with InternalEvent type.
To define your Actor you can inherit GelmActor abstract class and
override suspend execute(command: Command): Flow<InternalEvent> function.
For example:
import io.github.gymbay.gelm.GelmActor
class : <>() {
: Flow<ExampleInternalEvent> = flow {
(command) {
ExampleCommand.StartLoading -> {
delay(seconds)
list = mutableListOf<String>()
(i .Random.nextInt(, )) {
list.add()
}
emit(ExampleInternalEvent.LoadedData(list))
}
}
}
}
By default all commands executes in viewModelScope with Dispatchers.Default. If you need another
context use withContext() function.
As a result of actor work GelmStore received flow of InternalEvent.
Optional entity. Internal reducer an entity responsible for handling internal events
from GelmActor. Must be stateless.
In the sense of GelmInternalReducer is an analog of GelmExternalReducer, but it works only with
internal events.
To define your internal reducer you can inherit GelmInternalReducer abstract class and
override processInternalEvent(currentState: State, internalEvent: InternalEvent) function.
class ExampleInternalReducer :
GelmInternalReducer<ExampleInternalEvent, ExampleState, ExampleEffect, ExampleCommand>() {
override fun Modifier<ExampleState, ExampleEffect, ExampleCommand>.processInternalEvent(
currentState: ExampleState,
internalEvent: ExampleInternalEvent
) {
when (internalEvent) {
is ExampleInternalEvent.LoadedData -> TODO()
}
}
}
Using GelmInternalReducer make sense only with GelmActor, so store defining will be looks like:
GelmStore(
initialState = ExampleState(),
externalReducer = ExampleExternalReducer(),
actor = ExampleActor(),
internalReducer = ExampleInternalReducer()
)
On every invoke GelmStore passed actual current state and internal event to
reducer. currentState is
immutable, state mutations accumulates in Modifier.
Modifier and ReducerResult is a core classes for reducers used in processing events functions.
Modifier provides functions for state changing, produce effects, commands, events to subscribed
stores and cancel long work commands.
As a result of Modifier work always be ReducerResult. ReducerResult contains all state changes
and produced commands, events and etc.
Let's take a closer look at what functions the Modifier provides and what its typical use looks
like:
state(modify: State.() -> State)Function for state modifications. Function provides State lambda scope and expect new state on
return.
Typical approach for state modification in Kotlin is using copy() function on data classes.
Example of use:
data class State(val loadedCount: Int = 0)
class TestExternalReducer : <>() {
{
newLoadedCount = currentState.loadedCount +
state { copy(loadedCount = newLoadedCount) }
}
}
reducerResult = TestExternalReducer().processInit(State())
assertEquals(State(loadedCount = ), reducerResult.state)
effect(newEffect: Effect)Function for producing new Effects after reducer work. Each time the function is called,
the Modifier adds a new value to the internalEffects mutable list.
class TestExternalReducer : GelmExternalReducer<Nothing, Unit, Effect, Nothing>() {
override fun Modifier<Unit, Effect, Nothing>.processInit(currentState: Unit) {
effect(Effect.Alert)
effect(Effect.Toast)
effect(Effect.Navigation)
}
}
val reducerResult = TestExternalReducer().processInit(Unit)
assertEquals(3, reducerResult.effects.size)
command(newCommand: Command)Function for producing async commands to GelmActor. Each time the function is called,
the Modifier adds a new value to the internalCommands mutable list.
class TestExternalReducer : GelmExternalReducer<Nothing, Unit, Nothing, Command>() {
override fun Modifier<Unit, Nothing, Command>.processInit(currentState: Unit) {
command(Command.LoadClient)
command(Command.LoadProducts)
}
}
val reducerResult = TestExternalReducer().processInit(Unit)
assertEquals(2, reducerResult.commands.size)
cancelCommand(command: Command)Function for cancelling long work command in GelmActor. For example, long computation than might
be cancelled when user tap Cancel button.
class TestExternalReducer : GelmExternalReducer<Nothing, Unit, Nothing, Command>() {
override fun Modifier<Unit, Nothing, Command>.processInit(currentState: Unit) {
cancelCommand(Command.LoadClient)
cancelCommand(Command.LoadProducts)
}
}
val reducerResult = TestExternalReducer().processInit(Unit)
assertEquals(2, reducerResult.cancelledCommands.size)
event(event: ObserverEvent)Function for sending untyped events that might be handled by subscribed GelmStore. Use when you
need make interaction with another GelmStore.
GelmStore provides some additional functionality to debugging and state handling.
If you need your State to survive the system process death event,
use GelmSavedStateHandler
interface.
GelmSavedStateHandler interface provides two functions:
saveState(state: State) for saving state into long living storage. Invokes on each state
changing. Works on main thread;restoreState(initialState: State): State? for restoring state from long living storage. Works on
init phase of GelmStore on main thread.val savedStateHandler = object : GelmSavedStateHandler<ExampleState> {
override fun saveState(state: ExampleState) {
TODO()
}
override fun restoreState(initialState: ExampleState): ExampleState? {
TODO()
}
}
GelmStore(
initialState = ExampleState(),
externalReducer = ExampleExternalReducer(),
actor = ExampleActor(),
internalReducer = ExampleInternalReducer(),
savedStateHandler = savedStateHandler
)
For debugging might be useful
using GelmLogger.
GelmLogger provides log(eventType: EventType, message: String) function for log GelmStore
lifecycle events.
You can use standard log output or analytics in overrides of log function.
Example of use:
GelmStore(
logger = { eventType, message -> println("$eventType = $message") }
)
Now GelmLogger supports
10 EventTypes. Name of event
determine what will be logged.
All components in Gelm covered tests and no need to retest on user side.
On user side might be tested custom architecture components inherited from:
The library offers a standardized approach to testing architectural components.
Because GelmExternalReducer stateless component it might be tested like pure function with
determined inputs and outputs.
Typical test looks like:
@Test
fun testReloadEvent() {
val inputText = "Text"
val reducer = ExampleExternalReducer()
val result = reducer.startProcessing(
state = ExampleState(editField = inputText),
event = ExampleEvent.Reload
)
// state
assertEquals(
ExampleState(
editField = inputText,
isLoading =
),
result.state
)
assertTrue(result.effects.isEmpty())
assertTrue(result.commands.size == )
assertEquals(
ExampleCommand.StartLoading(text = inputText),
result.commands.first()
)
assertTrue(result.cancelledCommands.isEmpty())
assertTrue(result.observersEvents.isEmpty())
}
Each test might be invoke startProcessing function in reducer with specific Event and State.
And then assert ReducerResult output that contains five standardized variables.
That approach guarantee that test will be stable and check all logic.
Additional approach for stable test is using default values in State.
This ensures that if you add a new value to State, then most of the tests will not require
correction.
Testing approach for GelmInternalReducer is the same as for GelmExternalReducer.
GelmActor might be stateless component with external dependencies (for example, use cases,
repositories and etc).
All actor external dependencies must be replaced by fakes.
So, typical test on GelmActor will be looks like:
import kotlinx.coroutines.flow.toList
import kotlinx.coroutines.test.runTest
@Test
fun testStartLoading() = runTest {
val inputText = "test"
val sut = ExampleActor()
val events = mutableListOf<ExampleInternalEvent>()
sut.execute(ExampleCommand.StartLoading(text = inputText)).toList(events)
assertEquals(1, events.size)
val items = (events[0] ExampleInternalEvent.LoadedData).list
assertTrue(items.isNotEmpty())
assertTrue(items.all { it.contains(inputText) })
}
We need to invoke execute() with specific variant of Command (input) and then check all produced
events from Flow (output).
Thus, you need to consistently check all Commands and resulting events for a full covered test.
The project includes an iOS demo module iosDemo that consumes GELM on iOS (Kotlin/Native). It
shows the same usage pattern as the Android app: store creation, state/effect subscription, sending
events.
Requirements: Xcode, macOS, Kotlin/Native toolchain (installed by Gradle).
Run: Build iOS framework: ./gradlew :iosDemo:linkReleaseFrameworkIosArm64 (device) or
:iosDemo:linkReleaseFrameworkIosSimulatorArm64 (simulator). To run on simulator/device, use Xcode
with the iOS app target.
To verify all targets and the app build:
# Library: all targets
./gradlew :gelm:compileReleaseKotlinAndroid :gelm:compileKotlinJvm :gelm:compileKotlinIosArm64 :gelm:compileKotlinIosX64
# Unit tests (Android)
./gradlew :gelm:testDebugUnitTest :gelm:testReleaseUnitTest
# Android app
./gradlew :app:assembleDebug
# iOS demo (framework)
./gradlew :iosDemo:linkReleaseFrameworkIosArm64
Full build: ./gradlew :gelm:build :app:assembleDebug
import io.github.gymbay.gelm.reducers.GelmExternalReducer
import io.github.gymbay.gelm.reducers.Modifier
class ExampleExternalReducer :
GelmExternalReducer<ExampleEvent, ExampleState, ExampleEffect, ExampleCommand>() {
// Handle GelmStore init.
// For example, to mutate state on screen start or start loading.
override fun Modifier<ExampleState, ExampleEffect, ExampleCommand>.processInit(currentState: ExampleState) {
TODO()
}
// Handle events from UI or another observed GelmStore
override fun Modifier<ExampleState, ExampleEffect, ExampleCommand>.processEvent(
currentState: ExampleState,
event: ExampleEvent
) {
when (event) {
ExampleEvent.Reload -> TODO()
is ExampleEvent.TypeText -> TODO()
is ExampleEvent.Next -> TODO()
}
}
}
// Reducer that will be sending event to another store
private class InitialExternalReducer :
GelmExternalReducer<InitialEvent, Unit, Nothing, Nothing>() {
override fun Modifier<Unit, Nothing, Nothing>.processEvent(
currentState: Unit,
event: InitialEvent
) {
when (event) {
is InitialEvent.StartDelegation -> event(DelegationEvent.Data(title = event.title))
}
}
}
// Reducer that will be receiving event from another store
private class DelegationExternalReducer :
GelmExternalReducer<DelegationEvent, DelegationState, Nothing, Nothing>() {
override fun Modifier<DelegationState, Nothing, Nothing>.processEvent(
currentState: DelegationState,
event: DelegationEvent
) {
when (event) {
is DelegationEvent.Data -> state { copy(title = event.title) }
}
}
}
// Implementation logic
val initialStore = GelmStore<Unit, Nothing, InitialEvent, Nothing, Nothing>(
initialState = Unit,
externalReducer = InitialExternalReducer(),
commandsDispatcher = StandardTestDispatcher(testScheduler)
)
val delegationStore = GelmStore<DelegationState, Nothing, DelegationEvent, Nothing, Nothing>(
initialState = DelegationState(),
externalReducer = DelegationExternalReducer(),
)
// Subscribe delegationStore to initialStore
initialStore.subscribe(delegationStore)
assertNull(delegationStore.state.first().title)
val newTitle = "initial"
initialStore.sendEvent(InitialEvent.StartDelegation(title = newTitle))
advanceUntilIdle()
assertEquals(DelegationState(title = newTitle), delegationStore.state.first())
Surfaced from shared tags and platforms — no rankings paid for.