Rename select modifier to changes(of:) (#102)

* Rename select modifier to changes(of:)

* Add deprecated select modifier

Author: ra1028

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

@@ -58,6 +58,6 @@ struct CoordinateAtom: ValueAtom, Hashable {
 
 struct AuthorizationStatusAtom: ValueAtom, Hashable {
     func value(context: Context) -> CLAuthorizationStatus {
-        context.watch(LocationObserverAtom().select(\.manager.authorizationStatus))
+        context.watch(LocationObserverAtom().changes(of: \.manager.authorizationStatus))
     }
 }

README.md

@@ -634,13 +634,13 @@ struct ContactView: View {
 
 Modifiers can be applied to an atom to produce a different versions of the original atom to make it more coding friendly or to reduce view re-computation for performance optimization.
 
-#### [select](https://ra1028.github.io/swiftui-atom-properties/documentation/atoms/atom/select(_:))
+#### [changes(of:)](https://ra1028.github.io/swiftui-atom-properties/documentation/atoms/atom/changes(of:))
 
 |               |Description|
 |:--------------|:----------|
-|Summary        |Selects a partial property with the specified key path from the original atom. The selected property doesn't notify updates if the new value is equivalent to the old value.|
+|Summary        |Derives a partial property with the specified key path from the original atom and prevent it from updating its downstream when its new value is equivalent to old value.|
 |Output         |`T: Equatable`|
-|Compatible     |All atoms types. The selected property must be `Equatable` compliant.|
+|Compatible     |All atoms types. The derived property must be `Equatable` compliant.|
 |Use Case       |Performance optimization, Property scope restriction|
 
 <details><summary><code>📖 Expand to see example</code></summary>
@@ -653,7 +653,7 @@ struct CountAtom: StateAtom, Hashable {
 }
 
 struct CountDisplayView: View {
-    @Watch(CountAtom().select(\.description))
+    @Watch(CountAtom().changes(of: \.description))
     var description  // : String
 
     var body: some View {

Sources/Atoms/Atoms.docc/Atoms.md

@@ -27,8 +27,8 @@ Building state by compositing atoms automatically optimizes rendering based on i
 
 ### Modifiers
 
-- ``Atom/select(_:)``
 - ``Atom/changes``
+- ``Atom/changes(of:)``
 - ``Atom/phase``
 
 ### Attributes
@@ -70,8 +70,8 @@ Building state by compositing atoms automatically optimizes rendering based on i
 - ``Atom``
 - ``AtomStore``
 - ``AtomModifier``
-- ``SelectModifier``
 - ``ChangesModifier``
+- ``ChangesOfModifier``
 - ``TaskPhaseModifier``
 - ``AtomLoader``
 - ``RefreshableAtomLoader``

Sources/Atoms/Deprecated.swift

@@ -0,0 +1,8 @@
+public extension Atom {
+    @available(*, deprecated, renamed: "changes(of:)")
+    func select<Selected: Equatable>(
+        _ keyPath: KeyPath<Loader.Value, Selected>
+    ) -> ModifiedAtom<Self, ChangesOfModifier<Loader.Value, Selected>> {
+        changes(of: keyPath)
+    }
+}

Sources/Atoms/Modifier/ChangesModifier.swift

@@ -1,6 +1,5 @@
 public extension Atom where Loader.Value: Equatable {
-    /// Prevents the atom from updating its child views or atoms when its new value is the
-    /// same as its old value.
+    /// Prevents the atom from updating its downstream when its new value is equivalent to old value.
     ///
     /// ```swift
     /// struct FlagAtom: StateAtom, Hashable {

Sources/Atoms/Modifier/SelectModifier.swift renamed to Sources/Atoms/Modifier/ChangesOfModifier.swift

@@ -1,8 +1,6 @@
 public extension Atom {
-    /// Selects a partial property with the specified key path from the original atom.
-    ///
-    /// When this modifier is used, the atom provides the partial value which conforms to `Equatable`
-    /// and prevent the view from updating its child view if the new value is equivalent to old value.
+    /// Derives a partial property with the specified key path from the original atom and prevent it
+    /// from updating its downstream when its new value is equivalent to old value.
     ///
     /// ```swift
     /// struct IntAtom: ValueAtom, Hashable {
@@ -12,7 +10,7 @@ public extension Atom {
     /// }
     ///
     /// struct ExampleView: View {
-    ///     @Watch(IntAtom().select(\.description))
+    ///     @Watch(IntAtom().changes(of: \.description))
     ///     var description
     ///
     ///     var body: some View {
@@ -24,20 +22,20 @@ public extension Atom {
     /// - Parameter keyPath: A key path for the property of the original atom value.
     ///
     /// - Returns: An atom that provides the partial property of the original atom value.
-    func select<Selected: Equatable>(
-        _ keyPath: KeyPath<Loader.Value, Selected>
-    ) -> ModifiedAtom<Self, SelectModifier<Loader.Value, Selected>> {
-        modifier(SelectModifier(keyPath: keyPath))
+    func changes<T: Equatable>(
+        of keyPath: KeyPath<Loader.Value, T>
+    ) -> ModifiedAtom<Self, ChangesOfModifier<Loader.Value, T>> {
+        modifier(ChangesOfModifier(keyPath: keyPath))
     }
 }
 
-/// A modifier that selects the partial value of the specified key path
-/// from the original atom.
+/// A modifier that derives a partial property with the specified key path from the original atom
+/// and prevent it from updating its downstream when its new value is equivalent to old value.
 ///
-/// Use ``Atom/select(_:)`` instead of using this modifier directly.
-public struct SelectModifier<BaseValue, Selected: Equatable>: AtomModifier {
+/// Use ``Atom/changes(of:)`` instead of using this modifier directly.
+public struct ChangesOfModifier<BaseValue, T: Equatable>: AtomModifier {
     /// A type of modified value to provide.
-    public typealias Value = Selected
+    public typealias Value = T
 
     /// A type representing the stable identity of this modifier.
     public struct Key: Hashable {

Tests/AtomsTests/Atom/ModifiedAtomTests.swift

@@ -6,7 +6,7 @@ final class ModifiedAtomTests: XCTestCase {
     @MainActor
     func testKey() {
         let base = TestAtom(value: 0)
-        let modifier = SelectModifier<Int, String>(keyPath: \.description)
+        let modifier = ChangesOfModifier<Int, String>(keyPath: \.description)
         let atom = ModifiedAtom(atom: base, modifier: modifier)
 
         XCTAssertEqual(atom.key, atom.key)
@@ -20,7 +20,7 @@ final class ModifiedAtomTests: XCTestCase {
     @MainActor
     func testValue() async {
         let base = TestStateAtom(defaultValue: "test")
-        let modifier = SelectModifier<String, Int>(keyPath: \.count)
+        let modifier = ChangesOfModifier<String, Int>(keyPath: \.count)
         let atom = ModifiedAtom(atom: base, modifier: modifier)
         let context = AtomTestContext()
 

Tests/AtomsTests/Modifier/SelectModifierTests.swift renamed to Tests/AtomsTests/Modifier/ChangesOfModifierTests.swift

@@ -2,9 +2,9 @@ import XCTest
 
 @testable import Atoms
 
-final class SelectModifierTests: XCTestCase {
+final class ChangesOfModifierTests: XCTestCase {
     @MainActor
-    func testSelect() {
+    func testChangesOf() {
         let atom = TestStateAtom(defaultValue: "")
         let context = AtomTestContext()
         var updatedCount = 0
@@ -14,21 +14,21 @@ final class SelectModifierTests: XCTestCase {
         }
 
         XCTAssertEqual(updatedCount, 0)
-        XCTAssertEqual(context.watch(atom.select(\.count)), 0)
+        XCTAssertEqual(context.watch(atom.changes(of: \.count)), 0)
 
         context[atom] = "modified"
 
         XCTAssertEqual(updatedCount, 1)
-        XCTAssertEqual(context.watch(atom.select(\.count)), 8)
+        XCTAssertEqual(context.watch(atom.changes(of: \.count)), 8)
         context[atom] = "modified"
 
         // Should not be updated with an equivalent value.
         XCTAssertEqual(updatedCount, 1)
     }
 
     func testKey() {
-        let modifier0 = SelectModifier<Int, Int>(keyPath: \.byteSwapped)
-        let modifier1 = SelectModifier<Int, Int>(keyPath: \.leadingZeroBitCount)
+        let modifier0 = ChangesOfModifier<Int, Int>(keyPath: \.byteSwapped)
+        let modifier1 = ChangesOfModifier<Int, Int>(keyPath: \.leadingZeroBitCount)
 
         XCTAssertEqual(modifier0.key, modifier0.key)
         XCTAssertEqual(modifier0.key.hashValue, modifier0.key.hashValue)
@@ -38,7 +38,7 @@ final class SelectModifierTests: XCTestCase {
 
     @MainActor
     func testShouldUpdate() {
-        let modifier = SelectModifier<String, Int>(keyPath: \.count)
+        let modifier = ChangesOfModifier<String, Int>(keyPath: \.count)
 
         XCTAssertFalse(modifier.shouldUpdate(newValue: 100, oldValue: 100))
         XCTAssertTrue(modifier.shouldUpdate(newValue: 100, oldValue: 200))
@@ -47,7 +47,7 @@ final class SelectModifierTests: XCTestCase {
     @MainActor
     func testModify() {
         let atom = TestValueAtom(value: 0)
-        let modifier = SelectModifier<Int, String>(keyPath: \.description)
+        let modifier = ChangesOfModifier<Int, String>(keyPath: \.description)
         let transaction = Transaction(key: AtomKey(atom)) {}
         let context = AtomModifierContext<String>(transaction: transaction) { _ in }
         let value = modifier.modify(value: 100, context: context)
@@ -58,7 +58,7 @@ final class SelectModifierTests: XCTestCase {
     @MainActor
     func testAssociateOverridden() {
         let atom = TestValueAtom(value: 0)
-        let modifier = SelectModifier<Int, String>(keyPath: \.description)
+        let modifier = ChangesOfModifier<Int, String>(keyPath: \.description)
         let transaction = Transaction(key: AtomKey(atom)) {}
         let context = AtomModifierContext<String>(transaction: transaction) { _ in }
         let value = modifier.associateOverridden(value: "100", context: context)