Merge branch 'main' into protocol-beta

Author: stephencelis

Sources/ComposableArchitecture/Documentation.docc/Articles/Performance.md

@@ -74,18 +74,102 @@ This means `AppView` does not actually need to observe any state changes. This v
 created a single time, whereas if we observed the store then it would re-compute every time a single
 thing changed in either the activity, search or profile child features.
 
-If sometime in the future we do actually need some state from the store, we can create a localized
-"view state" struct that holds only the bare essentials of state that the view needs to do its
-job. For example, suppose the activity state holds an integer that represents the number of 
-unread activities. Then we could observe changes to only that piece of state like so:
+If sometime in the future we do actually need some state from the store, we can start to observe
+only the bare essentials of state necessary for the view to do its job. For example, suppose that 
+we need access to the currently selected tab in state:
+
+```swift
+struct AppState {
+  var activity: ActivityState
+  var search: SearchState
+  var profile: ProfileState
+  var selectedTab: Tab
+  enum Tab { case activity, search, profile }
+}
+```
+
+Then we can observe this state so that we can construct a binding to `selectedTab` for the tab view:
+
+```swift
+struct AppView: View {
+  let store: Store<AppState, AppAction>
+
+  var body: some View {
+    WithViewStore(self.store, observe: { $0 }) { viewStore in
+      TabView(selection: viewStore.binding(send: AppAction.tabSelected) {
+        ActivityView(
+          store: self.store.scope(state: \.activity, action: AppAction.activity)
+        )
+        .tag(AppState.Tab.activity)
+        SearchView(
+          store: self.store.scope(state: \.search, action: AppAction.search)
+        )
+        .tag(AppState.Tab.search)
+        ProfileView(
+          store: self.store.scope(state: \.profile, action: AppAction.profile)
+        )
+        .tag(AppState.Tab.profile)
+      }
+    }
+  }
+}
+```
+
+However, this style of state observation is terribly inefficient since _every_ change to `AppState`
+will cause the view to re-compute even though the only piece of state we actually care about is
+the `selectedTab`. The reason we are observing too much state is because we use `observe: { $0 }`
+in the construction of the ``WithViewStore``, which means the view store will observe all of state.
+
+To chisel away at the observed state you can provide a closure for that argument that plucks out
+the state the view needs. In this case the view only needs a single field:
+
+```swift
+WithViewStore(self.store, observe: \.selectedTab) { viewStore in
+  TabView(selection: viewStore.binding(send: AppAction.tabSelected) {
+    // ...
+  }
+}
+```
+
+In the future, the view may need access to more state. For example, suppose `ActivityState` holds
+onto an `unreadCount` integer to represent how many new activities you have. There's no need to
+observe _all_ of `ActivityState` to get access to this one field. You can observe just the one 
+field.
+
+Technically you can do this by mapping your state into a tuple, but because tuples are not 
+`Equatable` you will need to provide an explicit `removeDuplicates` argument:
+
+```swift
+WithViewStore(
+  self.store, 
+  observe: { (selectedTab: $0.selectedTab, unreadActivityCount: $0.activity.unreadCount) },
+  removeDuplicates: ==
+) { viewStore in 
+  TabView(selection: viewStore.binding(\.selectedTab, send: AppAction.tabSelected) {
+    ActivityView(
+      store: self.store.scope(state: \.activity, action: AppAction.activity)
+    )
+    .tag(AppState.Tab.activity)
+    .badge("\(viewStore.state)")
+
+    // ...
+  }
+}
+```
+
+Alternatively, and recommended, you can introduce a lightweight, equatable `ViewState` struct
+nested inside your view whose purpose is to transform the `Store`'s full state into the bare
+essentials of what the view needs:
 
 ```swift
 struct AppView: View {
   let store: StoreOf<AppReducer>
 
-  struct ViewState {
+  struct ViewState: Equatable {
+    let selectedTab: AppState.Tab
     let unreadActivityCount: Int
     init(state: AppReducer.State) {
+      self.selectedTab = state.selectedTab
       self.unreadActivityCount = state.activity.unreadCount
     }
   }
@@ -106,24 +190,25 @@ struct AppView: View {
 }
 ```
 
-Now the `AppView` will re-compute its body only when `activity.unreadCount` changes. In particular,
-no changes to the search or profile features will cause the view to re-compute, and that greatly
-reduces how often the view must re-compute.
+This gives you maximum flexibilty in the future for adding new fields to `ViewState` without making
+your view convoluated.
 
 This technique for reducing view re-computations is most effective towards the root of your app
 hierarchy and least effective towards the leaf nodes of your app. Root features tend to hold lots
 of state that its view does not need, such as child features, and leaf features tend to only hold
 what's necessary. If you are going to employ this technique you will get the most benefit by
-applying it to views closer to the root.
+applying it to views closer to the root. At leaf features and views that need access to most
+of the state, it is fine to continue using `observe: { $0 }` to observe all of the state in the 
+store.
 
 ### CPU intensive calculations
 
 Reducers are run on the main thread and so they are not appropriate for performing intense CPU
 work. If you need to perform lots of CPU-bound work, then it is more appropriate to use an
-``Effect``, which will operate in the cooperative thread pool, and then send it's output back into
-the system via an action. You should also make sure to perform your CPU intensive work in a
-cooperative manner by periodically suspending with `Task.yield()` so that you do not block a thread
-in the cooperative pool for too long.
+``Effect``, which will operate in the cooperative thread pool, and then send actions back into the
+system. You should also make sure to perform your CPU intensive work in a cooperative manner by
+periodically suspending with `Task.yield()` so that you do not block a thread in the cooperative
+pool for too long.
 
 So, instead of performing intense work like this in your reducer:
 

Sources/ComposableArchitecture/Documentation.docc/Extensions/Deprecations/EffectDeprecations.md

@@ -28,6 +28,7 @@ Avoid using deprecated APIs in your app. Select a method to see the replacement
 
 ### Combine integration
 
+- ``Effect/Output``
 - ``Effect/init(_:)``
 - ``Effect/init(value:)``
 - ``Effect/init(error:)``

Sources/ComposableArchitecture/Documentation.docc/Extensions/Deprecations/SwiftUIDeprecations.md

@@ -8,7 +8,27 @@ Avoid using deprecated APIs in your app. Select a method to see the replacement
 
 ## Topics
 
-### View state
+### `WithViewStore`
+
+- ``WithViewStore/init(_:content:file:line:)-1gjbi``
+- ``WithViewStore/init(_:content:file:line:)-2uj44``
+- ``WithViewStore/init(_:content:file:line:)-5vj3w``
+- ``WithViewStore/init(_:content:file:line:)-5zsmz``
+- ``WithViewStore/init(_:content:file:line:)-7kai``
+- ``WithViewStore/init(_:file:line:content:)-4xog0``
+- ``WithViewStore/init(_:file:line:content:)-55smh``
+- ``WithViewStore/init(_:file:line:content:)-7qkc1``
+- ``WithViewStore/init(_:file:line:content:)-8b21b``
+- ``WithViewStore/init(_:file:line:content:)-9b6e2``
+- ``WithViewStore/init(_:removeDuplicates:content:file:line:)-1lyhl``
+- ``WithViewStore/init(_:removeDuplicates:content:file:line:)-35xje``
+- ``WithViewStore/init(_:removeDuplicates:content:file:line:)-8zzun``
+- ``WithViewStore/init(_:removeDuplicates:content:file:line:)-9atby``
+- ``WithViewStore/init(_:removeDuplicates:file:line:content:)``
+- ``WithViewStore/Action``
+- ``WithViewStore/State``
+
+### View State
 
 - ``ActionSheetState``
 

Sources/ComposableArchitecture/Effect.swift

@@ -3,10 +3,9 @@ import Foundation
 import SwiftUI
 import XCTestDynamicOverlay
 
-/// The ``Effect`` type encapsulates a unit of work that can be kicked off from the reducer into the
-/// outside world, and can feed data back to the ``Store`` and into the reducer. It is the perfect
-/// place to do side effects, such as network requests, saving/loading from disk, creating timers,
-/// interacting with dependencies, and more.
+/// The ``Effect`` type encapsulates a unit of work that can be run in the outside world, and can
+/// feed actions back to the ``Store``. It is the perfect place to do side effects, such as network
+/// requests, saving/loading from disk, creating timers, interacting with dependencies, and more.
 ///
 /// Effects are returned from reducers so that the ``Store`` can perform the effects after the
 /// reducer is done running.
@@ -33,12 +32,12 @@ import XCTestDynamicOverlay
 /// > This is only an issue if using the Combine interface of ``Effect`` as mentioned above. If you
 /// you are using Swift's concurrency tools and the `.task`, `.run` and `.fireAndForget` functions
 /// on ``Effect``, then threading is automatically handled for you.
-public struct Effect<Output, Failure: Error> {
+public struct Effect<Action, Failure: Error> {
   @usableFromInline
   enum Operation {
     case none
-    case publisher(AnyPublisher<Output, Failure>)
-    case run(TaskPriority? = nil, @Sendable (Send<Output>) async -> Void)
+    case publisher(AnyPublisher<Action, Failure>)
+    case run(TaskPriority? = nil, @Sendable (Send<Action>) async -> Void)
   }
 
   @usableFromInline
@@ -116,8 +115,8 @@ extension Effect where Failure == Never {
   /// - Returns: An effect wrapping the given asynchronous work.
   public static func task(
     priority: TaskPriority? = nil,
-    operation: @escaping @Sendable () async throws -> Output,
-    catch handler: (@Sendable (Error) async -> Output)? = nil,
+    operation: @escaping @Sendable () async throws -> Action,
+    catch handler: (@Sendable (Error) async -> Action)? = nil,
     file: StaticString = #file,
     fileID: StaticString = #fileID,
     line: UInt = #line
@@ -175,7 +174,7 @@ extension Effect where Failure == Never {
   /// }
   /// ```
   ///
-  /// Then you could attach to it in a `run` effect by using `for await` and sending each output of
+  /// Then you could attach to it in a `run` effect by using `for await` and sending each action of
   /// the stream back into the system:
   ///
   /// ```swift
@@ -203,8 +202,8 @@ extension Effect where Failure == Never {
   /// - Returns: An effect wrapping the given asynchronous work.
   public static func run(
     priority: TaskPriority? = nil,
-    operation: @escaping @Sendable (Send<Output>) async throws -> Void,
-    catch handler: (@Sendable (Error, Send<Output>) async -> Void)? = nil,
+    operation: @escaping @Sendable (Send<Action>) async throws -> Void,
+    catch handler: (@Sendable (Error, Send<Action>) async -> Void)? = nil,
     file: StaticString = #file,
     fileID: StaticString = #fileID,
     line: UInt = #line
@@ -448,11 +447,11 @@ extension Effect {
 
   /// Transforms all elements from the upstream effect with a provided closure.
   ///
-  /// - Parameter transform: A closure that transforms the upstream effect's output to a new output.
+  /// - Parameter transform: A closure that transforms the upstream effect's action to a new action.
   /// - Returns: A publisher that uses the provided closure to map elements from the upstream effect
   ///   to new elements that it then publishes.
   @inlinable
-  public func map<T>(_ transform: @escaping (Output) -> T) -> Effect<T, Failure> {
+  public func map<T>(_ transform: @escaping (Action) -> T) -> Effect<T, Failure> {
     switch self.operation {
     case .none:
       return .none
@@ -462,11 +461,9 @@ extension Effect {
       return .init(
         operation: .run(priority) { send in
           await operation(
-            .init(
-              send: { output in
-                send(transform(output))
-              }
-            )
+            Send { action in
+              send(transform(action))
+            }
           )
         }
       )

Sources/ComposableArchitecture/Effects/Cancellation.swift

@@ -39,7 +39,7 @@ extension Effect {
             ()
               -> Publishers.HandleEvents<
                 Publishers.PrefixUntilOutput<
-                  AnyPublisher<Output, Failure>, PassthroughSubject<Void, Never>
+                  AnyPublisher<Action, Failure>, PassthroughSubject<Void, Never>
                 >
               > in
             cancellablesLock.lock()

Sources/ComposableArchitecture/Effects/Publisher.swift

@@ -5,13 +5,15 @@ import Combine
 @available(tvOS, deprecated: 9999.0)
 @available(watchOS, deprecated: 9999.0)
 extension Effect: Publisher {
+  public typealias Output = Action
+
   public func receive<S: Combine.Subscriber>(
     subscriber: S
-  ) where S.Input == Output, S.Failure == Failure {
+  ) where S.Input == Action, S.Failure == Failure {
     self.publisher.subscribe(subscriber)
   }
 
-  var publisher: AnyPublisher<Output, Failure> {
+  var publisher: AnyPublisher<Action, Failure> {
     switch self.operation {
     case .none:
       return Empty().eraseToAnyPublisher()
@@ -75,7 +77,7 @@ extension Effect {
   @available(macOS, deprecated: 9999.0, message: "Wrap the value in 'Effect.task', instead.")
   @available(tvOS, deprecated: 9999.0, message: "Wrap the value in 'Effect.task', instead.")
   @available(watchOS, deprecated: 9999.0, message: "Wrap the value in 'Effect.task', instead.")
-  public init(value: Output) {
+  public init(value: Action) {
     self.init(Just(value).setFailureType(to: Failure.self))
   }
 
@@ -147,7 +149,7 @@ extension Effect {
   @available(tvOS, deprecated: 9999.0, message: "Use 'Effect.task', instead.")
   @available(watchOS, deprecated: 9999.0, message: "Use 'Effect.task', instead.")
   public static func future(
-    _ attemptToFulfill: @escaping (@escaping (Result<Output, Failure>) -> Void) -> Void
+    _ attemptToFulfill: @escaping (@escaping (Result<Action, Failure>) -> Void) -> Void
   ) -> Self {
     Deferred { Future(attemptToFulfill) }.eraseToEffect()
   }
@@ -181,7 +183,7 @@ extension Effect {
   @available(macOS, deprecated: 9999.0, message: "Use 'Effect.task', instead.")
   @available(tvOS, deprecated: 9999.0, message: "Use 'Effect.task', instead.")
   @available(watchOS, deprecated: 9999.0, message: "Use 'Effect.task', instead.")
-  public static func result(_ attemptToFulfill: @escaping () -> Result<Output, Failure>) -> Self {
+  public static func result(_ attemptToFulfill: @escaping () -> Result<Action, Failure>) -> Self {
     Deferred { Future { $0(attemptToFulfill()) } }.eraseToEffect()
   }
 
@@ -247,7 +249,7 @@ extension Effect {
     //     iOS 13.3, but to remain compatible with iOS 13.2 and higher we need to do a little
     //     trickery to make sure the deferred publisher completes.
     let dependencies = DependencyValues.current
-    return Deferred { () -> Publishers.CompactMap<Result<Output?, Failure>.Publisher, Output> in
+    return Deferred { () -> Publishers.CompactMap<Result<Action?, Failure>.Publisher, Action> in
       DependencyValues.$current.withValue(dependencies) {
         try? work()
       }
@@ -297,7 +299,7 @@ extension Effect where Failure == Error {
     watchOS, deprecated: 9999.0,
     message: "Throw and catch errors directly in 'Effect.task' and 'Effect.run', instead."
   )
-  public static func catching(_ work: @escaping () throws -> Output) -> Self {
+  public static func catching(_ work: @escaping () throws -> Action) -> Self {
     .future { $0(Result { try work() }) }
   }
 }

Sources/ComposableArchitecture/Effects/Publisher/Throttling.swift

@@ -25,7 +25,7 @@ extension Effect {
       return .none
     case .publisher, .run:
       return self.receive(on: scheduler)
-        .flatMap { value -> AnyPublisher<Output, Failure> in
+        .flatMap { value -> AnyPublisher<Action, Failure> in
           throttleLock.lock()
           defer { throttleLock.unlock() }
 
@@ -35,7 +35,7 @@ extension Effect {
             return Just(value).setFailureType(to: Failure.self).eraseToAnyPublisher()
           }
 
-          let value = latest ? value : (throttleValues[id] as! Output? ?? value)
+          let value = latest ? value : (throttleValues[id] as! Action? ?? value)
           throttleValues[id] = value
 
           guard throttleTime.distance(to: scheduler.now) < interval else {

Sources/ComposableArchitecture/Effects/Publisher/Timer.swift

@@ -95,7 +95,7 @@ extension Effect where Failure == Never {
     tolerance: S.SchedulerTimeType.Stride? = nil,
     on scheduler: S,
     options: S.SchedulerOptions? = nil
-  ) -> Self where S.SchedulerTimeType == Output {
+  ) -> Self where S.SchedulerTimeType == Action {
     Publishers.Timer(every: interval, tolerance: tolerance, scheduler: scheduler, options: options)
       .autoconnect()
       .setFailureType(to: Failure.self)
@@ -129,7 +129,7 @@ extension Effect where Failure == Never {
     tolerance: S.SchedulerTimeType.Stride? = nil,
     on scheduler: S,
     options: S.SchedulerOptions? = nil
-  ) -> Self where S.SchedulerTimeType == Output {
+  ) -> Self where S.SchedulerTimeType == Action {
     self.timer(
       id: ObjectIdentifier(id),
       every: interval,

Sources/ComposableArchitecture/Internal/Create.swift

@@ -171,18 +171,18 @@ extension Publishers.Create.Subscription: CustomStringConvertible {
 
 extension Effect {
   public struct Subscriber {
-    private let _send: (Output) -> Void
+    private let _send: (Action) -> Void
     private let _complete: (Subscribers.Completion<Failure>) -> Void
 
     init(
-      send: @escaping (Output) -> Void,
+      send: @escaping (Action) -> Void,
       complete: @escaping (Subscribers.Completion<Failure>) -> Void
     ) {
       self._send = send
       self._complete = complete
     }
 
-    public func send(_ value: Output) {
+    public func send(_ value: Action) {
       self._send(value)
     }