FAQ about States

🤔 Why should I use states?
🖼 What is a state?
👨‍🎨 How do I write states?
👨‍🔬 How do I write specs?
👨‍🔧 How do I use states?

Graph


╔══════════════════════════╗
║          STATE           ║
╟──────────────────────────╢
║ Reducer ◀───▶ Properties ║
║    ▲               │     ║
║    │               ▼     ║
║  Events         Outputs  ║
╚════╪═══════════════╪═════╝
·   ─┼─             ─┼─
·    │  ┌─────────┐  │
·    ├─┼┼◀ TESTS ◀┼┼─┤
·    │  └─────────┘  │
·   ═╪═             ═╪═
╔════╪═══════════════╪═════╗
║    └─◀ Feedback ↻ ◀┘     ║
╟──────────────────────────╢
║        CONTROLLER        ║
╚══════════════════════════╝

Why should I use states?

We use states in Trafi for a few reasons:

States break down big problems to small pieces
States keep our code pure and easily testable
States help us share solutions between platforms & languages
States make debugging easier with a single pure function

Why shouldn’t I use states?

It’s an unusual development flow
Overhead for very simple cases
Takes time and practice to integrate into existing code

What is a state?

A state is the brains of a screen. It makes all the important decisions. It’s a simple type with three main parts:

Privately stored data
Enum of events to create new state
Computed outputs to be handled by the controller

🔎 See a simple example

#### Swift

swift
struct CoinState {

  // 1. Privately stored data
  private var isHeads: Bool = true

  // 2. Enum of events
  enum Event {
    case flipToHeads
    case flipToTails
  }
  // .. to create new state
  static func reduce(state: CoinState, event: Event) -> CoinState {
    switch event {
    case .flipToHeads: return CoinState(isHeads: true)
    case .flipToTails: return CoinState(isHeads: false)
    }
  }

  // 3. Computed outputs to be handled by the controller
  var coinSide: String {
    return isHeads ? "Heads" : "Tails"
  }
}

#### Kotlin

kotlin

data class CoinState(
    // 1. Privately stored data
    private val isHeads: Boolean = true
)

// 2. Enum of events
sealed class Event {
    object FlipToHeads : Event()
    object FlipToTails : Event()
}

// .. to create new state
fun CoinState.reduce(event: Event) = when(event) {
    FlipToHeads -> copy(isHeads = true)
    FlipToTails -> copy(isHeads = false)
}

// 3. Computed outputs to be handled by the controller
val CoinState.coinSide: String get() {
    return isHeads ? "Heads" : "Tails"
}

Samples

How do I write states?

There are many ways to write states. We can recommend following these steps:

Draft a platform-independent interface:
- List events that could happen
- List outputs to display UI, load data and navigate
Implement the internals:
- ❌ Write a failing test that sends an event and asserts an output
- ✅ Add code to state till test passes
- 🛠 Refactor code so it’s nice, but all tests still pass
- 🔁 Continue writing tests for all events and outputs

What can be an event?

Anything that just happened that the state should know about is an event. Events can be easily understood and listed by non-developers. Most events come from a few common sources:

User interactions
- tappedSearch
- tappedResult
- completedEditing
- pulledToRefresh
Networking
- loadedSearchResults
- loadedMapData
Screen lifecycle
- becameReadyForRefresh
- becameVisible
- enteredBackground
Device
- wentOffline
- changedCurrentLocation

As events are something that just happened we start their names with verbs in past simple tense.

🔎 See an example

#### Swift

swift
struct MyCommuteState {
  enum Event {
    case refetched(MyCommuteResponse)
    case wentOffline
    case loggedIn(Bool)
    case activatedTab(index: Int)
    case tappedFavorite(MyCommuteTrackStopFavorite)
    case tappedFeedback(MyCommuteUseCase, MyCommuteFeedbackRating)
    case completedFeedback(String)
  }
}

#### Kotlin

kotlin
data class MyCommuteState(/**/)

sealed class Event {
    data class Refetched(val response: MyCommuteResponse) : Event()
    object WentOffline : Event()
    data class LoggedIn(val isLoggedIn: Boolean) : Event()
    data class ActivatedTab(val index: Int) : Event()
    data class TappedFavorite(val favorite: MyCommuteTrackStopFavorite) : Event()
    data class TappedFeedback(val feedback: Feedback) : Event()
    data class CompletedFeedback(val message: String) : Event()
}

What are outputs?

Outputs are the exposed getters of state. Controllers listen to state changes through outputs. Like events, outputs are simple enough to be understood and listed by non-developers. Most outputs can be categorized as:

UI. These are usually non-optional outputs that specific UI elements are bound to, e.g:
- isLoading: Bool
- paymentOptions: [PaymentOption]
- profileHeader: ProfileHeader
Data. These are usually optional outputs that controllers react to. Their names indicate how to react and their types give associated information if needed, e.g:
- loadAutocompleteResults: String?
- loadNearbyStops: LatLng?
- syncFavorites: Void?
Navigation. These are always optional outputs that are just proxies for navigation, e.g.:
- showStop: StopState?
- showProfile: ProfileState?
- dismiss: Void?

What to store privately?

Any properties that are needed to compute the necessary outputs can be stored privately. We strive for this to be the minimal ground truth needed to represent any possible valid state.

🔎 See an example

#### Swift

swift
struct PhoneVerificationState {
    private let phoneNumber: String
    private var waitBeforeRetrySeconds: Int
}

#### Kotlin

kotlin
data class PhoneVerificationState(
    private val phoneNumber: String,
    private val waitBeforeRetrySeconds: Int
)

What does the reducer do?

The reducer is a pure function that changes the state’s privately stored properties according to an event.

🔎 See an example

#### Swift

swift
struct CoinState {
    private var isHeads: Bool = true

    static func reduce(_ state: CoinState, event: Event) -> CoinState {
        var result = state
        switch event {
        case .flipToHeads: result.isHeads = true
        case .flipToTails: result.isHeads = false
        }
        return result
    }
}

#### Kotlin

kotlin
data class CoinState(private val isHeads: Boolean) {

    fun reduce(event: Event) = when(event) {
        FlipToHeads -> copy(isHeads = true)
        FlipToTails -> copy(isHeads = false)
    }
}

How do I write specs?

We write specs (tests) in a BDD style. For Swift we use Quick and Nible, for Kotlin Spek.

🔎 See an example

#### Swift

swift
class MyCommuteSpec: QuickSpec {

    override func spec() {

        var state: MyCommuteState!
        beforeEach {
            state = .initial(response: .dummy, now: .h(10))
        }

        context("When offline") {

            it("Has no departues") {
                expect(state)
                    .after(.wentOffline)
                    .toTurn { $0.activeFavorites.flatMap { $0.departures }.isEmpty }
            }

            it("Has no disruptions") {
                expect(state)
                    .after(.wentOffline)
                    .toTurn { $0.activeFavorites.filter { $0.severity != .notAffected }.isEmpty }
            }
        }
    }
}

#### Kotlin

kotlin
object NearbyStopsStateSpec : Spek({
    describe("Stops near me") {

        describe("when location is present") {
            var state = NearbyStopsState(hasLocation = true)
            beforeEach { state = NearbyStopsState(hasLocation = true) }

            describe("at start") {
                it("shows progress") { assertEquals(Ui.Progress, state.ui) }
                it("tries to load stops") { assertTrue(state.loadStops) }
            }
        }
    }
}

How do I use states?

States become useful when their outputs are connected to UI, network requests, and other side effects.

Reactive streams compose nicely with the states pattern. We recommend using RxFeedback.swift / RxFeedback.kt to connect states to side effects in a reactive way.

🔎 See an example

#### Swift

swift
Driver.system(
        initialState: input,
        reduce: PhoneVerificationState.reduce,
        feedback: uiBindings() + dataBindings() + [produceOutput()])
    .drive()
    .disposed(by: rx_disposeBag)

States are versatile and can be used with more traditional patterns, e.g. observer / listener patterns. On Android we use a simple state machine implementation which you can find in the Kotlin state tools.

🔎 See an example

#### Kotlin (Android)

kotlin

private val machine = StateMachine(PhoneVerificationState("+00000000000"))

machine.subscribeWithAutoDispose(viewLifecycleOwner) { boundState, newState ->
    // do things with newState
}