ObservableStore
A simple Elm-like Store for SwiftUI, based on ObservableObject.
Like Elm or Redux, ObservableStore.Store offers reliable unidirectional state and effects management. All state updates happen through actions passed to an update function. This guarantees your application will produce exactly the same state, given the same actions in the same order.
Because Store is an ObservableObject, it can be used anywhere in SwiftUI that ObservableObject would be used.
Store is meant to be used as part of a single app-wide, or major-view-wide component. It deliberately does not solve for nested components or nested stores. Following Elm, deeply nested components are avoided. Instead, it is designed for apps that use a single store, or perhaps one store per major view. Instead of decomposing an app into many stateful components, ObservableStore favors decomposing an app into many stateless views that share the same store and actions. Sub-views can be passed data through bare properties of store.state, or bindings, which can be created with store.binding, or share the store globally, through EnvironmentObject. See https://guide.elm-lang.org/architecture/ and https://guide.elm-lang.org/webapps/structure.html for more about this philosophy.
Example
A minimal example of Store used to increment a count with a button.
import SwiftUI
import os
import Combine
import ObservableStore
/// Actions
enum AppAction {
case increment
}
/// Services like API methods go here
struct AppEnvironment {
}
/// App state
struct AppState: Equatable {
var count = 0
/// State update function
static func update(
state: AppState,
environment: AppEnvironment,
action: AppAction
) -> Update
{
switch action {
case .
increment
:
var model
= state
model.
count
= model.
count
+
1
return
Update(
state: model)
}
}
}
struct
AppView:
View {
@StateObject
var store
=
Store(
update: AppState.
update,
state:
AppState(),
environment:
AppEnvironment()
)
var body:
some View {
VStack {
Text(
"The count is: \(store.state.count)")
Button(
action: {
// Send `.increment` action to store,
// updating state.
store.
send(
action: .
increment)
},
label: {
Text(
"Increment")
}
)
}
}
}
Store, state, updates, and actions
A Store is a source of truth for a state. It's an ObservableObject. You can use it in a view via @ObservedObject or @StateObject to power view rendering.
Store exposes a single @Published property, state, which represents your application state. All updates and effects to this state happen through actions sent to store.send.
state is read-only, and cannot be updated directly. Instead, like Elm, or Redux, all state changes happen through a single update function, with the signature:
(State, Environment, Action) -> Update
The Update returned is a small struct that contains a new state, plus any effects this state change should generate (more about that in a bit).
state is modeled as an Equatable type, typically a struct. Updates only mutate the state property on store when they are not equal. This means returning the same state twice is a no-op, and SwiftUI view body recalculations are only triggered if the state actually changes. Since state is Equatable, you can also make Store-based views EquatableViews, wherever appropriate.
Effects
Updates are also able to produce asyncronous effects via Combine publishers. This lets you schedule asyncronous things like HTTP requests, or database calls, in response to actions. Using effects, you can model everything via a deterministic sequence of actions, even asyncronous side-effects.
Effects are modeled as Combine Publishers which publish actions and never fail.
For convenience, ObservableStore defines a typealias for effect publishers:
public typealias Fx<Action> = AnyPublisher
Never>
The most common way to produce effects is by exposing methods on Environment that produce effects publishers. For example, an asyncronous call to an authentication API service might be implemented in Environment, where an effects publisher is used to signal whether authentication was successful.
struct Environment {
// ...
func authenticate(credentials: Credentials) -> AnyPublisher
Never> {
// ...
}
}
The update function can pass this effect through Update(state:fx:)
func update(
state: State,
environment: Environment,
action: Action
) -> Update
{
switch action {
// ...
case .
authenticate(
let credentials)
:
return
Update(
state: state,
fx: environment.
authenticate(
credentials: credentials)
)
}
}
Store will manage the lifecycle of any publishers passed through fx this way, piping the actions they produce back into the store, producing new states.
11 Dec 23, 2022
1.6k Jan 3, 2023
695 Jan 3, 2023
97 Dec 28, 2022
60 Feb 4, 2022
16 Dec 28, 2022
340 Dec 4, 2022
210 Nov 22, 2022
479 Dec 5, 2022
644 Dec 12, 2022
1.6k Dec 29, 2022
34 Sep 26, 2022
117 Sep 2, 2022
1.2k Dec 17, 2022
65 Dec 9, 2022
585 Dec 28, 2022
442 Dec 25, 2022
1.2k Dec 22, 2022