KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

Actomaton

★ 267 Open GitHub ↗

🎭 Swift async/await & Actor-powered effectful state-management framework.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🎭 Actomaton

[![Swift 6.2](https://img.shields.io/badge/swift-6.2-orange.svg?style=flat)](https://swift.org/download/)
![](https://github.com/Actomaton/Actomaton/actions/workflows/main.yml/badge.svg)

🧑‍🎤 Actor + 🤖 Automaton = 🎭 Actomaton

**Actomaton** is Swift `async`/`await` & `Actor`-powered effectful state-management framework
inspired by [Elm](http://elm-lang.org/) and [swift-composable-architecture](https://github.com/pointfreeco/swift-composable-architecture).

## Overview

This repository consists of 6 modules:

1. **`Actomaton`**: Actor-based effect-handling state-machine, which is a convenience layer that wires `ActomatonCore` + `ActomatonEffect` together.
    - [Documentation](https://actomaton.github.io/Actomaton/documentation/actomaton/)
2. **`ActomatonUI`**: SwiftUI & UIKit & Combine support.
    - [Documentation (Currently in Japanese only)](https://actomaton.github.io/Actomaton/documentation/actomatonui/)
3. **`ActomatonDebugging`**: Helper module to print `Action` and `State` (with diffing) per `Reducer` call.
    - [Documentation](https://actomaton.github.io/Actomaton/documentation/actomatondebugging/)

4. **`ActomatonTesting`**: `TestActomaton` — exhaustive state-transition testing utility. Wraps `MealyMachine` + `EffectManager` to assert TCA-like `send` / `receive` flows with `customDump` diffs.
    - [Documentation](https://actomaton.github.io/Actomaton/documentation/actomatontesting/)

In addition, the following lower-level modules are available for advanced use cases:

5. **`ActomatonCore`**: Generic Mealy machine (`MealyMachine`) and composable `MealyReducer`, independent of any effect system. Pair it with a pluggable `EffectManager` conformer to choose what "output" means — `Void` (no effects), `Action?` (synchronous feedback), or your own custom type.
6. **`ActomatonEffect`**: The `Effect<Action>` type and its default `EffectManager` conformer (`EffectQueueManager`) — queue-based async task lifecycle (creation, cancellation, suspension, delay).

### Module dependency graph

```
ActomatonCore          -- generic MealyMachine + MealyReducer + EffectManager
  └─ ActomatonEffect   -- Effect<Action>, EffectQueueManager, EffectQueue, EffectID
       ├─ Actomaton    -- Actomaton typealias, Reducer typealias, CasePath integration
       │    ├─ ActomatonUI         -- Store, RouteStore (SwiftUI / UIKit)
       │    └─ ActomatonDebugging  -- debug / log reducers
       └─ ActomatonTesting         -- TestActomaton (exhaustive state-transition testing)
```

### Why the split?

`ActomatonCore` is intentionally free of `Effect` and async task management.
This makes `MealyMachine` usable in contexts where full effect infrastructure is overkill — for example, purely synchronous state machines, game logic, or protocol parsers.
The default `EffectManager` conformer ships in `ActomatonEffect`:

| Conformer | Output type | Use case |
|---|---|---|
| `EffectQueueManager` (package) | `Effect<Action>` | Full async effect lifecycle (in `ActomatonEffect`) |

You can also provide your own `EffectManager` conformer to plug in a custom output type (e.g. `Void` for purely synchronous state machines, or `[Action]` for synchronous action feedback loops).

## Platform Support

- Apple platforms: Full package support, including `ActomatonUI`.
- Linux / Wasm: Full package except `ActomatonUI` which depends on Combine, SwiftUI, and UIKit.

## Installation

In `Package.swift`:

```swift
let package = Package(
    ...
    dependencies: [
        .package(url: "https://github.com/Actomaton/Actomaton", .branch("main"))
    ]
)
```

### Wasm quick start

```bash
make wasm-install
make wasm-build
make wasm-test
```

## Demo App

- [Actomaton-Gallery](https://github.com/Actomaton/Actomaton-Gallery)

## 1. Actomaton (Core)

### Example 1-1. Simple Counter

```swift
struct State: Sendable {
    var count: Int = 0
}

enum Action: Sendable {
    case increment
    case decrement
}

typealias Environment = Void

let reducer: Reducer<Action, State, Environment, Never>
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, Never>(
    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:

```swift
reducer = Reducer { action, state, environment in
    switch action {
    case .increment:
        state.count += 1
        return Effect.fireAndForget { _ in
            print("increment")
        }
    case .decrement:
        state.count -= 1
        return Effect.fireAndForget { context in
            print("decrement and sleep...")
            try await context.clock.sleep(for: .seconds(1))
            print("I'm awake!")
        }
    }
}
```

NOTE: There are 6 ways of creating `Effect` in Actomaton:

1. No side-effects, but next action only
    - `Effect.next(action:)`
2. Single `async` without next action
    - `Effect.fireAndForget(id:run:)`
3. Single `async` with next action
    - `Effect.init(id:run:)`
4. Multiple `async`s (i.e. `AsyncSequence`) with next actions
    - `Effect.sequence(id:_:)`
5. Push-style stream that emits next actions via a `send` closure
    - `Effect.stream(id:_:)` — useful for bridging long-lived observers (delegates, callbacks, `NotificationCenter`, etc.)
6. Manual cancellation
    - `Effect.cancel(id:)` / `.cancel(ids:)`

Effects can also be combined with `+`: `Effect.cancel(id: ...) + Effect { ... }` runs them as a single effect.

### Example 1-2. Timer (using `AsyncSequence`) and `EffectID` cancellation

```swift
typealias State = Int

enum Action: Sendable {
    case start, tick, stop
}

struct TimerID: EffectID {}

struct Environment: Sendable {
    let timer: @Sendable () -> AsyncStream<Void>
}

let environment = Environment(
    timer: {
        AsyncStream<Void> { continuation in
            let task = Task {
                while true {
                    try 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 Effect.sequence(id: TimerID()) { _ in
            environment.timer()
                .map { _ in Action.tick }
        }
    case .tick:
        state += 1
        return .empty
    case .stop:
        return Effect.cancel(id: TimerID())
    }
}

let actomaton = Actomaton<Action, State, Never>(
    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)

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

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

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

await actomaton.send(.stop)

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

Here we see the notions of `EffectID`, `Environment`, and `Effect.sequence`:

- `EffectID` tags an effect with a `Hashable` identifier so it can be cancelled later via `Effect.cancel(id:)`. In this example, `TimerID` lets `.stop` cancel the running timer.
- `Environment` holds the raw dependencies (here, an `AsyncStream`-producing closure). The `Reducer` is responsible for wrapping those dependencies in `Effect`. **`Environment` is known as Dependency Injection Container** (using Reader monad).
- `Effect.sequence(id:_:)` turns an `AsyncSequence` into an `Effect`, yielding `Action.tick` multiple times until cancelled.

### Example 1-3. Login-Logout (and ForceLogout) — `EffectQueue` for automatic cancellation

![login-diagram](https://user-images.githubusercontent.com/138476/132146518-686deb5f-ff01-489a-abf2-e2ef2a2adb03.png)

`EffectID` (introduced in Example 1-2) only supports *manual* cancellation. When you instead want effects sharing the same identity to be cancelled (or suspended) automatically as new ones arrive, attach an ``EffectQueue``.

```swift
enum State: Sendable {
    case loggedOut, loggingIn, loggedIn, loggingOut
}

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

// NOTE:
// By attaching this `EffectQueue` to multiple `Effect`s, they share the same
// `EffectQueuePolicy` — here, `Newest1EffectQueue` lets only the newest
// effect survive and automatically cancels older queued effects.
struct LoginFlowEffectQueue: Newest1EffectQueue {}

struct Environment: Sendable {
    let login: @Sendable (_ userId: String) async throws -> Void
    let logout: @Sendable () async throws -> Void
}

let environment = Environment(
    login: { userId in
        let loginRequest = ...
        _ = try? await URLSession.shared.data(for: loginRequest)
        ...
    },
    logout: {
        let logoutRequest = ...
        _ = try? await URLSession.shared.data(for: logoutRequest)
        ...
    }
)

let reducer = Reducer { action, state, environment in
    switch (action, state) {
    case (.login, .loggedOut):
        state = .loggingIn
        return Effect(queue: LoginFlowEffectQueue()) { _ in
            try await environment.login("user-123")
            return Action.loginOK
        }

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

case (.logout, .loggedIn),
        (.forceLogout, .loggingIn),
        (.forceLogout, .loggedIn):
        state = .loggingOut
        return Effect(queue: LoginFlowEffectQueue()) { _ in
            try await environment.logout()
            return Action.logoutOK
        }

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

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

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

@main
enum Main {
    static func test_login_logout() async {
        var results: SendResults<Never>?

assertEqual(await actomaton.state, .loggedOut)

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

await results?.completion // wait for previous effect
        assertEqual(await actomaton.state, .loggedIn)

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

await results?.completion // wait for previous effect
        assertEqual(await actomaton.state, .loggedOut)

XCTAssertFalse(isLoginCancelled)
    }

static func test_login_forceLogout() async throws {
        var results: SendResults<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 `EffectQueue`.
        try await Task.sleep(/* 1 ms */)
        results = await actomaton.send(.forceLogout)

assertEqual(await actomaton.state, .loggingOut)

await results?.completion // wait for previous effect
        assertEqual(await actomaton.state, .loggedOut)
    }
}
```

Here we see the notions of `EffectQueue` and the `SendResults<Emission>` returned from `actomaton.send(...)`:

- `EffectQueue` is for automatic cancellation or suspension of effects.
  In this example, `Newest1EffectQueue` is used so that only the newest 1 effect (`forceLogout`) will survive,
  and the rest of older queued effects (e.g. an in-flight `login`) will be automatically cancelled.
- (Optional) `SendResults<Emission>` returned from `actomaton.send(action)` is another fancy way of dealing with "all the effects triggered by `action`". We can call `await results.completion` to wait for all of them to be completed, or `results.cancel()` to cancel all. Note that `Actomaton` already manages such effects for us internally, so we normally don't need to handle them by ourselves (use this as a last resort!).

### Example 1-4. `EffectQueue`

```swift
enum Action: Sendable {
    case fetch(id: String)
    case _didFetch(Data)
}

struct State: Sendable {} // no state

struct Environment: Sendable {
    let fetch: @Sendable (_ id: String) async throws -> Data
}

struct DelayedEffectQueue: EffectQueue {
    // First 3 effects will run concurrently, and other sent effects will be suspended.
    var effectQueuePolicy: EffectQueuePolicy {
        .runOldest(maxCount: 3, .suspendNew)
    }

// Adds delay between effect start. (This is useful for throttling / debouncing)
    var effectQueueDelay: EffectQueueDelay {
        .random(0.1 ... 0.3)
    }
}

let reducer = Reducer<Action, State, Environment, Never> { action, state, environment in
    switch action {
    case let .fetch(id):
        return Effect(queue: DelayedEffectQueue()) { _ in
            let data = try await environment.fetch(id)
            return ._didFetch(data)
        }
    case let ._didFetch(data):
        // Do something with `data`.
        return .empty
    }
}

let actomaton = Actomaton<Action, State, Never>(
    state: State(),
    reducer: reducer,
        environment: Environment(fetch: { /* ... */ })
)

await actomaton.send(.fetch(id: "item1"))
await actomaton.send(.fetch(id: "item2")) // min delay of 0.1
await actomaton.send(.fetch(id: "item3")) // min delay of 0.1 (after item2 actually starts)
await actomaton.send(.fetch(id: "item4")) // starts when item1 or 2 or 3 finishes
```

Above code uses a custom `DelayedEffectQueue` that conforms to `EffectQueue` with suspendable `EffectQueuePolicy` and delays between each effect by `EffectQueueDelay`.

See [EffectQueuePolicy](https://github.com/Actomaton/Actomaton/blob/main/Sources/Actomaton/EffectQueuePolicy.swift) for how each policy takes different queueing strategy for effects.

```swift
/// `EffectQueue`'s buffering policy.
public enum EffectQueuePolicy: Hashable, Sendable
{
    /// Runs `maxCount` newest effects, cancelling old running effects.
    case runNewest(maxCount: Int)

/// Runs `maxCount` old effects with either suspending or discarding new effects.
    case runOldest(maxCount: Int, OverflowPolicy)

public enum OverflowPolicy: Sendable
    {
        /// Suspends new effects when `.runOldest` `maxCount` of old effects is reached until one of them is completed.
        case suspendNew

/// Discards new effects when `.runOldest` `maxCount` of old effects is reached until one of them is completed.
        case discardNew
    }
}
```

For convenient `EffectQueue` protocol conformance, there are built-in sub-protocols:

```swift
/// A helper protocol where `effectQueuePolicy` is set to `.runNewest(maxCount: 1)`.
public protocol Newest1EffectQueue: EffectQueue {}

/// A helper protocol where `effectQueuePolicy` is set to `.runOldest(maxCount: 1, .discardNew)`.
public protocol Oldest1DiscardNewEffectQueue: EffectQueue {}

/// A helper protocol where `effectQueuePolicy` is set to `.runOldest(maxCount: 1, .suspendNew)`.
public protocol Oldest1SuspendNewEffectQueue: EffectQueue {}
```

so that we can write in one-liner: `struct MyEffectQueue: Newest1EffectQueue {}`

### Example 1-5. Reducer composition

[Actomaton-Gallery](https://github.com/Actomaton/Actomaton-Gallery) provides a good example of how `Reducer`s can be combined together into one big Reducer using `Reducer.combine`.

In this example, [swift-case-paths](https://github.com/pointfreeco/swift-case-paths) is used as a counterpart of `WritableKeyPath`, so if we use both, we can easily construct Mega-Reducer without a hassle.

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

```swift
enum Root {} // just a namespace

extension Root {
    enum Action: Sendable {
        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, Sendable {
        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, Never> {
        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 })
        )
    }
}
```

To learn more about `CasePath`, visit the official site and tutorials:

- [swift-case-paths](https://github.com/pointfreeco/swift-case-paths)
- [Episode #87: The Case for Case Paths: Introduction](https://www.pointfree.co/episodes/ep87-the-case-for-case-paths-introduction)

## 2. ActomatonUI (SwiftUI & UIKit)

`Store` (from `ActomatonUI.framework`) provides a thin wrapper of `Actomaton` to work seamlessly in SwiftUI and UIKit world.

To find out more, check the following resources:

- [Actomaton-Gallery](https://github.com/Actomaton/Actomaton-Gallery) (example apps)
- [ActomatonUI | Documentation](https://actomaton.github.io/Actomaton/documentation/actomatonui/)
    - [RouteStore チュートリアル | Documentation](https://actomaton.github.io/Actomaton/documentation/actomatonui/oop-tutorial) (in Japanese)

## References

- [Functional iOS Architecture for SwiftUI - Speaker Deck](https://speakerdeck.com/inamiy/functional-ios-architecture-for-swiftui)
- [Functional iOS Architecture for SwiftUI (English)](https://zenn.dev/inamiy/books/3dd014a50f321040a047)
- [Swift アクターモデルと Elm Architecture の融合](https://speakerdeck.com/inamiy/iosdc-japan-2022) (Japanese)

`Actomaton` is a successor of the following projects:

- [Harvest](https://github.com/inamiy/Harvest) (using Combine with SwiftUI support)
- [ReactiveAutomaton](https://github.com/inamiy/ReactiveAutomaton) (using [ReactiveSwift](https://github.com/ReactiveCocoa/ReactiveSwift))
- [RxAutomaton](https://github.com/inamiy/RxAutomaton) (using [RxSwift](https://github.com/ReactiveX/RxSwift))

## License

[MIT](LICENSE)

Actomaton

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README