KStateMachine

General

Category
Free
Tag
FSM
License
N/A
Registered
Jan 2, 2022
Favorites
1
Link
https://github.com/nsk90/kstatemachine
See also
TinyMachine
Ken-Ken-Pa
EasyFlow
Dalek
Kaskade

Additional

Language
Kotlin
Version
v0.25.1 (Feb 1, 2024)
Created
Sep 16, 2020
Updated
Feb 5, 2024
Owner
Mikhail Fedotov (nsk90)
Contributors
Mikhail Fedotov (nsk90)
Fabian Neugart (neugartf)
Jason Michaud (jmichaud)
3
Activity
Badge
Generate
Download
Source code

KStateMachine

Documentation | Quick start | Samples | Install | License | Discussions

KStateMachine is a Kotlin DSL library for creating state machines and statecharts.

Overview

Integration features are:

  • Kotlin DSL syntax. Declarative and clear state machine structure. Using without DSL is also possible.
  • Kotlin Coroutines support. Call suspendable functions within the library. You can fully use KStateMachine without Kotlin Coroutines dependency if necessary.
  • Kotlin Multiplatform support.
  • Zero dependency. It is written in pure Kotlin, it does not depend on any third party libraries or Android SDK.

State management features:

Important

SEE FULL DOCUMENTATION HERE

Note

The library is in a development phase. You are welcome to propose useful features, or contribute to the project. Don't forget to push the ⭐ if you like this project.

Quick start sample

Finishing traffic light

stateDiagram-v2
    direction LR
    [*] --> GreenState
    GreenState --> YellowState : SwitchEvent
    YellowState --> RedState : SwitchEvent
    RedState --> [*]

object SwitchEvent : Event

sealed class States : DefaultState() {
    object GreenState : States()
    object YellowState : States()
    object RedState : States(), FinalState // Machine finishes when enters final state
}

fun main() = runBlocking {
    // Create state machine and configure its states in a setup block
    val machine = createStateMachine(this) {
        addInitialState(GreenState) {
            // Add state listeners
            onEntry { println("Enter green") }
            onExit { println("Exit green") }

            // Setup transition
            transition<SwitchEvent> {
                targetState = YellowState
                // Add transition listener
                onTriggered { println("Transition triggered") }
            }
        }

        addState(YellowState) {
            transition<SwitchEvent>(targetState = RedState)
        }

        addFinalState(RedState)

        onFinished { println("Finished") }
    }

    // Now we can process events
    machine.processEvent(SwitchEvent)
    machine.processEvent(SwitchEvent)
}

Samples

Install

KStateMachine is available on Maven Central and JitPack repositories.

The library consists of 2 components:

  • kstatemachine - (mandatory) state machine implementation (depends only on Kotlin Standard library)
  • kstatemachine-coroutines - (optional) add-ons for working with coroutines (depends on Kotlin Coroutines library)

Please note that starting from v0.22.0 the library switched to Kotlin Multiplatform and artifact naming has changed.

Maven Central

Add dependencies:

// kotlin
dependencies {
    // multiplatform artifacts (starting from 0.22.0)
    implementation("io.github.nsk90:kstatemachine:<Tag>")
    implementation("io.github.nsk90:kstatemachine-coroutines:<Tag>")
    // or JVM/Android artifacts (starting from 0.22.0)
    implementation("io.github.nsk90:kstatemachine-jvm:<Tag>")
    implementation("io.github.nsk90:kstatemachine-coroutines-jvm:<Tag>")
    // or iOS artifacts (starting from 0.22.1)
    implementation("io.github.nsk90:kstatemachine-iosarm64:<Tag>")
    implementation("io.github.nsk90:kstatemachine-coroutines-iosarm64:<Tag>")

    implementation("io.github.nsk90:kstatemachine-iosx64:<Tag>")
    implementation("io.github.nsk90:kstatemachine-coroutines-iosx64:<Tag>")

    implementation("io.github.nsk90:kstatemachine-iossimulatorarm64:<Tag>")
    implementation("io.github.nsk90:kstatemachine-coroutines-iossimulatorarm64:<Tag>")
}
// groovy
dependencies {
    // multiplatform artifacts
    implementation 'io.github.nsk90:kstatemachine:<Tag>'
    implementation 'io.github.nsk90:kstatemachine-coroutines:<Tag>' // optional
    // etc..
}

Where <Tag> is a library version.

You can see official docs about dependencies on multiplatform libraries

JitPack (deprecated)

Currently, JitPack does not support Kotlin multiplatform artifacts. So versions starting from 0.22.0 are not available there, use Maven Central instead.

Add the JitPack repository to your build file. Add it in your root build.gradle at the end of repositories:

// kotlin
repositories {
    //  ...
    maven { url = uri("https://jitpack.io") }
}
// groovy
allprojects {
    repositories {
        //  ...
        maven { url 'https://jitpack.io' }
    }
}

Add dependencies:

// kotlin
dependencies {
    implementation("com.github.nsk90:kstatemachine:<Tag>")
    // note that group is different in second artifact, long group name also works for first artifact but not vise versa
    // it is some strange JitPack behaviour
    implementation("com.github.nsk90.kstatemachine:kstatemachine-coroutines:<Tag>") // optional
}
// groovy
dependencies {
    implementation 'com.github.nsk90:kstatemachine:<Tag>'
    // note that group is different in second artifact, long group name also works for first artifact but not vise versa
    // it is some strange JitPack behaviour
    implementation 'com.github.nsk90.kstatemachine:kstatemachine-coroutines:<Tag>' // optional
}

Where <Tag> is a library version.

Build

Run ./gradlew build or build with Intellij IDEA.

To run tests from IDE download official Kotest plugin.

License

Licensed under permissive Boost Software License

Thanks to supporters