README.md

May 30, 2026 · View on GitHub

A powerful Kotlin Multiplatform state machine library with clean DSL syntax
and first-class Kotlin Coroutines support

What is KStateMachine?

KStateMachine lets you model complex application logic as a finite state machine or statechart using an expressive Kotlin DSL. It runs on every Kotlin Multiplatform target, integrates seamlessly with Kotlin Coroutines, and has zero mandatory dependencies.

🚀 Quick Start

Animated traffic light

Animated UML statechart — traffic light state machine

// Events
object SwitchEvent : Event

// States
sealed class States : DefaultState() {
    object RedState : States()
    object YellowState : States()
    object GreenState : States(), FinalState  // machine stops here
}

fun main() = runBlocking {
    val machine = createStateMachine(scope = this) {
        addInitialState(RedState) {
            onEntry { println("🔴 Red — stop!") }
            onExit { println("   leaving red") }

            transition<SwitchEvent> {
                targetState = YellowState
                onTriggered { println("   → switching…") }
            }
        }

        addState(YellowState) {
            onEntry { println("🟡 Yellow — get ready") }
            transition<SwitchEvent>(targetState = GreenState)
        }

        addFinalState(GreenState) {
            onEntry { println("🟢 Green — go!") }
        }

        onFinished { println("✅ Done") }
    }

    machine.processEvent(SwitchEvent) // Red → Yellow
    machine.processEvent(SwitchEvent) // Yellow → Green (finished)
}

Output

🔴 Red — stop!
   → switching…
   leaving red
🟡 Yellow — get ready
🟢 Green — go!
✅ Done

✨ Key Features

Integration

Feature	Description
Kotlin DSL	Declarative, readable structure; plain API also available
Kotlin Coroutines	Suspending functions in listeners and guards; fully optional
Kotlin Multiplatform	JVM, Android, iOS, JS, Wasm, Native
Zero dependencies	Core artifact depends only on the Kotlin stdlib

State management

Feature	Description
Event-based	Transitions fire in response to events
Reactive listeners	Observe machines, states, state groups, and transitions
Guarded & conditional transitions	Dynamic target state computed at runtime
Nested states	Full statechart hierarchy with cross-level transitions
Composed state machines	Embed one machine as a child state of another
Pseudo states	History, redirect, and other behavioural helpers
Typesafe transitions	Carry typed data from event to target state
Parallel states	Run orthogonal regions simultaneously
Undo transitions	Navigate back like a stack-based FSM

Tooling

Feature	Description
Export	Generate PlantUML or Mermaid diagrams from your machine definition
Persist & restore	Record processed events and replay them to restore state; `kotlinx.serialization` built in
Testing helpers	`startFrom(state)` bypasses normal init, enabling focused unit tests

📄 Documentation

Important

Full documentation lives at kstatemachine.github.io/kstatemachine
KDoc for every class: kstatemachine.github.io/kstatemachine/kdoc

❤️ Sponsors

If KStateMachine saves you time, please consider supporting the project:

⭐ Star this repo — it helps others discover it
❤️ GitHub Sponsors — one-time or recurring donations
💛 Open Collective — transparent team funding

🧪 Samples

Full app samples and 20+ focused code samples are listed on the Samples page in the documentation.

Android sample app

✍️ Publications

Integrating State Machines with MVI Architecture in Kotlin for Reactive Android Apps

💾 Install

KStateMachine is published to Maven Central and JitPack.

dependencies {
    // Core (zero dependencies)
    implementation("io.github.nsk90:kstatemachine:<Tag>")

    // + Kotlin Coroutines integration (optional)
    implementation("io.github.nsk90:kstatemachine-coroutines:<Tag>")

    // + kotlinx.serialization for state persistence (optional)
    implementation("io.github.nsk90:kstatemachine-serialization:<Tag>")
}

Replace <Tag> with the current version shown in the Maven Central badge above.
See the full install guide for Gradle Kotlin DSL, Groovy DSL, and JitPack variants.

🏗️ Build

./gradlew build          # build all modules
./gradlew :tests:jvmTest # run all tests (JVM target)

Or open in IntelliJ IDEA and run from there.

🤝 Contribution

The library is in stable phase — but feature proposals and pull requests are welcome!
Please read CONTRIBUTING.md before submitting.

🙋 Support

Channel	Best for
Slack `#kstatemachine`	Questions & discussions
GitHub Discussions	Questions & longer discussions
GitHub Issues	Bug reports & feature requests

When asking on other platforms, include a link to this repo or use the #kstatemachine tag.