wip

Author: stephencelis

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

@@ -14,6 +14,8 @@ APIs, and these guides contain tips to do so.
 
 ## Topics
 
+- <doc:MigratingTo1.19>
+- <doc:MigratingTo1.18>
 - <doc:MigratingTo1.17.1>
 - <doc:MigratingTo1.17>
 - <doc:MigratingTo1.16>

Sources/ComposableArchitecture/Documentation.docc/Articles/MigrationGuides/MigratingTo1.18.md

@@ -0,0 +1,35 @@
+# Migrating to 1.18
+
+Stores now automatically cancel their in-flight effects when they deallocate. And another UIKit
+navigation helper has been introduced.
+
+## An effect lifecycle change
+
+In previous versions of the Composable Architecture, a root store's effects continued to run even
+after the store's lifetime. In 1.18, this leak has been fixed, and a root store's effects will be
+cancelled when the store deallocates.
+
+If you depend on a store's fire-and-forget effect to outlive the store, for example if you want to
+ensure an analytics or persistence effect proceeds without cancellation, perform this work in an
+unstructured task, instead:
+
+```diff
+ return .run { _ in
+-  await analytics.track(/* ... */)
++  Task {
++    await analytics.track(/* ... */)
++  }
+ }
+```
+
+## A UIKit navigation helper
+
+Our [Swift Navigation](https://github.com/pointfreeco/swift-navigation) library ships with many
+UIKit tools, and the Composable Architecture integrates with many of them, but up till now it has
+lacked support for trait-based navigation by pushing an element of ``StackState``.
+
+This has been fixed with a new endpoint on the `push` trait that takes a `state` parameter:
+
+```swift
+traitCollection.push(state: Path.State.detail(/* ... */))
+```

Sources/ComposableArchitecture/Documentation.docc/Articles/MigrationGuides/MigratingTo1.19.md

@@ -0,0 +1,60 @@
+# Migrating to 1.19
+
+Store internals have been rewritten for performance and future features, and are now compatible with
+SwiftUI's `@StateObject` property wrapper.
+
+## Overview
+
+There are no steps needed to migrate to 1.19 of the Composable Architecture, but there are a number
+of changes and improvements that have been made to the `Store` that one should be aware of.
+
+## Store internals rewrite
+
+The store's internals have been rewritten to improved performance and to pave the way for future
+features. While this should not be a breaking change, with any rewrite it is important to thoroughly
+test your application after upgrading.
+
+## StateObject compatibility
+
+SwiftUI's `@State` and `@StateObject` allow a view to own a value or object over time, ensuring that
+when a parent view is recomputed, the view-local state isn't recreated from scratch.
+
+One important difference between `@State` and `@StateObject` is that `@State`'s initializer is
+eager, while `@StateObject`'s is lazy. Because of this, if you initialize a root `Store` to be held
+in `@State`, stores will be initialized (and immediately discarded) whenever the parent view's body
+is computed.
+
+To avoid the creation of these stores, one can now assign the store to a `@StateObject`, instead:
+
+```swift
+struct FeatureView: View {
+  @StateObject var store: StoreOf<Feature>
+
+  init() {
+    _store = StateObject(
+      // This expression is only evaluated the first time the parent view is computed.
+      wrappedValue: Store(initialState: Feature.State()) {
+        Feature()
+      }
+    )
+  }
+
+  var body: some View { /* ... */ }
+}
+```
+
+> Important: The store's `ObservableObject` conformance does not have any impact on the actual
+> observability of the store. You should continue to rely on the ``ObservableState()`` macro for
+> observation.
+
+## Initial actions
+
+A new `initialAction` has been introduced to the `Store` that will immediately kick off an initial
+action when the store is created. This is an alternative to waiting for an `onAppear` or `task`
+view modifier to evaluate.
+
+```swift
+Store(initialState: Feature.State(), initialAction: .initialize) {
+  Feature()
+}
+```

Sources/ComposableArchitecture/Observation/Store+Observation.swift

@@ -207,7 +207,7 @@ extension ObservedObject.Wrapper {
     self[
       dynamicMember:
         \.[
-          id: self[dynamicMember: \.__currentState].wrappedValue[keyPath: state]
+          id: self[dynamicMember: \._currentState].wrappedValue[keyPath: state]
             .flatMap(_identifiableID),
           state: state,
           action: action,
@@ -220,8 +220,9 @@ extension ObservedObject.Wrapper {
     ]
   }
 }
+
 extension Store {
-  fileprivate var __currentState: State {
+  fileprivate var _currentState: State {
     get { currentState }
     set {}
   }