State Machine

A state machine library for Kotlin, with extensions for Android.

States and Events

A state machine takes three generic parameters: the events it takes in, the states it spits out,
and the arguments it finishes with. These could be sealed classes, or plain classes & objects.

sealed class Event {
  data class InputText(val text: String) : Event()
  
  object ClickedButton : Event()
}

sealed class State {
  abstract val showProgress: Boolean

  data class Idle(val currentInput: String = "") : State() {
     override val showProgress: Boolean = false
  }
  
  data class Submitting(val currentInput: String) : State() {
     override val showProgress: Boolean = true
  }
  
  object Success : State() {
     override val showProgress: Boolean = false
  }
  
  data class Failure(val reason: String) : State() {
     override val showProgress: Boolean = false
  }
}

data class Result(val success: Boolean)
Kotlin

Building a Machine

A basic machine only requires the core module without any extensions.

Gradle Dependency

Core 

dependencies {
   ...
   implementation "com.afollestad:statemachine:0.0.1-alpha1"
}
Gradle

Basics

Your state machine should be a subclass of the StateMachine class.

When the react method is called, your machine should setup handlers for states. Each state
handles a set of events, each event returns a state. The state should propagate to the UI, and the
UI should send in events when there is interaction. It's a loop, which is basically what a state
machine is.

class MyStateMachine : StateMachine<Event, State, Result>() {
  override suspend fun react() {
    onState<Idle> {
      onEvent<InputText> {
        state.copy(currentInput = event.text)
      }
      onEvent<ClickedButton> {
        Submitting(currentInput = state.currentInput)
      }
    }
    onState<Submitting> {
      onEnter { doServerWork(state) }
    }
    onState<Success> {
      onEnter {
        delay(2000) // A synthetic delay
        finish(Result(true)) // Kills the state machine.
      }
    }
    onState<Failure> {
      onEnter {
        delay(5000) 
        Idle() 
      }
    }
  }

  private suspend fun doServerWork(state: Submitting): State {
    delay(2000)
    return if (state.currentInput == "fail") {
      Failure(reason = "Your wish is my command.")
    } else {
      Success
    }
  }
}
Kotlin

Usage

This example below demonstrates usage from a JVM command-line program.

fun main() {
  val stateMachine = MyStateMachine()
  
  // Listen for state changes in the background
  GlobalScope.launch {
    stateMachine.stateFlow()
        .collect { state ->
          println("Current state: $state")
        }
  }
  
  // Start the machine with an initial state, launches the event looper.
  stateMachine.start(Idle()) { args ->
    // This callback is invoked when the machine is finished.
    // It cannot be re-used after this point.
    println("Goodbye.")
  }

  val inputReader = Scanner(System.`in`)
  while (stateMachine.isActive) {
    when (val input = inputReader.nextLine()) {
      "send" -> {
        // The invoke operator on the machine streams in events.
        stateMachine(ClickedButton)
      }
      "exit" -> {
        // The finish() method destroys the state machine.
        // This releases resources and shuts down the event looper.
        stateMachine.finish()
      }
      else -> stateMachine(InputText(input))
    }
  }
}
Kotlin

Using a Machine on Android

On Android, there are extension modules that you can use to make connecting your states and UI much
easier. Annotation processing is used to generate view models from your state.

Gradle Dependency

Core Android

On Android, your application should depend on the core-android module as an implementation
dependency, and the core-android-processor module as an annotation processor (with kapt).

dependencies {
   ...
   implementation "com.afollestad:statemachine-android:0.0.1-alpha1"
   kapt "com.afollestad:statemachine-android-processor:0.0.1-alpha1"
}
Gradle

States and View Models

Your state must be tagged with the @StateToViewModel annotation. Only the parent class should be tagged.

@StateToViewModel
sealed class MyState {
  abstract val buttonEnabled: Boolean

  data class Idle(val currentInput: String = "") : State() {
     override val buttonEnabled = true
  }
  data class Submitting(val currentInput: String) : State() {
     override val buttonEnabled = false
  }
  object Success : State() {
     override val buttonEnabled = false
  }
  data class Failure(val errorMessage: String) : State() {
     override val buttonEnabled = true
  }
}
Kotlin

This will generate a ViewModel that you can use in your UI. From the above state,
you'd get something similar to this (some details are omitted because they aren't relevant):

class MyStateViewModel : ViewModel(), StateConsumer<MyState> {
  val onButtonEnabled: LiveData<Boolean> = // ...
  val onCurrentInput: LiveData<String> = // ...
  val onErrorMessage: LiveData<String> = // ...
  
  override fun accept(state: MyState) {
    ...
     // This is filled automatically to propagate state changes into the live data fields above.
  }
}
Kotlin

Dispatchers

On Android, being thread conscious is important. StateMachine's constructor takes two coroutine
dispatchers - one for background execution, and one for the main thread.

class MyStateMachine : StateMachine<Event, State, Result>(
   executionContext = Dispatchers.IO,
   mainContext = Dispatchers.Main
) {
  ...
}
Kotlin

Usage

In your Activity, Fragment, etc. you can use the generated ViewModels like you would without
this library.

class MyActivity : AppCompatActivity() {
  private lateinit var button: Button
  private lateinit var input: EditText
  private lateinit var error: TextView

  private lateinit var stateMachine: MyStateMachine

  override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)
      // ...
      
      stateMachine = MyStateMachine()
      
      val viewModel = ViewModelProviders.of(this)
         .get(MyStateViewModel::class.java)
      
      viewModel.onButtonEnabled
         .observe(this, button::setEnabled)
      viewModel.onCurrentInput
         /** Filtering here is important to we don't end up with an input/output loop */
         .filter { it != input.text.toString() }
         .observe(this, input::setText)
      viewModel.onErrorMessage
         .observe(this, error::setTextAndVisibility)
          
      input.onTextChanged { text -> 
         stateMachine(InputText(text = text)) 
      }
      button.setOnClickListener { 
         stateMachine(ClickedSubmit) 
      }
      
      // This is important on Android! This will automatically finish your state machine
      // when `this` (a LifecycleOwner) is destroyed. You could of course use plain `start()` 
      // here and remember to call `finish` somewhere below later, e.g. on `onDestroy()`.
      startMachine.startWithOwner(this)
  }
  
  private fun TextView.setTextAndVisibility(text: String) {
     setText(text)
     visibility = if (text.isNotEmpty()) VISIBLE else GONE
  }
}
Kotlin

Your UI will automatically receive propagated values from your states as they come in. The
generated view model will automatically distinct values as well, so you won't receive duplicate
emissions (which could result in unnecessary UI invalidation).

If you're familiar with LiveData, you'll also know that this implementation is
totally lifecycle safe. LiveData will not emit if the lifecycle owner is no longer
started.

Unit Testing Machines

A core-test module is provided to aid in unit testing your state machines.

Gradle Dependency

Core Testing 

dependencies {
   ...
   testImplementation "com.afollestad:statemachine-test:0.0.1-alpha1"
}
Gradle

Usage

Here's a simple example of a JUnit test, for the state machine above.

class MyTests {
  // The core-test module exposes a `test()` extension method.
  private val stateMachine = MyStateMachine().test()
  
  @Test fun `idle state accepts input`() {
     val initialState = Idle()
     stateMachine.start(initialState)
     // send an event in
     stateMachine(InputText(text))
     // assert the initial state and new state
     stateMachine.assertStates(initialState, Idle(text))
  }
  
  @Test fun `click button in idle submits`() {
     val initialState = Idle("hello world")
     stateMachine.start(initialState)
     // send an event in
     stateMachine(ClickedButton)
     // assert the initial state and new states
     // Submitting's `onEnter` brings us to the Success state.
     stateMachine.assertStates(initialState, Submitting(text), Success)
  }
  
  @After fun shutdown() {
     // Ensure resources are released and the event looper is stopped.
     stateMachine.destroy()
  }
}
Kotlin

GitHub