Skip to content
mradzinskiPublic

About

An event router for MVVM screens on Kotlin Multiplatform. The UI sends events, each event goes to its own small handler class, and the screen's state and one-time effects come back as flows. It runs on Android, iOS, Desktop and Web from common code.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Maven Central Build Coverage

Eventus

An event router for MVVM screens on Kotlin Multiplatform. The UI sends events, each event goes to its own small handler class, and the screen's state and one-time effects come back as flows. It runs on Android, iOS, Desktop and Web from common code.

  • One event, one handler class, one test class: a screen with fifty events is fifty small files, not one view model with fifty functions
  • Four ways to run a handler when its event arrives again: at once, latest only, in order, or ignore while busy
  • The view model extends nothing from this library: it delegates to a router
  • State is one immutable value in a StateFlow; effects are delivered once, and kept until something collects them
  • Handlers get the screen's state from the router, so no dependency-injection scope can be set up wrong
  • A handler that fails does not stop the screen, and every failure reaches one place
  • Optimistic updates in one call: show the result at once, put it back if the work fails
  • Depends only on kotlinx.coroutines: no Compose, no lifecycle, no dependency-injection library
  • Safe to call from any thread

Contents

Before you begin

  • Kotlin 2.4.21 or newer. The library is built with it; older compilers are not supported.
  • kotlinx-coroutines 1.11.0 or newer, which the library brings in by itself.
  • Targets: android (minSdk 23), jvm, iosArm64, iosSimulatorArm64, iosX64, js, wasmJs.
  • The examples use the multiplatform androidx.lifecycle ViewModel and Compose, because that is how most apps will use the library. Neither is required.

Install

// build.gradle.kts of the module that holds your screens
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.github.mradzinski:eventus:1.0.0-rc01")
        }
    }
}

That is all the library needs. One more step is optional, and recommended.

Recommended: the build-time check

eventus-ksp is a KSP processor. With it, an event that has no handler fails the build; without it, that event throws when it is sent. It runs while your app is built and is never part of the app.

Add the KSP plugin, 2.3.12 or newer, and the processor once for every target of the module:

// build.gradle.kts of the module that holds your screens
plugins {
    id("com.google.devtools.ksp") version "2.3.14"
}

dependencies {
    add("kspAndroid", "io.github.mradzinski:eventus-ksp:1.0.0-rc01")
    add("kspJvm", "io.github.mradzinski:eventus-ksp:1.0.0-rc01")
    add("kspIosArm64", "io.github.mradzinski:eventus-ksp:1.0.0-rc01")
    add("kspIosSimulatorArm64", "io.github.mradzinski:eventus-ksp:1.0.0-rc01")
}

A configuration is named after its target: ksp and the target's name with a capital first letter. In a module with a single platform, the one line is ksp("io.github.mradzinski:eventus-ksp:1.0.0-rc01").

If you use Koin, the processor can also write the Koin module of your handlers. That takes one more artifact, eventus-koin, and one annotated property. See handlers checked and wired by the build for both.

Quick start

1. Describe the screen. Its state, the events the UI can send and the effects the UI must perform, each as a sealed type or a data class of your own.

sealed interface CounterEvent : UiEvent {

    data object OnIncrementClick : CounterEvent
    data object OnSaveClick : CounterEvent
}

data class CounterUiState(val count: Int = 0) : UiState

sealed interface CounterEffect : UiEffect {

    data object Saved : CounterEffect
    data class ShowFailure(val reason: FailureReason) : CounterEffect
}

2. Write one handler per event. A handler takes what it really depends on in its constructor. The screen's state and effects come in with each call, as the store.

class OnIncrementClickHandler : EventHandler<OnIncrementClick, CounterUiState, CounterEffect> {

    override val eventType = OnIncrementClick::class

    override suspend fun handle(event: OnIncrementClick, store: ScreenStore<CounterUiState, CounterEffect>) {
        store.update { it.copy(count = it.count + 1) }
    }
}

class OnSaveClickHandler(
    private val counters: CounterRepository,
) : EventHandler<OnSaveClick, CounterUiState, CounterEffect> {

    override val eventType = OnSaveClick::class
    override val strategy = DispatchStrategy.DropIfBusy   // a second tap while saving is ignored

    override suspend fun handle(event: OnSaveClick, store: ScreenStore<CounterUiState, CounterEffect>) {
        counters.save(store.current.count)   // throws when it fails: the screen's ErrorHandler takes it
        store.emit(CounterEffect.Saved)
    }
}

Every event needs exactly one handler. With eventus-ksp the build tells you when one is missing: add an event to CounterEvent and forget its handler, and the module no longer compiles.

3. Give the router to the UI through your view model. The view model has no logic. It delegates state, effects and onEvent to the router.

class CounterViewModel(
    handlers: Collection<EventHandler<*, CounterUiState, CounterEffect>>,
    scope: CoroutineScope = routerScope(),
) : ViewModel(scope),
    EventRouter<CounterEvent, CounterUiState, CounterEffect> by EventRouter(
        scope = scope,
        initialState = CounterUiState(),
        handlers = handlers,
        errorHandler = { _, error, store -> store.emit(CounterEffect.ShowFailure(error.toFailureReason())) },
    )

4. Use it from the UI. Draw the state, send events, perform effects.

@Composable
fun CounterRoute(viewModel: CounterViewModel) {
    val state by viewModel.state.collectAsStateWithLifecycle()

    LaunchedEffect(viewModel) {
        viewModel.effects.collect { effect ->
            when (effect) {
                is CounterEffect.Saved -> { /* show a confirmation */ }
                is CounterEffect.ShowFailure -> { /* show why */ }
            }
        }
    }

    CounterScreen(
        state = state,
        onEvent = viewModel::onEvent,
    )
}

Documentation

Each topic has a page of its own in docs/. They are listed with what most apps need first.

Guide What it covers
Key concepts The types of the library and what each one is, and the three rules that follow from how they fit together.
Dispatch strategies What happens when an event arrives again while its handler is still running, and what the router keeps for each strategy.
Dependency injection Wiring handlers with Koin, with a compile-time container, or by hand.
Handlers checked and wired by the build The eventus-ksp processor: the missing-handler check, the generated Koin module, and projects with several modules.
Failures Where a handler's exception goes, and how to turn it into something the UI can show.
Work that keeps running Handlers that never return, such as one that collects a flow, and how long they last.
Testing Testing a handler, a view model, and that every event has a handler.
Effect or state? How to decide whether something is an effect or part of the state.
Navigation Navigating as an effect that carries only an id.
Debouncing Waiting until the user has stopped typing before doing the expensive part.
Optimistic updates Showing a result at once and putting it back if the work fails.
Reaching another screen How one screen affects another without an event bus.
The coroutine scope Which scope the router runs in, who cancels it, and threads.
Logging events Logging every event of a screen with a router that wraps another.
Where Eventus sits in your app Which modules of an app depend on Eventus and which never do.
What Eventus does not do The limits of the library, stated plainly.
Project layout The modules of this repository, and how to run the sample, the checks and the formatter.

Changelog

See CHANGELOG.md.

License

Eventus is free to use, including in commercial apps, under the Apache License 2.0. The full text is in LICENSE.

If you ship Eventus in an app, credit it. Include the contents of NOTICE, which names the library and links to this repository, wherever your app lists its third-party software: an "open source licenses" screen, an about page or the documentation. The license requires this of anything that redistributes the library (section 4).

Copyright 2026 Matias Radzinski

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

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

About

An event router for MVVM screens on Kotlin Multiplatform. The UI sends events, each event goes to its own small handler class, and the screen's state and one-time effects come back as flows. It runs on Android, iOS, Desktop and Web from common code.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages