feat: Atom Coordinator API (#24)

Author: ra1028

Examples/Packages/iOS/Sources/ExampleMap/Atoms.swift

@@ -14,13 +14,6 @@ final class LocationObserver: NSObject, ObservableObject, CLLocationManagerDeleg
         manager.delegate = self
     }
 
-    convenience override init() {
-        let manager = CLLocationManager()
-        manager.desiredAccuracy = kCLLocationAccuracyBest
-
-        self.init(manager: manager)
-    }
-
     func locationManagerDidChangeAuthorization(_ manager: CLLocationManager) {
         objectWillChange.send()
 
@@ -45,8 +38,14 @@ final class LocationObserver: NSObject, ObservableObject, CLLocationManagerDeleg
 }
 
 struct LocationObserverAtom: ObservableObjectAtom, Hashable {
+    func makeCoordinator() -> LocationManagerProtocol {
+        let manager = CLLocationManager()
+        manager.desiredAccuracy = kCLLocationAccuracyBest
+        return manager
+    }
+
     func object(context: Context) -> LocationObserver {
-        LocationObserver()
+        LocationObserver(manager: context.coordinator)
     }
 }
 

README.md

@@ -23,7 +23,7 @@
   - [Atoms](#atoms)
   - [Modifiers](#modifiers)
   - [Property Wrappers](#property-wrappers)
-  - [Contexts](#contexts)
+  - [Context](#context)
   - [KeepAlive](#keepalive)
   - [Suspense](#suspense)
   - [Testing](#testing)
@@ -903,13 +903,13 @@ await context.refresh(FetchMoviesAtom())
 context.reset(CounterAtom())
 ```
 
-The context also provides a flexible solution for passing dynamic parameters to atom's initializer. See [Contexts](#contexts) section for more detail.
+The context also provides a flexible solution for passing dynamic parameters to atom's initializer. See [Context](#context) section for more detail.
 
 ---
 
-### Contexts
+### Context
 
-Contexts are context structure for using and interacting with the data of other atoms from a view or an another atom. The basic API common to all contexts is as follows:
+Context is a structure for using and interacting with atom values from views or other atoms.  
 
 |API|Use|
 |:--|:--|
@@ -921,7 +921,7 @@ Contexts are context structure for using and interacting with the data of other
 |[refresh(_:)](https://ra1028.github.io/swiftui-atom-properties/documentation/atoms/atomcontext/refresh(_:))|Reset an atom and await until asynchronous operation is complete.|
 |[reset(_:)](https://ra1028.github.io/swiftui-atom-properties/documentation/atoms/atomcontext/reset(_:))|Reset an atom to the default value or a first output.|
 
-There are the following types context as different contextual environments, and they have some specific APIs for each.
+There are the following types context as different contextual environments.
 
 #### [AtomViewContext](https://ra1028.github.io/swiftui-atom-properties/documentation/atoms/atomviewcontext)
 
@@ -992,24 +992,23 @@ struct BooksView: View {
 
 </details>
 
-Context available through the `@ViewContext` property wrapper when using atoms from a view. There is no specific API for this context.
+A context available through the `@ViewContext` property wrapper when using atoms from a view.
 
 #### [AtomTransactionContext](https://ra1028.github.io/swiftui-atom-properties/documentation/atoms/atomtransactioncontext)
 
 <details><summary><code>📖 Click to expand example code</code></summary>
 
 ```swift
-class LocationManagerDelegate: NSObject, CLLocationManagerDelegate { ... }
-
 struct LocationManagerAtom: ValueAtom, Hashable {
-    func value(context: Context) -> LocationManagerProtocol {
-        let manager = CLLocationManager()
-        let delegate = LocationManagerDelegate()
+    final class Coordinator: NSObject, CLLocationManagerDelegate { ... }
 
-        manager.delegate = delegate
-        context.addTermination(manager.stopUpdatingLocation)
-        context.keepUntilTermination(delegate)
+    func makeCoordinator() -> Coordinator {
+        Coordinator()
+    }
 
+    func value(context: Context) -> LocationManagerProtocol {
+        let manager = CLLocationManager()
+        manager.delegate = context.coordinator
         return manager
     }
 }
@@ -1024,12 +1023,12 @@ struct CoordinateAtom: ValueAtom, Hashable {
 
 </details>
 
-Context passed as a parameter to the primary function of each atom type.
+A context passed as a parameter to the primary function of each atom type.  
+This context type has a `coordinator` property that preserves an instance from the time an atom is used and initialized until it is unused and cleaned up, so it can be used to cache values or as a lifecycle for an atom.  
 
 |API|Use|
 |:--|:--|
-|[addTermination(_:)](https://ra1028.github.io/swiftui-atom-properties/documentation/atoms/atomtransactioncontext/addtermination(_:))|Calls the passed closure when the atom is updated or is no longer used.|
-|[keepUntilTermination(_:)](https://ra1028.github.io/swiftui-atom-properties/documentation/atoms/atomtransactioncontext/keepuntiltermination(_:))|Retains the given object instance until the atom is updated or is no longer used.|
+|[coordinator](https://ra1028.github.io/swiftui-atom-properties/documentation/atoms/atomtransactioncontext/coordinator)|The atom’s associated coordinator that preservess a state until the atom will no longer be used.|
 
 #### [AtomTestContext](https://ra1028.github.io/swiftui-atom-properties/documentation/atoms/atomtestcontext)
 
@@ -1074,7 +1073,7 @@ class FetchMusicsTests: XCTestCase {
 
 </details>
 
-Context that can simulate any scenarios in which atoms are used from a view or another atom and provides a comprehensive means of testing.
+A context that can simulate any scenarios in which atoms are used from a view or another atom and provides a comprehensive means of testing.
 
 |API|Use|
 |:--|:--|
@@ -1133,7 +1132,7 @@ In order to fully test your app, this library guarantees the following principle
 - Dependencies are replaceable with any of mock/stub/fake/spy per test case.
 - Test cases can reproduce any possible scenarios at the view-layer.
 
-In the test case, you first create an `AtomTestContext` instance that behaves similarly to other context types. The context allows for flexible reproduction of expected scenarios for testing using the control functions described in the [Contexts](#contexts) section.  
+In the test case, you first create an `AtomTestContext` instance that behaves similarly to other context types. The context allows for flexible reproduction of expected scenarios for testing using the control functions described in the [Context](#context) section.  
 In addition, it's able to replace the atom value with test-friendly dependencies with `override` function. It helps you to write a reproducible & stable testing.  
 Since atom needs to be used from the main actor to guarantee thread-safety, `XCTestCase` class that to test atoms should have `@MainActor` attribute.
 

Sources/Atoms/Atom/AsyncSequenceAtom.swift

@@ -44,7 +44,7 @@
 /// }
 /// ```
 ///
-public protocol AsyncSequenceAtom: Atom where Loader == AsyncSequenceAtomLoader<Sequence> {
+public protocol AsyncSequenceAtom: Atom {
     /// The type of asynchronous sequence that this atom manages.
     associatedtype Sequence: AsyncSequence
 
@@ -64,7 +64,7 @@ public protocol AsyncSequenceAtom: Atom where Loader == AsyncSequenceAtomLoader<
 
 public extension AsyncSequenceAtom {
     @MainActor
-    var _loader: Loader {
-        Loader(makeSequence: sequence)
+    var _loader: AsyncSequenceAtomLoader<Self> {
+        AsyncSequenceAtomLoader(atom: self)
     }
 }

Sources/Atoms/Atom/Atom.swift

@@ -10,11 +10,14 @@ public protocol Atom {
     associatedtype Key: Hashable
 
     /// A loader type that represents an actual implementation of the corresponding atom.
-    associatedtype Loader: AtomLoader
+    associatedtype Loader: AtomLoader where Loader.Coordinator == Coordinator
+
+    /// A type to coordinate with the atom.
+    associatedtype Coordinator = Void
 
     /// A type of the context structure that to read, watch, and otherwise interacting
     /// with other atoms.
-    typealias Context = AtomTransactionContext
+    typealias Context = AtomTransactionContext<Coordinator>
 
     /// A boolean value indicating whether the atom value should be preserved even if
     /// no longer watched to.
@@ -31,6 +34,17 @@ public protocol Atom {
     /// If this atom conforms to `Hashable`, it will adopt itself as the `key` by default.
     var key: Key { get }
 
+    /// Creates the custom coordinator instance that you use to preserve arbitrary state of
+    /// the atom.
+    ///
+    /// It's called when the atom is initialized, and the same instance is preserved until
+    /// the atom is no longer used and is deinitialized.
+    ///
+    /// - Returns: The atom's associated coordinator instance.
+    func makeCoordinator() -> Coordinator
+
+    // --- Internal ---
+
     /// A loader that represents an actual implementation of the corresponding atom.
     @MainActor
     var _loader: Loader { get }
@@ -40,8 +54,14 @@ public extension Atom {
     static var shouldKeepAlive: Bool {
         false
     }
+
+    func makeCoordinator() -> Coordinator where Coordinator == Void {
+        ()
+    }
 }
 
 public extension Atom where Self == Key {
-    var key: Self { self }
+    var key: Self {
+        self
+    }
 }

Sources/Atoms/Atom/ObservableObjectAtom.swift

@@ -48,7 +48,7 @@ import Combine
 /// }
 /// ```
 ///
-public protocol ObservableObjectAtom: Atom where Loader == ObservableObjectAtomLoader<ObjectType> {
+public protocol ObservableObjectAtom: Atom {
     /// The type of observable object that this atom produces.
     associatedtype ObjectType: ObservableObject
 
@@ -67,7 +67,7 @@ public protocol ObservableObjectAtom: Atom where Loader == ObservableObjectAtomL
 
 public extension ObservableObjectAtom {
     @MainActor
-    var _loader: Loader {
-        Loader(makeObject: object)
+    var _loader: ObservableObjectAtomLoader<Self> {
+        ObservableObjectAtomLoader(atom: self)
     }
 }

Sources/Atoms/Atom/PublisherAtom.swift

@@ -37,7 +37,7 @@ import Combine
 /// }
 /// ```
 ///
-public protocol PublisherAtom: Atom where Loader == PublisherAtomLoader<Publisher> {
+public protocol PublisherAtom: Atom {
     /// The type of publisher that this atom manages.
     associatedtype Publisher: Combine.Publisher
 
@@ -57,7 +57,7 @@ public protocol PublisherAtom: Atom where Loader == PublisherAtomLoader<Publishe
 
 public extension PublisherAtom {
     @MainActor
-    var _loader: Loader {
-        Loader(makePublisher: publisher)
+    var _loader: PublisherAtomLoader<Self> {
+        PublisherAtomLoader(atom: self)
     }
 }

Sources/Atoms/Atom/StateAtom.swift

@@ -36,7 +36,7 @@
 /// }
 /// ```
 ///
-public protocol StateAtom: Atom where Loader == ValueAtomLoader<Value> {
+public protocol StateAtom: Atom {
     /// The type of state value that this atom produces.
     associatedtype Value
 
@@ -61,7 +61,7 @@ public protocol StateAtom: Atom where Loader == ValueAtomLoader<Value> {
     ///   - context: A context structure that to read, watch, and otherwise
     ///              interacting with other atoms.
     @MainActor
-    func willSet(newValue: Value, oldValue: Value, context: Context)
+    func willSet(newValue: Loader.Value, oldValue: Loader.Value, context: Context)
 
     /// Observes and responds to changes in the state value which is called just after
     /// the state is changed.
@@ -72,18 +72,18 @@ public protocol StateAtom: Atom where Loader == ValueAtomLoader<Value> {
     ///   - context: A context structure that to read, watch, and otherwise
     ///              interacting with other atoms.
     @MainActor
-    func didSet(newValue: Value, oldValue: Value, context: Context)
+    func didSet(newValue: Loader.Value, oldValue: Loader.Value, context: Context)
 }
 
 public extension StateAtom {
     @MainActor
-    var _loader: Loader {
-        Loader(getValue: defaultValue)
+    var _loader: StateAtomLoader<Self> {
+        StateAtomLoader(atom: self)
     }
 
     @MainActor
-    func willSet(newValue: Value, oldValue: Value, context: Context) {}
+    func willSet(newValue: Loader.Value, oldValue: Loader.Value, context: Context) {}
 
     @MainActor
-    func didSet(newValue: Value, oldValue: Value, context: Context) {}
+    func didSet(newValue: Loader.Value, oldValue: Loader.Value, context: Context) {}
 }

Sources/Atoms/Atom/TaskAtom.swift

@@ -34,7 +34,7 @@
 /// }
 /// ```
 ///
-public protocol TaskAtom: Atom where Loader == TaskAtomLoader<Value> {
+public protocol TaskAtom: Atom {
     /// The type of value that this atom produces.
     associatedtype Value
 
@@ -53,7 +53,7 @@ public protocol TaskAtom: Atom where Loader == TaskAtomLoader<Value> {
 
 public extension TaskAtom {
     @MainActor
-    var _loader: Loader {
-        Loader(getValue: value)
+    var _loader: TaskAtomLoader<Self> {
+        TaskAtomLoader(atom: self)
     }
 }

Sources/Atoms/Atom/ThrowingTaskAtom.swift

@@ -36,7 +36,7 @@
 /// }
 /// ```
 ///
-public protocol ThrowingTaskAtom: Atom where Loader == ThrowingTaskAtomLoader<Value> {
+public protocol ThrowingTaskAtom: Atom {
     /// The type of value that this atom produces.
     associatedtype Value
 
@@ -57,7 +57,7 @@ public protocol ThrowingTaskAtom: Atom where Loader == ThrowingTaskAtomLoader<Va
 
 public extension ThrowingTaskAtom {
     @MainActor
-    var _loader: Loader {
-        Loader(getValue: value)
+    var _loader: ThrowingTaskAtomLoader<Self> {
+        ThrowingTaskAtomLoader(atom: self)
     }
 }

Sources/Atoms/Atom/ValueAtom.swift

@@ -29,7 +29,7 @@
 /// }
 /// ```
 ///
-public protocol ValueAtom: Atom where Loader == ValueAtomLoader<Value> {
+public protocol ValueAtom: Atom {
     /// The type of value that this atom produces.
     associatedtype Value
 
@@ -48,7 +48,7 @@ public protocol ValueAtom: Atom where Loader == ValueAtomLoader<Value> {
 
 public extension ValueAtom {
     @MainActor
-    var _loader: Loader {
-        Loader(getValue: value)
+    var _loader: ValueAtomLoader<Self> {
+        ValueAtomLoader(atom: self)
     }
 }