feat(entity): Add support for enum (#51)

Author: pjechris

README.md

@@ -133,8 +133,8 @@ To store objects containing nested identity objects you need to make them confor
 struct AuthorBooks: Aggregate {
   var id: Author.ID { author.id }
 
-  let author: Author
-  let books: [Book]
+  var author: Author
+  var books: [Book]
 
   // `nestedEntitiesKeyPaths` must list all Identifiable/Aggregate this object contain
   var nestedEntitiesKeyPaths: [PartialIdentifiableKeyPath<Self>] {
@@ -193,6 +193,46 @@ Sometimes both can be used but they each have a different purpose:
 
 ## Advanced topics
 
+### Enum support
+
+Starting with 0.13 library has support for enum types. Note that you'll need to conform to `EntityEnumWrapper` and provide computed getter/setter for each entity you'd like to store.
+
+```swift
+enum MediaType: EntityEnumWrapper {
+  case book(Book)
+  case game(Game)
+  case tvShow(TvShow)
+
+  func wrappedEntitiesKeyPaths<Root>(relativeTo parent: WritableKeyPath<Root, Self>) -> [PartialIdentifiableKeyPath<Root>] {
+    [.init(parent.appending(\.book)), .init(parent.appending(\.game)), .init(parent.appending(\.tvShow))]
+  }
+
+  var book: Book? {
+    get { ... }
+    set { ... }
+  }
+
+  var game: Game? {
+    get { ... }
+    set { ... }
+  }
+
+  var tvShow: TvShow? {
+    get { ... }
+    set { ... }
+  }
+}
+
+struct AuthorMedia: Aggregate {
+  var author: Author
+  var media: MediaType
+
+  var nestedEntitiesKeyPaths: [PartialIdentifiableKeyPath<Self>] {
+    [.init(\.author), .init(wrapper: \.media)]
+  }
+}
+```
+
 ### Aliases
 
 Sometimes you need to retrieve data without knowing the object id. Common case is current user.
@@ -267,49 +307,6 @@ cancellable = nil
 identityMap.find(Book.self, id: "ACK") // return "A Clash of Kings" because cancellable2 still observe this book
 ```
 
-## Known limitations
-
-### Associated value enums require double update
-
-Let's say you have an enum with `Identifiable`/`Aggregate`:
-
-```swift
-enum MediaType: Identifiable {
-  case book(Book)
-  case game(Game)
-  case tvShow(TvShow)
-}
-
-struct AuthorMedia: Aggregate {
-  let author: Author
-  let media: [MediaType]
-}
-
-let lastOfUsPart1 = Game(id: xx, title: "The Last Of Us", supportedPlatforms: [.ps3, .ps4])
-
-let lastOfUs = TvShow(title: "The Last Of Us", releasedYear: 2023)
-
-let naughtyDog = Author(
-  author: .naughtyDog,
-  media: [.game(theLastOfUsPart1), .movie(theLastOfUst)]
-)
-
-identityMap.store(naughtyDog)
-```
-
-If associated value changes you might need to do a double update inside the lib in order to properly propagate the modifications:
-
-```swift
-
-let lastOfUsPart1 = Game(id: xx, title: "The Last Of Us", supportedPlatforms: [.ps3, .ps4, .ps5, .pc])
-
-identityMap.store(lastOfUsPart1) // this only notifies objects direct Game reference, not objects using MovieType.game (like our previous `naughtyDog`)
-identityMap.store(MovieType.game(lastOfUsPart1)) // on the other hand this one notifies objects like naughtyDog but not those using a plain Game
-```
-
-Note that in this context CohesionKit stores the value twice: once as `Game` and once as `MediaType.game` hence the double update.
-
-
 # License
 
 This project is released under the MIT License. Please see the LICENSE file for details.

Sources/CohesionKit/KeyPath/Aggregate.swift renamed to Sources/CohesionKit/Entity/Aggregate.swift

@@ -0,0 +1,21 @@
+/// a type wrapping one or more Identifiable types. As the name indicates you should use this type **only** on enums:
+/// this is the easiest way to extract types they are containing. If you facing a non enum case where you feel you need
+/// this type: rethink about it ;)
+public protocol EntityEnumWrapper {
+    /// Entities contained by all cases relative to the parent container
+    /// - Returns: entities contained in the enum
+    ////
+    /// Example:
+    //// ```swift
+    /// enum MyEnum: EntityEnumWrapper {
+    ///     case a(A)
+    ///     case b(B)
+    ///
+    ///    // you would also need to create computed getter/setter for a and b
+    ///    func wrappedEntitiesKeyPaths<Root>(relativeTo root: WritableKeyPath<Root, Self>) -> [PartialIdentifiableKeyPath<Root>] {
+    ///     [.init(root.appending(\.a)), .init(root.appending(\.b))]
+    ///    }
+    /// }
+    /// ```
+    func wrappedEntitiesKeyPaths<Root>(relativeTo parent: WritableKeyPath<Root, Self>) -> [PartialIdentifiableKeyPath<Root>]
+}

Sources/CohesionKit/Entity/EntityEnumWrapper.swift

@@ -67,4 +67,30 @@ public struct PartialIdentifiableKeyPath<Root> {
             )
         }
     }
+
+    public init<W: EntityEnumWrapper>(wrapper keyPath: WritableKeyPath<Root, W>) {
+        self.keyPath = keyPath
+        self.accept = { parent, root, stamp, visitor in
+            for wrappedKeyPath in root[keyPath: keyPath].wrappedEntitiesKeyPaths(relativeTo: keyPath) {
+                wrappedKeyPath.accept(parent, root, stamp, visitor)
+            }
+        }
+    }
+
+    public init<W: EntityEnumWrapper>(wrapper keyPath: WritableKeyPath<Root, W?>) {
+        self.keyPath = keyPath
+        self.accept = { parent, root, stamp, visitor in
+            if let wrapper = root[keyPath: keyPath] {
+                for wrappedKeyPath in wrapper.wrappedEntitiesKeyPaths(relativeTo: keyPath.unwrapped()) {
+                    wrappedKeyPath.accept(parent, root, stamp, visitor)
+                }
+            }
+        }
+    }
+}
+
+private extension WritableKeyPath {
+    func unwrapped<Wrapped>() -> WritableKeyPath<Root, Wrapped> where Value == Optional<Wrapped> {
+        self.appending(path: \.self!)
+    }
 }

Sources/CohesionKit/KeyPath/PartialIdentifiableKeyPath.swift

@@ -50,6 +50,31 @@ class IdentityMapTests: XCTestCase {
         XCTAssertEqual((node.value as! RootFixture).listNodes, nestedArray)
     }
 
+    func test_storeAggregate_nestedWrapperChanged_aggregateIsUpdated() {
+        let identityMap = IdentityMap()
+        let root = RootFixture(id: 1, primitive: "", singleNode: SingleNodeFixture(id: 1), optional: OptionalNodeFixture(id: 1), listNodes: [], enumWrapper: .single(SingleNodeFixture(id: 2)))
+        let updatedValue = SingleNodeFixture(id: 2, primitive: "updated")
+
+        withExtendedLifetime(identityMap.store(entity: root)) {
+            _ = identityMap.store(entity: updatedValue)
+            XCTAssertEqual(identityMap.find(RootFixture.self, id: 1)!.value.enumWrapper, .single(updatedValue))
+        }
+    }
+
+    func test_storeAggregate_nestedOptionalWrapperNullified_aggregateIsNullified() {
+        let identityMap = IdentityMap()
+        var root = RootFixture(id: 1, primitive: "", singleNode: SingleNodeFixture(id: 1), optional: OptionalNodeFixture(id: 1), listNodes: [], enumWrapper: .single(SingleNodeFixture(id: 2)))
+
+        withExtendedLifetime(identityMap.store(entity: root)) {
+            root.enumWrapper = nil
+
+            _ = identityMap.store(entity: root)
+            _ = identityMap.store(entity: SingleNodeFixture(id: 2, primitive: "deleted"))
+
+            XCTAssertNil(identityMap.find(RootFixture.self, id: 1)!.value.enumWrapper)
+        }
+    }
+
     func test_storeIdentifiable_entityIsInsertedForThe1stTime_loggerIsCalled() {
         let logger = LoggerMock()
         let identityMap = IdentityMap(logger: logger)

Tests/CohesionKitTests/IdentityMapTests.swift

@@ -11,34 +11,56 @@ class PartialIdentifiableKeyPathTests: XCTestCase {
 
     XCTAssertTrue(visitMock.visitAggregateCalled)
   }
+
+  func test_accept_wrapper_visitWrappedValues() {
+    let visitMock = VisitMock()
+    let partialIdentifiable = PartialIdentifiableKeyPath(wrapper: \RootFixture.enumWrapper)
+    let entity = RootFixture(
+      id: 1,
+      primitive: "",
+      singleNode: SingleNodeFixture(id: 1),
+      optional: nil,
+      listNodes: [],
+      enumWrapper: .single(SingleNodeFixture(id: 2))
+    )
+
+    visitMock.visitorCalledWith = { visitedEntity, keyPath in
+      XCTAssertEqual(visitedEntity as? SingleNodeFixture, entity.enumWrapper?.singleNode)
+      XCTAssertEqual(keyPath, \RootFixture.enumWrapper!.singleNode)
+    }
+
+    partialIdentifiable.accept(EntityNode(entity, modifiedAt: 0), entity, 0, visitMock)
+  }
 }
 
 private class VisitMock: NestedEntitiesVisitor {
     var visitAggregateCalled = false
+    var visitorCalledWith: ((Any?, AnyKeyPath) -> Void)?
     func visit<Root, T>(context: EntityContext<Root, T>, entity: T) where T : Aggregate {
         visitAggregateCalled = true
+        visitorCalledWith?(entity, context.keyPath)
     }
-    
+
     func visit<Root, T>(context: EntityContext<Root, T>, entity: T) where T : Identifiable {
-        
+      visitorCalledWith?(entity, context.keyPath)
     }
-    
+
     func visit<Root, T>(context: EntityContext<Root, T?>, entity: T?) where T : Identifiable {
-        
+      visitorCalledWith?(entity, context.keyPath)
     }
-    
+
     func visit<Root, T>(context: EntityContext<Root, T?>, entity: T?) where T : Aggregate {
-        
+      visitorCalledWith?(entity, context.keyPath)
     }
-    
+
     func visit<Root, C>(context: EntityContext<Root, C>, entities: C)
-    where C : Collection, C.Element : Aggregate, C.Index : Hashable {
-        
+    where C : MutableCollection, C.Element : Aggregate, C.Index : Hashable {
+      visitorCalledWith?(entities, context.keyPath)
     }
-    
+
     func visit<Root, C>(context: EntityContext<Root, C>, entities: C)
-    where C : Collection, C.Element : Identifiable, C.Index : Hashable {
-        
+    where C : MutableCollection, C.Element : Identifiable, C.Index : Hashable {
+      visitorCalledWith?(entities, context.keyPath)
     }
-    
+
 }

Tests/CohesionKitTests/KeyPath/PartialIdentifiableKeyPathTests.swift

@@ -7,12 +7,14 @@ struct RootFixture: Aggregate, Equatable {
     var singleNode: SingleNodeFixture
     var optional: OptionalNodeFixture?
     var listNodes: [ListNodeFixture]
-    
-    var nestedEntitiesKeyPaths: [PartialIdentifiableKeyPath<RootFixture>] {
+    var enumWrapper: EnumFixture?
+
+    var nestedEntitiesKeyPaths: [PartialIdentifiableKeyPath<Self>] {
         [
             .init(\.singleNode),
             .init(\.optional),
-            .init(\.listNodes)
+            .init(\.listNodes),
+            .init(wrapper: \.enumWrapper)
         ]
     }
 }
@@ -31,3 +33,27 @@ struct ListNodeFixture: Identifiable, Equatable {
     let id: Int
     var key = ""
 }
+
+ enum EnumFixture: Equatable, EntityEnumWrapper {
+    case single(SingleNodeFixture)
+
+    var singleNode: SingleNodeFixture? {
+        get {
+            switch self {
+                case .single(let value):
+                return value
+            }
+        }
+        set {
+            if let newValue {
+                self = .single(newValue)
+            }
+        }
+    }
+
+    func wrappedEntitiesKeyPaths<Root>(relativeTo parent: WritableKeyPath<Root, Self>) -> [PartialIdentifiableKeyPath<Root>] {
+        [
+            PartialIdentifiableKeyPath(parent.appending(path: \.singleNode))
+        ]
+    }
+}