Reintroduce ViewStore, remove CursorProtocol (#25)

Author: gordonbrander

README.md

@@ -4,9 +4,9 @@ A simple Elm-like Store for SwiftUI, based on [ObservableObject](https://develop
 
 ObservableStore helps you craft more reliable apps by centralizing all of your application state into one place, and giving you a deterministic system for managing state changes and side-effects. 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. If you’ve ever used [Elm](https://guide.elm-lang.org/architecture/) or [Redux](https://redux.js.org/), you get the gist.
 
-Because `Store` is an [ObservableObject](https://developer.apple.com/documentation/combine/observableobject), and can be used anywhere in SwiftUI that ObservableObject would be used.
+Because `Store` is an [ObservableObject](https://developer.apple.com/documentation/combine/observableobject), it can be used anywhere in SwiftUI that ObservableObject would be used.
 
-You can centralize all application state in a single Store, use the Store as an [`EnvironmentObject`](https://developer.apple.com/documentation/swiftui/environmentobject), or create multiple `@StateObject` stores. You can also pass scoped parts of a store down to sub-views as `@Bindings` or as ordinary bare properties of `store.state`.
+You can centralize all application state in a single Store, use the Store as an [`EnvironmentObject`](https://developer.apple.com/documentation/swiftui/environmentobject), or create multiple `@StateObject` stores. You can also pass scoped parts of a store down to sub-views as `@Bindings`, as scoped `ViewStores`, or as ordinary bare properties of `store.state`.
 
 ## Example
 
@@ -187,14 +187,13 @@ Button("Set color to red") {
 
 ## Bindings
 
-`Binding(get:send:tag:)` lets you create a [binding](https://developer.apple.com/documentation/swiftui/binding) that represents some part of the store state. The `get` closure reads the state into a value, and the `tag` closure wraps the value set on the binding in an action. The result is a binding that can be passed to any vanilla SwiftUI view, but changes state only through deterministic updates.
+`StoreProtocol.binding(get:tag:)` lets you create a [binding](https://developer.apple.com/documentation/swiftui/binding) that represents some part of a store state. The `get` closure reads the state into a value, and the `tag` closure wraps the value set on the binding in an action. The result is a binding that can be passed to any vanilla SwiftUI view, but changes state only through deterministic updates.
 
 ```swift
 TextField(
     "Username"
-    text: Binding(
-        get: { store.state.username },
-        send: store.send,
+    text: store.binding(
+        get: { state in state.username },
         tag: { username in .setUsername(username) }
     )
 )
@@ -205,9 +204,9 @@ Bottom line, because Store is just an ordinary [ObservableObject](https://develo
 
 ## Creating scoped child components
 
-We can also create component-scoped state and send callbacks from a shared root store. This allows you to create apps from free-standing components that all have their own local state, actions, and update functions, but share the same underlying root store.
+We can also create `ViewStore`s that represent just a scoped part of the root store. You can think of them as being like a binding, but they expose a `StoreProtocol` interface, instead of a binding interface. This allows you to create apps from free-standing components that all have their own local state, actions, and update functions, but share the same underlying root store.
 
-Imagine we have a vanilla SWiftUI child view that looks something like this:
+Imagine we have a SWiftUI child view that looks something like this:
 
 ```swift
 enum ChildAction {
@@ -232,12 +231,11 @@ struct ChildModel: ModelProtocol {
 }
 
 struct ChildView: View {
-    var state: ChildModel
-    var send: (ChildAction) -> Void
+    var store: ViewStore<ChildModel>
 
     var body: some View {
         VStack {
-            Text("Count \(state.count)")
+            Text("Count \(store.state.count)")
             Button(
                 "Increment",
                 action: {
@@ -249,23 +247,23 @@ struct ChildView: View {
 }
 ```
 
-Let's integrate this child component with a parent component. This is where `CursorProtocol` comes in. It defines three things:
+To integrate this child component with a parent component, we're going to need 3 functions:
 
-- A way to `get` a local state from the root state
-- A way to `set` a local state on a root state
-- A way to `tag` a local action so it becomes a root action
+- A function to `get` a local state from the root state
+- A function to `set` a local state on a root state
+- A function to `tag` a local action so it becomes a root action
 
-Together, these functions give us everything we need to map from child to parent.
+Together, these functions give us everything we need to map from child domain to a parent domain. Let's define them as static functions so we have them all in one place.
 
 ```swift
-struct AppChildCursor: CursorProtocol {
+struct AppChildCursor {
     /// Get child state from parent
-    static func get(state: ParentModel) -> ChildModel {
+    static func get(_ state: ParentModel) -> ChildModel {
         state.child
     }
 
     /// Set child state on parent
-    static func set(state: ParentModel, inner child: ChildModel) -> ParentModel {
+    static func set(_ state: ParentModel, _ child: ChildModel) -> ParentModel {
         var model = state
         model.child = child
         return model
@@ -281,25 +279,28 @@ struct AppChildCursor: CursorProtocol {
 }
 ```
 
-Let's start by integrating the child view with the parent view. We pass down part of the parent state to the child, along with a scoped `send` callback that will map child actions to parent actions. We can create this scoped `send` with `Address.forward`, passing it the store's send method, and the cursor's tag function.
+Ok, now that we have everything we need to map from the parent domain to the child domain, let's integrate the child view with the parent view.
+
+We call the `store.viewStore(get:tag:)` method to create a scoped ViewStore from our store, and pass it the appropriate cursor functions.
 
 ```swift
 struct ContentView: View {
     @StateObject private var store: Store<AppModel>
 
     var body: some View {
         ChildView(
-            state: store.state.child,
-            send: Address.forward(
-                send: store.send,
+            store: store.viewStore(
+                get: AppChildCursor.get,
                 tag: AppChildCursor.tag
             )
         )
     }
 }
 ```
 
-Next, we want to integrate the child's update function into the parent update function. Luckily, `CursorProtocol` synthesizes an `update` function that automatically maps child state and actions to parent state and actions.
+Note that `.viewStore(get:tag:)` is an extension of `StoreProtocol`, so you can call it on `Store` or `ViewStore` to create arbitrarily nested components!
+
+Next, we want to integrate the child's update function into the parent update function. Luckily, `ModelProtocol` synthesizes an `update(get:set:tag:state:action:environment)` function that automatically maps child state and actions to parent state and actions.
 
 ```swift
 enum AppAction {
@@ -316,7 +317,10 @@ struct AppModel: ModelProtocol {
     ) -> Update<AppModel> {
         switch {
         case .child(let action):
-            return AppChildCursor.update(
+            return update(
+                get: AppChildCursor.get,
+                set: AppChildCursor.set,
+                tag: AppChildCursor.tag,
                 state: state,
                 action: action,
                 environment: ()
@@ -326,4 +330,4 @@ struct AppModel: ModelProtocol {
 }
 ```
 
-This tagging/update pattern also gives parent components an opportunity to intercept and handle child actions in special ways.
+And that's it! We have successfully created an isolated child component and integrated it into a parent component. This tagging/update pattern also gives parent components an opportunity to intercept and handle child actions in special ways.

Sources/ObservableStore/ObservableStore.swift

@@ -54,6 +54,45 @@ extension ModelProtocol {
     }
 }
 
+extension ModelProtocol {
+    /// Update a child state within a parent state.
+    /// This update offers a convenient way to call child update functions
+    /// from the parent domain, and get parent-domain states and actions
+    /// back from it.
+    ///
+    /// - `get` gets the child's state
+    /// - `set` sets the child's state within the parent state
+    /// - `tag` tags child actions, turning them into parent actions
+    /// - `state` the outer state
+    /// - `action` the inner action
+    /// - `environment` the environment for the update function
+    /// - Returns a new outer state
+    public static func update<ViewModel: ModelProtocol>(
+        get: (Self) -> ViewModel?,
+        set: (Self, ViewModel) -> Self,
+        tag: @escaping (ViewModel.Action) -> Self.Action,
+        state: Self,
+        action viewAction: ViewModel.Action,
+        environment: ViewModel.Environment
+    ) -> Update<Self> {
+        // If getter returns nil (as in case of a list item that no longer
+        // exists), do nothing.
+        guard let inner = get(state) else {
+            return Update(state: state)
+        }
+        let next = ViewModel.update(
+            state: inner,
+            action: viewAction,
+            environment: environment
+        )
+        return Update(
+            state: set(state, next.state),
+            fx: next.fx.map(tag).eraseToAnyPublisher(),
+            transaction: next.transaction
+        )
+    }
+}
+
 /// Update represents a state change, together with an `Fx` publisher,
 /// and an optional `Transaction`.
 public struct Update<Model: ModelProtocol> {
@@ -258,138 +297,59 @@ where Model: ModelProtocol
     }
 }
 
-public struct Address {
-    /// Forward transform an address (send function) into a local address.
-    /// View-scoped actions are tagged using `tag` before being forwarded to
-    /// `send.`
-    public static func forward<Action, ViewAction>(
-        send: @escaping (Action) -> Void,
-        tag: @escaping (ViewAction) -> Action
-    ) -> (ViewAction) -> Void {
-        { viewAction in send(tag(viewAction)) }
-    }
-}
-
-/// A cursor provides a complete description of how to map from one component
-/// domain to another.
-public protocol CursorProtocol {
-    associatedtype Model: ModelProtocol
-    associatedtype ViewModel: ModelProtocol
-
-    /// Get an inner state from an outer state
-    static func get(state: Model) -> ViewModel
+public struct ViewStore<ViewModel: ModelProtocol>: StoreProtocol {
+    private var _send: (ViewModel.Action) -> Void
+    public var state: ViewModel
 
-    /// Set an inner state on an outer state, returning an outer state
-    static func set(state: Model, inner: ViewModel) -> Model
-
-    /// Tag an inner action, transforming it into an outer action
-    static func tag(_ action: ViewModel.Action) -> Model.Action
+    public init(
+        state: ViewModel,
+        send: @escaping (ViewModel.Action) -> Void
+    ) {
+        self.state = state
+        self._send = send
+    }
+        
+    public func send(_ action: ViewModel.Action) {
+        self._send(action)
+    }
 }
 
-extension CursorProtocol {
-    /// Update an outer state through a cursor.
-    /// CursorProtocol.update offers a convenient way to call child
-    /// update functions from the parent domain, and get parent-domain
-    /// states and actions back from it.
-    ///
-    /// - `state` the outer state
-    /// - `action` the inner action
-    /// - `environment` the environment for the update function
-    /// - Returns a new outer state
-    public static func update(
-        state: Model,
-        action viewAction: ViewModel.Action,
-        environment: ViewModel.Environment
-    ) -> Update<Model> {
-        let next = ViewModel.update(
-            state: get(state: state),
-            action: viewAction,
-            environment: environment
-        )
-        return Update(
-            state: set(state: state, inner: next.state),
-            fx: next.fx.map(tag).eraseToAnyPublisher(),
-            transaction: next.transaction
+extension ViewStore {
+    public init<Action>(
+        state: ViewModel,
+        send: @escaping (Action) -> Void,
+        tag: @escaping (ViewModel.Action) -> Action
+    ) {
+        self.init(
+            state: state,
+            send: { action in send(tag(action)) }
         )
     }
 }
 
-public protocol KeyedCursorProtocol {
-    associatedtype Key
-    associatedtype Model: ModelProtocol
-    associatedtype ViewModel: ModelProtocol
-
-    /// Get an inner state from an outer state
-    static func get(state: Model, key: Key) -> ViewModel?
-
-    /// Set an inner state on an outer state, returning an outer state
-    static func set(state: Model, inner: ViewModel, key: Key) -> Model
-
-    /// Tag an inner action, transforming it into an outer action
-    static func tag(action: ViewModel.Action, key: Key) -> Model.Action
-}
-
-extension KeyedCursorProtocol {
-    /// Update an inner state within an outer state through a keyed cursor.
-    /// This cursor type is useful when looking up children in dynamic lists
-    /// such as arrays or dictionaries.
-    ///
-    /// - `state` the outer state
-    /// - `action` the inner action
-    /// - `environment` the environment for the update function
-    /// - `key` a key uniquely representing this model in the parent domain
-    /// - Returns an update for a new outer state or nil
-    public static func update(
-        state: Model,
-        action viewAction: ViewModel.Action,
-        environment viewEnvironment: ViewModel.Environment,
-        key: Key
-    ) -> Update<Model>? {
-        guard let viewModel = get(state: state, key: key) else {
-            return nil
-        }
-        let next = ViewModel.update(
-            state: viewModel,
-            action: viewAction,
-            environment: viewEnvironment
-        )
-        return Update(
-            state: set(state: state, inner: next.state, key: key),
-            fx: next.fx
-                .map({ viewAction in Self.tag(action: viewAction, key: key) })
-                .eraseToAnyPublisher(),
-            transaction: next.transaction
+extension StoreProtocol {
+    /// Create a viewStore from a StoreProtocol
+    public func viewStore<ViewModel: ModelProtocol>(
+        get: (Self.Model) -> ViewModel,
+        tag: @escaping (ViewModel.Action) -> Self.Model.Action
+    ) -> ViewStore<ViewModel> {
+        ViewStore(
+            state: get(self.state),
+            send: self.send,
+            tag: tag
         )
     }
+}
 
-    /// Update an inner state within an outer state through a keyed cursor.
-    /// This cursor type is useful when looking up children in dynamic lists
-    /// such as arrays or dictionaries.
-    ///
-    /// This version of update always returns an `Update`. If the child model
-    /// cannot be found at key, then it returns an update for the same state
-    /// (noop), effectively ignoring the action.
-    ///
-    /// - `state` the outer state
-    /// - `action` the inner action
-    /// - `environment` the environment for the update function
-    /// - `key` a key uniquely representing this model in the parent domain
-    /// - Returns an update for a new outer state or nil
-    public static func update(
-        state: Model,
-        action viewAction: ViewModel.Action,
-        environment viewEnvironment: ViewModel.Environment,
-        key: Key
-    ) -> Update<Model> {
-        guard let next = update(
-            state: state,
-            action: viewAction,
-            environment: viewEnvironment,
-            key: key
-        ) else {
-            return Update(state: state)
-        }
-        return next
+public struct Address {
+    /// Forward transform an address (send function) into a local address.
+    /// View-scoped actions are tagged using `tag` before being forwarded to
+    /// `send.`
+    public static func forward<Action, ViewAction>(
+        send: @escaping (Action) -> Void,
+        tag: @escaping (ViewAction) -> Action
+    ) -> (ViewAction) -> Void {
+        { viewAction in send(tag(viewAction)) }
     }
 }
 
@@ -410,3 +370,15 @@ extension Binding {
         )
     }
 }
+
+extension StoreProtocol {
+    public func binding<Value>(
+        get: @escaping (Self.Model) -> Value,
+        tag: @escaping (Value) -> Self.Model.Action
+    ) -> Binding<Value> {
+        Binding(
+            get: { get(self.state) },
+            set: { value in self.send(tag(value)) }
+        )
+    }
+}