Atom Effects (#131)

* Implement AtomEffect

* Update tests

* Documentation

* Update README

* Update documentation

Author: ra1028

Examples/Packages/iOS/Sources/ExampleVoiceMemo/Atoms/VoiceMemoListAtoms.swift

@@ -120,32 +120,8 @@ struct RecordingDataAtom: StateAtom, Hashable {
         return nil
     }
 
-    func updated(newValue: RecordingData?, oldValue: RecordingData?, context: UpdatedContext) {
-        let audioRecorder = context.read(AudioRecorderAtom())
-        let audioSession = context.read(AudioSessionAtom())
-
-        if let data = oldValue {
-            let voiceMemo = VoiceMemo(
-                url: data.url,
-                date: data.date,
-                duration: audioRecorder.currentTime
-            )
-
-            context[VoiceMemosAtom()].insert(voiceMemo, at: 0)
-            audioRecorder.stop()
-            try? audioSession.setActive(false, options: [])
-        }
-
-        if let data = newValue {
-            do {
-                try audioSession.setCategory(.playAndRecord, mode: .default, options: .defaultToSpeaker)
-                try audioSession.setActive(true, options: [])
-                try audioRecorder.record(url: data.url)
-            }
-            catch {
-                context[IsRecordingFailedAtom()] = true
-            }
-        }
+    func effect(context: CurrentContext) -> some AtomEffect {
+        RecordingEffect()
     }
 }
 

Examples/Packages/iOS/Sources/ExampleVoiceMemo/Atoms/VoiceMemoRowAtoms.swift

@@ -17,18 +17,21 @@ struct IsPlayingAtom: StateAtom {
         return false
     }
 
-    func updated(newValue: Bool, oldValue: Bool, context: UpdatedContext) {
-        let audioPlayer = context.read(AudioPlayerAtom(voiceMemo: voiceMemo))
+    func effect(context: CurrentContext) -> some AtomEffect {
+        UpdateEffect {
+            let audioPlayer = context.read(AudioPlayerAtom(voiceMemo: voiceMemo))
+            let isPlaying = context.read(self)
 
-        guard newValue else {
-            return audioPlayer.stop()
-        }
+            guard isPlaying else {
+                return audioPlayer.stop()
+            }
 
-        do {
-            try audioPlayer.play(url: voiceMemo.url)
-        }
-        catch {
-            context[IsPlaybackFailedAtom()] = true
+            do {
+                try audioPlayer.play(url: voiceMemo.url)
+            }
+            catch {
+                context[IsPlaybackFailedAtom()] = true
+            }
         }
     }
 }

Examples/Packages/iOS/Sources/ExampleVoiceMemo/Effects/RecordingEffect.swift

@@ -0,0 +1,37 @@
+import AVFoundation
+import Atoms
+
+final class RecordingEffect: AtomEffect {
+    private var currentData: RecordingData?
+
+    func updated(context: Context) {
+        let audioSession = context.read(AudioSessionAtom())
+        let audioRecorder = context.read(AudioRecorderAtom())
+        let data = context.read(RecordingDataAtom())
+
+        if let currentData {
+            let voiceMemo = VoiceMemo(
+                url: currentData.url,
+                date: currentData.date,
+                duration: audioRecorder.currentTime
+            )
+
+            context[VoiceMemosAtom()].insert(voiceMemo, at: 0)
+            audioRecorder.stop()
+            try? audioSession.setActive(false, options: [])
+        }
+
+        currentData = data
+
+        if let data {
+            do {
+                try audioSession.setCategory(.playAndRecord, mode: .default, options: .defaultToSpeaker)
+                try audioSession.setActive(true, options: [])
+                try audioRecorder.record(url: data.url)
+            }
+            catch {
+                context[IsRecordingFailedAtom()] = true
+            }
+        }
+    }
+}

README.md

@@ -811,9 +811,11 @@ struct FetchMoviesPhaseAtom: ValueAtom, Refreshable, Hashable {
         await context.refresh(FetchMoviesTaskAtom().phase)
     }
 
-    func updated(newValue: AsyncPhase<[Movies], Error>, oldValue: AsyncPhase<[Movies], Error>, context: UpdatedContext) {
-        if case .failure = newValue {
-            print("Failed to fetch movies.")
+    func effect(context: CurrentContext) -> some AtomEffect {
+        UpdateEffect {
+            if case .failure = context.read(self) {
+                print("Failed to fetch movies.")
+            }
         }
     }
 }
@@ -1305,6 +1307,69 @@ AtomScope(id: TextScopeID()) {
 This is also useful when multiple identical screens are stacked and each screen needs isolated states such as user inputs.  
 Note that other atoms that depend on scoped atoms will be in a shared state and must be given `Scoped` attribute as well in order to scope them as well.  
 
+#### Atom Effects
+
+Atom effects are an API for managing side effects that are synchronized with the atom's lifecycle. They are widely applicable for variety of usage such as state synchronization, state persistence, logging, and etc, by observing and reacting to state changes.  
+
+You can create custom effects that conform to the [`AtomEffect`](https://ra1028.github.io/swiftui-atom-properties/documentation/atoms/atomeffect) protocol, but there are several predefined effects.  
+
+|API|Use|
+|:--|:--|
+|[InitializeEffect](https://ra1028.github.io/swiftui-atom-properties/documentation/atoms/initializeeffect)|Performs an arbitrary action when the atom is initialized.|
+|[UpdateEffect](https://ra1028.github.io/swiftui-atom-properties/documentation/atoms/updateeffect)|Performs an arbitrary action when the atom is updated.|
+|[ReleaseEffect](https://ra1028.github.io/swiftui-atom-properties/documentation/atoms/releaseeffect)|Performs an arbitrary action when the atom is released.|
+|[MergedEffect](https://ra1028.github.io/swiftui-atom-properties/documentation/atoms/mergedeffect)|Merges multiple atom effects into one.|
+
+Atom effects are attached to atoms via the [`Atom.effect(context:)`](https://ra1028.github.io/swiftui-atom-properties/documentation/atoms/atom/effect(context:)-2kcbd) function.  
+
+```swift
+struct CounterAtom: StateAtom, Hashable {
+    func defaultValue(context: Context) -> Int {
+        UserDefaults.standard.integer(forKey: "persistence_key")
+    }
+
+    func effect(context: CurrentContext) -> some AtomEffect {
+        UpdateEffect {
+            UserDefaults.standard.set(context.read(self), forKey: "persistence_key")
+        }
+    }
+}
+```
+
+Each atom initializes its effect when the atom is initialized, and the effect is retained until the atom is no longer used from anywhere and is released, thus it allows to declare stateful side effects.  
+
+```swift
+struct CounterAtom: StateAtom, Hashable {
+    func defaultValue(context: Context) -> Int {
+        0
+    }
+
+    func effect(context: CurrentContext) -> some AtomEffect {
+        CountTimerEffect()
+    }
+}
+
+
+final class CountTimerEffect: AtomEffect {
+    private var timer: Timer?
+
+    func initialized(context: Context) {
+        timer = Timer.scheduledTimer(withTimeInterval: 1, repeats: true) { _ in
+            context[CounterAtom()] += 1
+        }
+    }
+
+    func updated(context: Context) {
+        print("Count: \(context.read(CounterAtom()))")
+    }
+
+    func released(context: Context) {
+        timer?.invalidate()
+        timer = nil
+    }
+}
+```
+
 #### Override Atoms
 
 You can override atoms in [AtomRoot](#atomroot) or [AtomScope](#atomscope) to overwirete the atom states for dependency injection or faking state in particular view, which is useful especially for testing.  
@@ -1658,29 +1723,6 @@ class MessageLoader: ObservableObject {
 
 </details>
 
-#### Side effects
-
-All atom types can optionally implement [`updated(newValue:oldValue:context:)`](https://ra1028.github.io/swiftui-atom-properties/documentation/atoms/atom/updated(newvalue:oldvalue:context:)-98n6k) method to manage arbitrary side-effects of value updates, such as state persistence, state synchronization, logging, and etc.  
-In the above example, the initial state of the atom is retrieved from UserDefaults, and when the user updates the state, the value is reflected into UserDefaults as a side effect.
-
-<details><summary><code>📖 Example</code></summary>
-
-```swift
-struct PersistentCounterAtom: StateAtom, Hashable {
-    func defaultValue(context: Context) -> Int {
-        UserDefaults.standard.integer(forKey: "persistence_key")
-    }
-
-    func updated(newValue: Int, oldValue: Int, context: UpdatedContext) {
-        if newValue != oldValue {
-            UserDefaults.standard.set(newValue, forKey: "persistence_key")
-        }
-    }
-}
-```
-
-</details>
-
 ---
 
 ### Dealing with Known SwiftUI Bugs

Sources/Atoms/Atoms.docc/Atoms.md

@@ -33,6 +33,14 @@ Building state by compositing atoms automatically optimizes rendering based on i
 - ``TaskAtom/phase``
 - ``ThrowingTaskAtom/phase``
 
+### Effects
+
+- ``AtomEffect``
+- ``InitializeEffect``
+- ``UpdateEffect``
+- ``ReleaseEffect``
+- ``MergedEffect``
+
 ### Attributes
 
 - ``Scoped``
@@ -67,6 +75,7 @@ Building state by compositing atoms automatically optimizes rendering based on i
 - ``AtomViewContext``
 - ``AtomTestContext``
 - ``AtomCurrentContext``
+- ``AtomEffectContext``
 
 ### Misc
 
@@ -80,5 +89,6 @@ Building state by compositing atoms automatically optimizes rendering based on i
 - ``ChangesOfModifier``
 - ``TaskPhaseModifier``
 - ``AnimationModifier``
+- ``EmptyEffect``
 - ``AtomProducer``
 - ``AtomRefreshProducer``