Asyncio

Swift async/await and Actor-powered effectful state-management framework

Sep 09, 2021 10 min read

?
Actomaton

?‍?
Actor +
?
Automaton =
?
Actomaton

Actomaton is Swift async/await & Actor-powered effectful state-management framework inspired by Elm and swift-composable-architecture.

This repository consists of 2 frameworks:

Actomaton: Actor-based effect-handling state-machine at its core. Linux ready.
ActomatonStore: SwiftUI & Combine support

These frameworks depend on swift-case-paths as Functional Prism library, which is a powerful tool to construct an App-level Mega-Reducer from each screen’s Reducers.

This framework is a successor of the following projects:

Harvest (using Combine with SwiftUI support)
ReactiveAutomaton (using ReactiveSwift)
RxAutomaton (using RxSwift)

Demo App

Actomaton-Gallery

1. Actomaton (Core)

Example 1-1. Simple Counter

<div class="highlight highlight-source-swift position-relative" data-snippet-clipboard-copy-content="enum State {
var count: Int = 0
}

enum Action {
case increment
case decrement
}

typealias Enviornment = Void

let reducer: Reducer
reducer = Reducer { action, state, environment in
switch action {
case .increment:
state.count += 1
return Effect.empty
case .decrement:
state.count -= 1
return Effect.empty
}
}

let actomaton = Actomaton(
state: State(),
reducer: reducer
)

@main
enum Main {
static func main() async {
assertEqual(await actomaton.state.count, 0)

await actomaton.send(.increment)
assertEqual(await actomaton.state.count, 1)

await actomaton.send(.increment)
assertEqual(await actomaton.state.count, 2)

await actomaton.send(.decrement)
assertEqual(await actomaton.state.count, 1)

await actomaton.send(.decrement)
assertEqual(await actomaton.state.count, 0)
}
}
“>

enum State {
    var count: Int = 0
}

enum Action {
    case increment
    case decrement
}

typealias Enviornment = Void

let reducer: Reducer<Action, State, Environment>
reducer = Reducer { action, state, environment in
    switch action {
    case .increment:
        state.count += 1
        return Effect.empty
    case .decrement:
        state.count -= 1
        return Effect.empty
    }
}

let actomaton = Actomaton<Action, State>(
    state: State(),
    reducer: reducer
)

@main
enum Main {
    static func main() async {
        assertEqual(await actomaton.state.count, 0)

        await actomaton.send(.increment)
        assertEqual(await actomaton.state.count, 1)

        await actomaton.send(.increment)
        assertEqual(await actomaton.state.count, 2)

        await actomaton.send(.decrement)
        assertEqual(await actomaton.state.count, 1)

        await actomaton.send(.decrement)
        assertEqual(await actomaton.state.count, 0)
    }
}

If you want to do some logging (side-effect), add Effect in Reducer as follows:

reducer = Reducer { action, state, environment in
    switch action {
    case .increment:
        state.count += 1
        return Effect.fireAndForget {
            print("increment")
        }
    case .decrement:
        state.count -= 1
        return Effect.fireAndForget {
            print("decrement and sleep...")
            await Task.sleep(...) // NOTE: We can use `await`!
            print("I'm awake!")
        }
    }
}

NOTE: There are 5 ways of creating Effect in Actomaton:

No side-effects, but next action only
- Effect.nextAction
Single async without next action
- Effect.fireAndForget(id:run:)
Single async with next action
- Effect.init(id:run:)
Multiple asyncs (i.e. AsyncSequence) with next actions
- Effect.init(id:sequence:)
Manual cancellation
- Effect.cancel(id:) / .cancel(ids:)

Example 1-2. Login-Logout (and ForceLogout)

Effect
let logoutEffect: Effect
}

let environment = Environment(
loginEffect: { userId in
Effect(id: LoginFlowEffectID()) {
let loginRequest = …
let data = try? await URLSession.shared.data(for: loginRequest)
if Task.isCancelled { return nil }
…
return Action.loginOK // next action
}
},
logoutEffect: {
Effect(id: LoginFlowEffectID()) {
let logoutRequest = …
let data = try? await URLSession.shared.data(for: logoutRequest)
if Task.isCancelled { return nil }
…
return Action.logoutOK // next action
}
}
)

let reducer = Reducer { action, state, environment in
switch (action, state) {
case (.login, .loggedOut):
state = .loggingIn
return environment.login(state.userId)

case (.loginOK, .loggingIn):
state = .loggedIn
return .empty

case (.logout, .loggedIn),
(.forceLogout, .loggingIn),
(.forceLogout, .loggedIn):
state = .loggingOut
return environment.logout()

case (.logoutOK, .loggingOut):
state = .loggedOut
return .empty

default:
return Effect.fireAndForget {
print("State transition failed…")
}
}
}

let actomaton = Actomaton(
state: .loggedOut,
reducer: reducer,
environment: environment
)

@main
enum Main {
static func test_login_logout() async {
var t: Task?

assertEqual(await actomaton.state, .loggedOut)

t = await actomaton.send(.login)
assertEqual(await actomaton.state, .loggingIn)

await t?.value // wait for previous effect
assertEqual(await actomaton.state, .loggedIn)

t = await actomaton.send(.logout)
assertEqual(await actomaton.state, .loggingOut)

await t?.value // wait for previous effect
assertEqual(await actomaton.state, .loggedOut)

XCTAssertFalse(isLoginCancelled)
}

static func test_login_forceLogout() async throws {
var t: Task?

assertEqual(await actomaton.state, .loggedOut)

await actomaton.send(.login)
assertEqual(await actomaton.state, .loggingIn)

// Wait for a while and interrupt by `forceLogout`.
// Login’s effect will be automatically cancelled because of same `EffectID.
await Task.sleep(/* 1 ms */)
t = await actomaton.send(.forceLogout)

assertEqual(await actomaton.state, .loggingOut)

await t?.value // wait for previous effect
assertEqual(await actomaton.state, .loggedOut)

}
}
“>

enum State {
    case loggedOut, loggingIn, loggedIn, loggingOut
}

enum Action {
    case login, loginOK, logout, logoutOK
    case forceLogout
}

// NOTE:
// Use same `EffectID` so that if previous effect is still running,
// next effect with same `EffectID` will automatically cancel the previous one.
//
// Note that `EffectID` is also useful for manual cancellation via `Effect.cancel`.
struct LoginFlowEffectID: EffectIDProtocol {}

struct Environment {
    let loginEffect: (userId: String) -> Effect<Action>
    let logoutEffect: Effect<Action>
}

let environment = Environment(
    loginEffect: { userId in
        Effect(id: LoginFlowEffectID()) {
            let loginRequest = ...
            let data = try? await URLSession.shared.data(for: loginRequest)
            if Task.isCancelled { return nil }
            ...
            return Action.loginOK // next action
        }
    },
    logoutEffect: {
        Effect(id: LoginFlowEffectID()) {
            let logoutRequest = ...
            let data = try? await URLSession.shared.data(for: logoutRequest)
            if Task.isCancelled { return nil }
            ...
            return Action.logoutOK // next action
        }
    }
)

let reducer = Reducer { action, state, environment in
    switch (action, state) {
    case (.login, .loggedOut):
        state = .loggingIn
        return environment.login(state.userId)

    case (.loginOK, .loggingIn):
        state = .loggedIn
        return .empty

    case (.logout, .loggedIn),
        (.forceLogout, .loggingIn),
        (.forceLogout, .loggedIn):
        state = .loggingOut
        return environment.logout()

    case (.logoutOK, .loggingOut):
        state = .loggedOut
        return .empty

    default:
        return Effect.fireAndForget {
            print("State transition failed...")
        }
    }
}

let actomaton = Actomaton<Action, State>(
    state: .loggedOut,
    reducer: reducer,
    environment: environment
)

@main
enum Main {
    static func test_login_logout() async {
        var t: Task<(), Never>?

        assertEqual(await actomaton.state, .loggedOut)

        t = await actomaton.send(.login)
        assertEqual(await actomaton.state, .loggingIn)

        await t?.value // wait for previous effect
        assertEqual(await actomaton.state, .loggedIn)

        t = await actomaton.send(.logout)
        assertEqual(await actomaton.state, .loggingOut)

        await t?.value // wait for previous effect
        assertEqual(await actomaton.state, .loggedOut)

        XCTAssertFalse(isLoginCancelled)
    }

    static func test_login_forceLogout() async throws {
        var t: Task<(), Never>?

        assertEqual(await actomaton.state, .loggedOut)

        await actomaton.send(.login)
        assertEqual(await actomaton.state, .loggingIn)

        // Wait for a while and interrupt by `forceLogout`.
        // Login's effect will be automatically cancelled because of same `EffectID.
        await Task.sleep(/* 1 ms */)
        t = await actomaton.send(.forceLogout)

        assertEqual(await actomaton.state, .loggingOut)

        await t?.value // wait for previous effect
        assertEqual(await actomaton.state, .loggedOut)

    }
}

Here we see the notions of EffectID, Environment, and let task: Task<(), Never> = actomaton.send(...)

EffectID is for both manual & automatic cancellation of previous running effects. In this example, forceLogout will cancel login‘s networking effect.
Environment is useful for injecting effects to be called inside Reducer so that they become replaceable. Environment is known as Dependency Injection (using Reader monad).
(Optional) Task<(), Never> returned from actomaton.send(action) is another fancy way of dealing with “all the effects triggered by action“. We can call await task.value to wait for all of them to be completed, or task.cancel() to cancel all. Note that Actomaton already manages such tasks for us internally, so we normally don’t need to handle them by ourselves (use this as a last resort!).

Example 1-3. Timer (using `AsyncSequence`)

<div class="highlight highlight-source-swift position-relative" data-snippet-clipboard-copy-content="typealias State = Int

enum Action {
case start, tick, stop
}

struct TimerID: EffectIDProtocol {}

struct Environment {
let timerEffect: Effect
}

let environment = Environment(
timerEffect: { userId in
Effect(id: TimerID(), sequence: AsyncStream { continuation in
let task = Task {
while true {
await Task.sleep(/* 1 sec */)
continuation.yield(())
}
}

continuation.onTermination = { @Sendable _ in
task.cancel()
}
}
}
)

let reducer = Reducer { action, state, environment in
switch action {
case .start:
return environment.timerEffect
case .tick:
state += 1
return .empty
case .stop:
return Effect.cancel(id: TimerID())
}
}

let actomaton = Actomaton(
state: 0,
reducer: reducer,
environment: environment
)

@main
enum Main {
static func test_timer() async {
assertEqual(await actomaton.state, 0)

await actomaton.send(.start)

assertEqual(await actomaton.state, 0)

await Task.sleep(/* 1 sec */)
assertEqual(await actomaton.state, 1)

await Task.sleep(/* 1 sec */)
assertEqual(await actomaton.state, 2)

await Task.sleep(/* 1 sec */)
assertEqual(await actomaton.state, 3)

await actomaton.send(.stop)

await Task.sleep(/* long enough */)
assertEqual(await actomaton.state, 3,
"Should not increment because timer is stopped.")
}
}
“>

typealias State = Int

enum Action {
    case start, tick, stop
}

struct TimerID: EffectIDProtocol {}

struct Environment {
    let timerEffect: Effect<Action>
}

let environment = Environment(
    timerEffect: { userId in
        Effect(id: TimerID(), sequence: AsyncStream<()> { continuation in
            let task = Task {
                while true {
                    await Task.sleep(/* 1 sec */)
                    continuation.yield(())
                }
            }

            continuation.onTermination = { @Sendable _ in
                task.cancel()
            }
        }
    }
)

let reducer = Reducer { action, state, environment in
    switch action {
    case .start:
        return environment.timerEffect
    case .tick:
        state += 1
        return .empty
    case .stop:
        return Effect.cancel(id: TimerID())
    }
}

let actomaton = Actomaton<Action, State>(
    state: 0,
    reducer: reducer,
    environment: environment
)

@main
enum Main {
    static func test_timer() async {
        assertEqual(await actomaton.state, 0)

        await actomaton.send(.start)

        assertEqual(await actomaton.state, 0)

        await Task.sleep(/* 1 sec */)
        assertEqual(await actomaton.state, 1)

        await Task.sleep(/* 1 sec */)
        assertEqual(await actomaton.state, 2)

        await Task.sleep(/* 1 sec */)
        assertEqual(await actomaton.state, 3)

        await actomaton.send(.stop)

        await Task.sleep(/* long enough */)
        assertEqual(await actomaton.state, 3,
                    "Should not increment because timer is stopped.")
    }
}

In this example, Effect(id:sequence:) is used for timer effect, which yields Action.tick multiple times.

Example 1-4. Reducer composition

Actomaton-Gallery provides a good example of how Reducers can be combined together into one big Reducer using Reducer.combine.

In this example, swift-case-paths is used as a counterpart of WritableKeyPath, so if we use both, we can easily construct Mega-Reducer without a hussle.

(NOTE: CasePath is useful when dealing with enums, e.g. enum Action and enum Current in this example)

<div class="highlight highlight-source-swift position-relative" data-snippet-clipboard-copy-content="enum Root {} // just a namespace

extension Root {
enum Action {
case changeCurrent(State.Current?)

case counter(Counter.Action)
case stopwatch(Stopwatch.Action)
case stateDiagram(StateDiagram.Action)
case todo(Todo.Action)
case github(GitHub.Action)
}

struct State: Equatable {
var current: Current?

// Current screen (NOTE: enum, so only 1 screen will appear)
enum Current: Equatable {
case counter(Counter.State)
case stopwatch(Stopwatch.State)
case stateDiagram(StateDiagram.State)
case todo(Todo.State)
case github(GitHub.State)
}
}

// NOTE: `contramap` is also called `pullback` in swift-composable-architecture.
static var reducer: Reducer {
Reducer.combine(
Counter.reducer
.contramap(action: /Action.counter)
.contramap(state: /State.Current.counter)
.contramap(state: \State.current)
.contramap(environment: { _ in () }),

Todo.reducer
.contramap(action: /Action.todo)
.contramap(state: /State.Current.todo)
.contramap(state: \State.current)
.contramap(environment: { _ in () }),

StateDiagram.reducer
.contramap(action: /Action.stateDiagram)
.contramap(state: /State.Current.stateDiagram)
.contramap(state: \State.current)
.contramap(environment: { _ in () }),

Stopwatch.reducer
.contramap(action: /Action.stopwatch)
.contramap(state: /State.Current.stopwatch)
.contramap(state: \State.current)
.contramap(environment: { $0.stopwatch }),

GitHub.reducer
.contramap(action: /Action.github)
.contramap(state: /State.Current.github)
.contramap(state: \State.current)
.contramap(environment: { $0.github }),

GitHub.reducer
.contramap(action: /Action.github)
.contramap(state: /State.Current.github)
.contramap(state: \State.current)
.contramap(environment: { $0.github })
)
}
}
“>

enum Root {} // just a namespace

extension Root {
    enum Action {
        case changeCurrent(State.Current?)

        case counter(Counter.Action)
        case stopwatch(Stopwatch.Action)
        case stateDiagram(StateDiagram.Action)
        case todo(Todo.Action)
        case github(GitHub.Action)
    }

    struct State: Equatable {
        var current: Current?

        // Current screen (NOTE: enum, so only 1 screen will appear)
        enum Current: Equatable {
            case counter(Counter.State)
            case stopwatch(Stopwatch.State)
            case stateDiagram(StateDiagram.State)
            case todo(Todo.State)
            case github(GitHub.State)
        }
    }

    // NOTE: `contramap` is also called `pullback` in swift-composable-architecture.
    static var reducer: Reducer<Action, State, Environment> {
        Reducer.combine(
            Counter.reducer
                .contramap(action: /Action.counter)
                .contramap(state: /State.Current.counter)
                .contramap(state: \State.current)
                .contramap(environment: { _ in () }),

            Todo.reducer
                .contramap(action: /Action.todo)
                .contramap(state: /State.Current.todo)
                .contramap(state: \State.current)
                .contramap(environment: { _ in () }),

            StateDiagram.reducer
                .contramap(action: /Action.stateDiagram)
                .contramap(state: /State.Current.stateDiagram)
                .contramap(state: \State.current)
                .contramap(environment: { _ in () }),

            Stopwatch.reducer
                .contramap(action: /Action.stopwatch)
                .contramap(state: /State.Current.stopwatch)
                .contramap(state: \State.current)
                .contramap(environment: { $0.stopwatch }),

            GitHub.reducer
                .contramap(action: /Action.github)
                .contramap(state: /State.Current.github)
                .contramap(state: \State.current)
                .contramap(environment: { $0.github }),

            GitHub.reducer
                .contramap(action: /Action.github)
                .contramap(state: /State.Current.github)
                .contramap(state: \State.current)
                .contramap(environment: { $0.github })
        )
    }
}

Swift async/await and Actor-powered effectful state-management framework

?
Actomaton

Demo App

1. Actomaton (Core)

Example 1-1. Simple Counter

Example 1-2. Login-Logout (and ForceLogout)

Example 1-3. Timer (using `AsyncSequence`)

Example 1-4. Reducer composition

2. ActomatonStore (SwiftUI)

`Store.Proxy.stateBinding`

References

License

GitHub

Example project guide you schedules multiple thread for network requests in RxSwift

A Multiplatform iOS app to count stitches in crochet patterns

? Actomaton

Demo App

1. Actomaton (Core)

Example 1-1. Simple Counter

Example 1-2. Login-Logout (and ForceLogout)

Example 1-3. Timer (using AsyncSequence)

Example 1-4. Reducer composition

2. ActomatonStore (SwiftUI)

Store.Proxy.stateBinding

References

License

GitHub

Example project guide you schedules multiple thread for network requests in RxSwift

A Multiplatform iOS app to count stitches in crochet patterns

You might also like...

Subscribe to iOS Example

?
Actomaton

Example 1-3. Timer (using `AsyncSequence`)

`Store.Proxy.stateBinding`