Scoped Observe (#109)

Examples/Packages/iOS/Sources/ExampleTimeTravel/ExampleTimeTravel.swift

@@ -89,7 +89,7 @@ struct TimeTravelDebug<Content: View>: View {
             }
             .padding()
         }
-        .observe { snapshot in
+        .scopedObserve { snapshot in
             Task {
                 snapshots = Array(snapshots.prefix(position + 1))
                 snapshots.append(snapshot)

README.md

@@ -1214,7 +1214,7 @@ See the [Override Atoms](#override-atoms) and [Debugging](#debugging) sections f
 AtomScope {
     CounterView()
 }
-.observe { snapshot in
+.scopedObserve { snapshot in
     if let count = snapshot.lookup(CounterAtom()) {
         print(count)
     }
@@ -1443,8 +1443,8 @@ var debugButton: some View {
 }
 ```
 
-Or, you can observe all updates of atoms and always continue to receive `Snapshots` at that point in time through `observe(_:)` modifier of [AtomRoot](#atomroot) or [AtomScope](#atomscope).  
-Note that observing in `AtomRoot` will receive all atom updates that happened in the whole app, but observing in `AtomScope` will only receive atoms used in the descendant views.  
+Or, you can observe all state changes and always continue to receive `Snapshots` at that point in time with `observe(_:)` modifier of [AtomRoot](#atomroot) or with `scopedObserve(_:)` modifier of [AtomScope](#atomscope).  
+Note that observing in `AtomRoot` will receive every state changes that happened in the whole app, but observing in `AtomScope` will observe changes of atoms used in the scope.  
 
 ```swift
 AtomRoot {

Sources/Atoms/AtomRoot.swift

@@ -108,9 +108,8 @@ public struct AtomRoot<Content: View>: View {
         }
     }
 
-    /// For debugging purposes, each time there is a change in the internal state,
-    /// a snapshot is taken that captures the state of the atoms and their dependency graph
-    /// at that point in time.
+    /// Observes the state changes with a snapshot that captures the whole atom states and
+    /// their dependency graph at the point in time for debugging purposes.
     ///
     /// - Parameter onUpdate: A closure to handle a snapshot of recent updates.
     ///
@@ -178,6 +177,7 @@ private extension AtomRoot {
                     scopeKey: ScopeKey(token: state.token),
                     inheritedScopeKeys: [:],
                     observers: observers,
+                    scopedObservers: [],
                     overrides: overrides
                 )
             )
@@ -206,6 +206,7 @@ private extension AtomRoot {
                     scopeKey: ScopeKey(token: state.token),
                     inheritedScopeKeys: [:],
                     observers: observers,
+                    scopedObservers: [],
                     overrides: overrides
                 )
             )

Sources/Atoms/AtomScope.swift

@@ -2,13 +2,13 @@ import SwiftUI
 
 /// A view to override or monitor atoms in scope.
 ///
-/// This view allows you to monitor changes of atoms used in descendant views by``AtomScope/observe(_:)``.
+/// This view allows you to monitor changes of atoms used in descendant views by``AtomScope/scopedObserve(_:)``.
 ///
 /// ```swift
 /// AtomScope {
 ///     CounterView()
 /// }
-/// .observe { snapshot in
+/// .scopedObserve { snapshot in
 ///     if let count = snapshot.lookup(CounterAtom()) {
 ///         print(count)
 ///     }
@@ -87,17 +87,16 @@ public struct AtomScope<Content: View>: View {
         }
     }
 
-    /// For debugging purposes, each time there is a change in the internal state,
-    /// a snapshot is taken that captures the state of the atoms and their dependency graph
-    /// at that point in time.
+    /// Observes the state changes with a snapshot that captures the whole atom states and
+    /// their dependency graph at the point in time for debugging purposes.
     ///
-    /// Note that unlike observed by ``AtomRoot``, this is triggered only by internal state changes
-    /// caused by atoms use in this scope.
+    /// Note that unlike ``AtomRoot/observe(_:)``, this observes only the state changes caused by atoms
+    /// used in this scope.
     ///
     /// - Parameter onUpdate: A closure to handle a snapshot of recent updates.
     ///
     /// - Returns: The self instance.
-    public func observe(_ onUpdate: @escaping @MainActor (Snapshot) -> Void) -> Self {
+    public func scopedObserve(_ onUpdate: @escaping @MainActor (Snapshot) -> Void) -> Self {
         mutating(self) { $0.observers.append(Observer(onUpdate: onUpdate)) }
     }
 
@@ -181,7 +180,7 @@ private extension AtomScope {
             content.environment(
                 \.store,
                 context._store.inherited(
-                    observers: observers,
+                    scopedObservers: observers,
                     overrides: overrides
                 )
             )

Sources/Atoms/Context/AtomTestContext.swift

@@ -5,8 +5,7 @@ import Foundation
 ///
 /// This context has a store that manages the state of atoms, so it can be used to test individual
 /// atoms or their interactions with other atoms without depending on the SwiftUI view tree.
-/// Furthermore, unlike other contexts, it is possible to override or observe changes in atoms
-/// through this context.
+/// Furthermore, unlike other contexts, it is possible to override atoms through this context.
 @MainActor
 public struct AtomTestContext: AtomWatchableContext {
     private let location: SourceLocation
@@ -444,6 +443,7 @@ internal extension AtomTestContext {
             scopeKey: ScopeKey(token: _state.token),
             inheritedScopeKeys: [:],
             observers: [],
+            scopedObservers: [],
             overrides: _state.overrides
         )
     }

Sources/Atoms/Core/Environment.swift

@@ -14,6 +14,7 @@ private struct StoreEnvironmentKey: EnvironmentKey {
             scopeKey: ScopeKey(token: ScopeKey.Token()),
             inheritedScopeKeys: [:],
             observers: [],
+            scopedObservers: [],
             overrides: [:],
             enablesAssertion: true
         )

Sources/Atoms/Core/StoreContext.swift

@@ -7,6 +7,7 @@ internal struct StoreContext {
     private let scopeKey: ScopeKey
     private let inheritedScopeKeys: [ScopeID: ScopeKey]
     private let observers: [Observer]
+    private let scopedObservers: [Observer]
     private let overrides: [OverrideKey: any AtomOverrideProtocol]
     private let enablesAssertion: Bool
 
@@ -15,26 +16,29 @@ internal struct StoreContext {
         scopeKey: ScopeKey,
         inheritedScopeKeys: [ScopeID: ScopeKey],
         observers: [Observer],
+        scopedObservers: [Observer],
         overrides: [OverrideKey: any AtomOverrideProtocol],
         enablesAssertion: Bool = false
     ) {
         self.weakStore = store
         self.scopeKey = scopeKey
         self.inheritedScopeKeys = inheritedScopeKeys
         self.observers = observers
+        self.scopedObservers = scopedObservers
         self.overrides = overrides
         self.enablesAssertion = enablesAssertion
     }
 
     func inherited(
-        observers: [Observer],
+        scopedObservers: [Observer],
         overrides: [OverrideKey: any AtomOverrideProtocol]
     ) -> StoreContext {
         StoreContext(
             weakStore,
             scopeKey: scopeKey,
             inheritedScopeKeys: inheritedScopeKeys,
-            observers: self.observers + observers,
+            observers: observers,
+            scopedObservers: self.scopedObservers + scopedObservers,
             overrides: self.overrides.merging(overrides) { $1 },
             enablesAssertion: enablesAssertion
         )
@@ -50,7 +54,8 @@ internal struct StoreContext {
             weakStore,
             scopeKey: scopeKey,
             inheritedScopeKeys: mutating(inheritedScopeKeys) { $0[scopeID] = scopeKey },
-            observers: self.observers + observers,
+            observers: self.observers,
+            scopedObservers: observers,
             overrides: overrides,
             enablesAssertion: enablesAssertion
         )
@@ -612,13 +617,13 @@ private extension StoreContext {
     }
 
     func notifyUpdateToObservers() {
-        guard !observers.isEmpty else {
+        guard !observers.isEmpty || !scopedObservers.isEmpty else {
             return
         }
 
         let snapshot = snapshot()
 
-        for observer in observers {
+        for observer in observers + scopedObservers {
             observer.onUpdate(snapshot)
         }
     }

Sources/Atoms/Deprecated.swift

@@ -27,4 +27,9 @@ public extension AtomScope {
             AtomRoot(storesIn: store, content: content)
         }
     }
+
+    @available(*, deprecated, renamed: "scopedObserve(_:)")
+    func observe(_ onUpdate: @escaping @MainActor (Snapshot) -> Void) -> Self {
+        scopedObserve(onUpdate)
+    }
 }

Tests/AtomsTests/Core/StoreContextTests.swift

@@ -16,6 +16,7 @@ final class StoreContextTests: XCTestCase {
             scopeKey: scopeKey,
             inheritedScopeKeys: [:],
             observers: [],
+            scopedObservers: [],
             overrides: [
                 OverrideKey(atom): AtomOverride<TestAtom<Int>> { _ in
                     10

Tests/AtomsTests/Utilities/Util.swift

@@ -68,6 +68,7 @@ extension StoreContext {
             scopeKey: ScopeKey(token: ScopeKey.Token()),
             inheritedScopeKeys: [:],
             observers: observers,
+            scopedObservers: [],
             overrides: overrides
         )
     }