Substate

A tiny state management library for Swift.

Substate is a Redux-style state management library consisting of actions, models, and a store. The goal is to leverage Swift’s type system to provide the most ergonomic possible version of the pattern.

Access your Substate models from SwiftUI views, and dispatch actions to update them. Bootstrap your app from SwiftUI, and inject models into previews.

Extend Substate with logging, async tasks, time control, persistent models, action mapping logic, and a standalone debugging app. Connect your own services to Substate.

🎚 Models

import Substate

Describe your model using a simple value type. Add some Actions that will trigger model updates.

struct Counter: Model {
    var value = 0

    struct Increment: Action {}
    struct Decrement: Action {}

    mutating func update(action: Action) {
        switch action {
        case is Increment: value += 1
        case is Decrement: value -= 1
        default: ()
        }
    }
}

Then, conform to Model by adding an update(action:) method and define how the model should change when actions are received.

🎛 Nesting

Add other models alongside plain values to compose a state tree for your program.

struct Counter: Model {
    var value = 0
    var subCounter = SubCounter()
    mutating func update(action: Action) { ... }
}

Nested models are automatically detected and updated using their own update(action:) methods.

struct SubCounter: Model {
    var value = 0
    mutating func update(action: Action) { ... }
}

Reuse models in different places by making them generic with respect to their containers.

struct Tracker<Screen>: Model { ... }

struct NewsScreen: Model {
    var tracker = Tracker<NewsScreen>()
}

struct ProductsScreen: Model {
    var tracker = Tracker<ProductsScreen>()
}

⭐️ Views

import SubstateUI

Add @Model properties to access models from your views.

struct CounterView: View {
    @Model var counter: Counter
    @Model var subCounter: SubCounter

    var body: some View {
        Text("Count: \(counter.value)")
        Text("Subcount: \(subCounter.value)")
    }
}

Use an @Update property to trigger model updates.

struct CounterView: View {
    @Update var update

    var body: some View {
        Button("Increment", action: update(Counter.Increment()))
        Button("Decrement", action: update(Counter.Decrement()))
    }
}

🌟 Previews

Extend your model with data for use in different previews.

extension Counter {
    static let zero = Counter(value: 0)
    static let random = Counter(value: .random(in: 1...100))
}

Pass your predefined models in to the model view modifier.

struct CounterViewPreviews: PreviewProvider {
    static var previews: some View {
        CounterView().model(Counter.zero)
        CounterView().model(Counter.random)
    }
}

The model view modifier is an optional shorthand for environmentObject(Store(model:)).

🗄 Stores

Bootstrap your program by passing in your root state and a list of middleware to the store view modifier.

struct CounterApp: App {
    var scene: some Scene {
        CounterView().store(model: Counter(), middleware: [])
    }
}

The store view modifier is an optional shorthand for enviromentObject(Store(model:middleware:)).

For more control or to use Substate separately from SwiftUI, create a store manually.

let store = Store(model: Counter(), middleware: [])

Retrieve models directly from the store by passing the desired type to find.

store.find(Counter.self) // => Optional<Counter>
store.find(SubCounter.self) // => Optional<SubCounter>

Update your app’s model directly by passing an action to update.

store.update(Counter.Increment())