Merge pull request #24 from shapehq/bugfix/initial-observed-value

Ensures observers receive correct initial value

Author: simonbs

README.md

@@ -225,6 +225,9 @@ class ContentViewController: UIViewController {
 }
 ```
 
+> [!IMPORTANT]
+> If an observation is setup before the corresponding property has been read or written, you must explicitly call `prepareIfNeeded()` on the spice store to avoid accessing an unprepared state. If the SpiceStore is not prepared, accessing a projected value will trigger an assertion failure.
+
 ## 🧪 Example Projects
 
 The example projects in the [Examples](/Examples) folder shows how Spices can be used to add an in-app debug menu to iOS apps with SwiftUI and UIKit lifecycles.

Sources/Spices/Internal/Storage/AnyStorage.swift

@@ -1,53 +1,33 @@
 import Combine
 
 final class AnyStorage<Value>: ObservableObject {
+    private(set) var isPrepared = false
     let publisher: AnyPublisher<Value, Never>
     var value: Value {
         get {
-            backingValue
+            read()
         }
         set {
+            objectWillChange.send()
             write(newValue)
-            backingValue = newValue
         }
     }
 
     private let read: () -> Value
     private let write: (Value) -> Void
     private let prepare: (String, any SpiceStore) -> Void
-    private var cancellables: Set<AnyCancellable> = []
-    @Published private var backingValue: Value
 
-    convenience init<S: Storage>(_ storage: S) where S.Value == Value {
-        self.init(storage: storage)
-        storage.publisher.sink { [weak self] newValue in
-            self?.backingValue = newValue
-        }
-        .store(in: &cancellables)
-    }
-
-    convenience init<S: Storage>(_ storage: S) where S.Value == Value, S.Value: Equatable {
-        self.init(storage: storage)
-        // Remove duplicates to reduce publishes from updating backing value,
-        // ultimately reducing number of view updates.
-        storage.publisher.removeDuplicates().sink { [weak self] newValue in
-            self?.backingValue = newValue
-        }
-        .store(in: &cancellables)
-    }
-
-    private init<S: Storage>(storage: S) where S.Value == Value {
-        publisher = storage.publisher
-        backingValue = storage.value
+    init<S: Storage>(_ storage: S) where S.Value == Value {
         read = { storage.value }
         write = { storage.value = $0 }
         prepare = { storage.prepare(propertyName: $0, ownedBy: $1) }
+        publisher = storage.publisher
     }
 }
 
 extension AnyStorage: Preparable {
     func prepare(propertyName: String, ownedBy spiceStore: any SpiceStore) {
         prepare(propertyName, spiceStore)
-        backingValue = read()
+        isPrepared = true
     }
 }

Sources/Spices/Internal/Storage/UserDefaultsStorage.swift

@@ -4,11 +4,15 @@ import Foundation
 final class UserDefaultsStorage<Value>: Storage {
     var value: Value {
         get {
-            internalValue
+            backingValue
         }
         set {
-            write?(newValue)
-            internalValue = newValue
+            if !isValuesEqual(newValue, backingValue) {
+                write?(newValue)
+                spiceStoreOrThrow.publishObjectWillChange()
+                backingValue = newValue
+                subject.send(newValue)
+            }
         }
     }
     var publisher: AnyPublisher<Value, Never> {
@@ -39,23 +43,15 @@ final class UserDefaultsStorage<Value>: Storage {
         }
         return spiceStore
     }
-    private var _internalValue: Value
-    private var internalValue: Value {
-        get {
-            _internalValue
-        }
-        set {
-            spiceStoreOrThrow.publishObjectWillChange()
-            _internalValue = newValue
-            subject.send(newValue)
-        }
-    }
+    private var backingValue: Value
+    private let isValuesEqual: (Value, Value) -> Bool
     private var cancellables: Set<AnyCancellable> = []
 
-    init(default value: Value, key: String?) {
-        _internalValue = value
+    init(default value: Value, key: String?) where Value: Equatable {
+        backingValue = value
         preferredKey = key
         subject = CurrentValueSubject(value)
+        isValuesEqual = { $0 == $1 }
         read = { [weak self] in
             guard let self else {
                 return value
@@ -70,10 +66,11 @@ final class UserDefaultsStorage<Value>: Storage {
         }
     }
 
-    init(default value: Value, key: String?) where Value: RawRepresentable {
-        _internalValue = value
+    init(default value: Value, key: String?) where Value: RawRepresentable, Value.RawValue: Equatable {
+        backingValue = value
         preferredKey = key
         subject = CurrentValueSubject(value)
+        isValuesEqual = { $0.rawValue == $1.rawValue }
         read = { [weak self] in
             guard let self, let rawValue = self.userDefaults.object(forKey: self.key) as? Value.RawValue else {
                 return value
@@ -98,7 +95,13 @@ private extension UserDefaultsStorage {
                 guard let self, let read = self.read else {
                     return
                 }
-                self.internalValue = read()
+                let value = read()
+                guard !self.isValuesEqual(value, backingValue) else {
+                    return
+                }
+                self.spiceStoreOrThrow.publishObjectWillChange()
+                self.backingValue = value
+                self.subject.send(value)
             }
             .store(in: &cancellables)
     }
@@ -109,7 +112,11 @@ extension UserDefaultsStorage: Preparable {
         self.propertyName = propertyName
         self.spiceStore = spiceStore
         if let read {
-            _internalValue = read()
+            let value = read()
+            if !isValuesEqual(value, backingValue) {
+                backingValue = value
+                subject.send(value)
+            }
         }
         observeUserDefaults()
     }

Sources/Spices/Spice.swift

@@ -1,3 +1,4 @@
+// swiftlint:disable file_length
 import Combine
 import Foundation
 import SwiftUI
@@ -74,7 +75,9 @@ import SwiftUI
     /// }
     /// ```
     public var projectedValue: AnyPublisher<Value, Never> {
-        storage.publisher
+        // swiftlint:disable:next line_length
+        assert(storage.isPrepared, "The projected value of a Spice cannot be accessed until its owning spice store has been prepared. This happens automatically unless the projected value is accessed before the property has been read or written, in which case you must manually call prepareIfNeeded() on the spice store.")
+        return storage.publisher
     }
 
     let name: Name
@@ -158,7 +161,7 @@ import SwiftUI
         key: String? = nil,
         name: String? = nil,
         requiresRestart: Bool = false
-    ) where Value: RawRepresentable & CaseIterable {
+    ) where Value: RawRepresentable & CaseIterable, Value.RawValue: Equatable {
         self.name = Name(name)
         self.storage = AnyStorage(UserDefaultsStorage(default: wrappedValue, key: key))
         self.menuItem = PickerMenuItem(
@@ -481,3 +484,4 @@ private extension Spice {
 }
 
 extension Spice: MenuItemProvider {}
+// swiftlint:enable file_length

Sources/Spices/SpiceStore.swift

@@ -41,6 +41,27 @@ public extension SpiceStore {
     }
 }
 
+public extension SpiceStore {
+    /// Ensures that the `SpiceStore` is prepared before accessing its projected values.
+    ///
+    /// This method checks whether the `SpiceStore` has already been prepared. If not, it marks it as prepared
+    /// and invokes the `prepare()` method.
+    ///
+    /// You typically do not need to call this method manually, as preparation happens automatically. However,
+    /// if ``Spice/projectedValue`` is accessed before the corresponding property has been read or written,
+    /// you must explicitly call `prepareIfNeeded()` to avoid accessing an unprepared state.
+    ///
+    /// - Important: If the `SpiceStore` is not prepared, accessing a projected value will trigger an assertion failure.
+    ///
+    func prepareIfNeeded() {
+        guard !isPrepared else {
+            return
+        }
+        isPrepared = true
+        prepare()
+    }
+}
+
 extension SpiceStore {
     var id: String {
         if let value = objc_getAssociatedObject(self, &idKey) as? String {
@@ -108,14 +129,6 @@ extension SpiceStore {
         parent?.publishObjectWillChange()
     }
 
-    func prepareIfNeeded() {
-        guard !isPrepared else {
-            return
-        }
-        isPrepared = true
-        prepare()
-    }
-
     private func prepare() {
         let mirror = Mirror(reflecting: self)
         for (name, value) in mirror.children {

Sources/Spices/Spices.docc/Extensions/SpiceStore.md

@@ -0,0 +1,11 @@
+# ``SpiceStore``
+
+## Topics
+
+### Storage
+
+- ``SpiceStore/userDefaults``
+
+### Preparation
+
+- ``SpiceStore/prepareIfNeeded()``

Tests/SpicesTests/AnyStorageTests.swift

@@ -0,0 +1,46 @@
+import Combine
+import Foundation
+@testable import Spices
+import Testing
+
+@Suite
+final class AnyStorageTests {
+    private var cancellables: Set<AnyCancellable> = []
+
+    @Test
+    func it_reads_value() async throws {
+        let storage = MockStorage(default: "Hello world!")
+        let sut = AnyStorage(storage)
+        #expect(sut.value == "Hello world!")
+    }
+
+    @Test
+    func it_writes_value() async throws {
+        let storage = MockStorage(default: "Hello world!")
+        let sut = AnyStorage(storage)
+        sut.value = "Foo"
+        #expect(storage.value == "Foo")
+    }
+
+    @Test
+    func it_notifies_observer_of_changes() async throws {
+        let storage = MockStorage(default: "Hello world!")
+        let sut = AnyStorage(storage)
+        var didReceiveChange = false
+        sut.objectWillChange.sink {
+            didReceiveChange = true
+        }
+        .store(in: &cancellables)
+        sut.value = "Foo"
+        #expect(didReceiveChange == true)
+    }
+
+    @Test
+    func it_updates_prepared_state() async throws {
+        let storage = MockStorage(default: "Hello world!")
+        let sut = AnyStorage(storage)
+        #expect(sut.isPrepared == false)
+        sut.prepare(propertyName: "foo", ownedBy: MockSpiceStore())
+        #expect(sut.isPrepared == true)
+    }
+}

Tests/SpicesTests/CamelCaseToNaturalTextTests.swift

@@ -1,7 +1,6 @@
 import Foundation
-import Testing
-
 @testable import Spices
+import Testing
 
 @Suite
 struct CamelCaseToNaturalTextTests {

Tests/SpicesTests/Mocks/MockStorage.swift

@@ -0,0 +1,24 @@
+import Combine
+@testable import Spices
+
+final class MockStorage<Value>: Storage, Preparable {
+    var publisher: AnyPublisher<Value, Never> {
+        subject.eraseToAnyPublisher()
+    }
+    var value: Value {
+        get {
+            subject.value
+        }
+        set {
+            subject.send(newValue)
+        }
+    }
+
+    private let subject: CurrentValueSubject<Value, Never>
+
+    init(default value: Value) {
+        subject = CurrentValueSubject(value)
+    }
+
+    func prepare(propertyName: String, ownedBy spiceStore: any SpiceStore) {}
+}

Tests/SpicesTests/SpiceTests.swift

@@ -3,7 +3,7 @@ import Foundation
 @testable import Spices
 import Testing
 
-@MainActor @Suite
+@MainActor @Suite(.serialized)
 final class SpiceTests {
     private var cancellables: Set<AnyCancellable> = []
 
@@ -63,17 +63,32 @@ final class SpiceTests {
         var initialValue: MockEnvironment?
         let sut = MockSpiceStore()
         sut.userDefaults.removeAll()
+        sut.prepareIfNeeded()
         sut.$enumValue.sink { newValue in
             initialValue = newValue
         }
         .store(in: &cancellables)
         #expect(initialValue == .production)
     }
 
+    @Test func it_sink_receives_initial_value_if_it_has_been_changed() async throws {
+        var initialValue: MockEnvironment?
+        let sut = MockSpiceStore()
+        sut.userDefaults.removeAll()
+        sut.userDefaults.set(MockEnvironment.staging.rawValue, forKey: "enumValue")
+        sut.prepareIfNeeded()
+        sut.$enumValue.sink { newValue in
+            initialValue = newValue
+        }
+        .store(in: &cancellables)
+        #expect(initialValue == .staging)
+    }
+
     @Test func it_publishes_values() async throws {
         var publishedValue: MockEnvironment?
         let sut = MockSpiceStore()
         sut.userDefaults.removeAll()
+        sut.prepareIfNeeded()
         sut.$enumValue.sink { newValue in
             publishedValue = newValue
         }