added mechanism to track transaction sources

Sources/ListObserver.swift

@@ -51,15 +51,54 @@ public protocol ListObserver: AnyObject {
      The default implementation does nothing.
      
      - parameter monitor: the `ListMonitor` monitoring the list being observed
+     - parameter sourceIdentifier: an optional identifier provided by the transaction source
      */
-    func listMonitorWillChange(_ monitor: ListMonitor<ListEntityType>)
+    func listMonitorWillChange(
+        _ monitor: ListMonitor<ListEntityType>,
+        sourceIdentifier: Any?
+    )
+    
+    /**
+     Handles processing just before a change to the observed list occurs. (Optional)
+     The default implementation does nothing.
+     
+     - parameter monitor: the `ListMonitor` monitoring the list being observed
+     */
+    func listMonitorWillChange(
+        _ monitor: ListMonitor<ListEntityType>
+    )
+    
+    /**
+     Handles processing right after a change to the observed list occurs. (Required)
+     
+     - parameter monitor: the `ListMonitor` monitoring the object being observed
+     - parameter sourceIdentifier: an optional identifier provided by the transaction source
+     */
+    func listMonitorDidChange(
+        _ monitor: ListMonitor<ListEntityType>,
+        sourceIdentifier: Any?
+    )
     
     /**
      Handles processing right after a change to the observed list occurs. (Required)
      
      - parameter monitor: the `ListMonitor` monitoring the object being observed
      */
-    func listMonitorDidChange(_ monitor: ListMonitor<ListEntityType>)
+    func listMonitorDidChange(
+        _ monitor: ListMonitor<ListEntityType>
+    )
+    
+    /**
+     This method is broadcast from within the `ListMonitor`'s `refetch(...)` method to let observers prepare for the internal `NSFetchedResultsController`'s pending change to its predicate, sort descriptors, etc. (Optional)
+     
+     - Important: All `ListMonitor` access between `listMonitorWillRefetch(_:)` and `listMonitorDidRefetch(_:)` will raise and assertion. The actual refetch will happen after the `NSFetchedResultsController`'s last `controllerDidChangeContent(_:)` notification completes.
+     - parameter monitor: the `ListMonitor` monitoring the object being observed
+     - parameter sourceIdentifier: an optional identifier provided by the transaction source
+     */
+    func listMonitorWillRefetch(
+        _ monitor: ListMonitor<ListEntityType>,
+        sourceIdentifier: Any?
+    )
     
     /**
      This method is broadcast from within the `ListMonitor`'s `refetch(...)` method to let observers prepare for the internal `NSFetchedResultsController`'s pending change to its predicate, sort descriptors, etc. (Optional)
@@ -67,7 +106,21 @@ public protocol ListObserver: AnyObject {
      - Important: All `ListMonitor` access between `listMonitorWillRefetch(_:)` and `listMonitorDidRefetch(_:)` will raise and assertion. The actual refetch will happen after the `NSFetchedResultsController`'s last `controllerDidChangeContent(_:)` notification completes.
      - parameter monitor: the `ListMonitor` monitoring the object being observed
      */
-    func listMonitorWillRefetch(_ monitor: ListMonitor<ListEntityType>)
+    func listMonitorWillRefetch(
+        _ monitor: ListMonitor<ListEntityType>
+    )
+    
+    /**
+     After the `ListMonitor`'s `refetch(...)` method is called, this method is broadcast after the `NSFetchedResultsController`'s last `controllerDidChangeContent(_:)` notification completes. (Required)
+     
+     - Important: When `listMonitorDidRefetch(_:)` is called it should be assumed that all `ListMonitor`'s previous data have been reset, including counts, objects, and persistent stores.
+     - parameter monitor: the `ListMonitor` monitoring the object being observed
+     - parameter sourceIdentifier: an optional identifier provided by the transaction source
+     */
+    func listMonitorDidRefetch(
+        _ monitor: ListMonitor<ListEntityType>,
+        sourceIdentifier: Any?
+    )
     
     /**
      After the `ListMonitor`'s `refetch(...)` method is called, this method is broadcast after the `NSFetchedResultsController`'s last `controllerDidChangeContent(_:)` notification completes. (Required)
@@ -75,7 +128,9 @@ public protocol ListObserver: AnyObject {
      - Important: When `listMonitorDidRefetch(_:)` is called it should be assumed that all `ListMonitor`'s previous data have been reset, including counts, objects, and persistent stores.
      - parameter monitor: the `ListMonitor` monitoring the object being observed
      */
-    func listMonitorDidRefetch(_ monitor: ListMonitor<ListEntityType>)
+    func listMonitorDidRefetch(
+        _ monitor: ListMonitor<ListEntityType>
+    )
 }
 
 
@@ -83,9 +138,45 @@ public protocol ListObserver: AnyObject {
 
 extension ListObserver {
     
-    public func listMonitorWillChange(_ monitor: ListMonitor<ListEntityType>) { }
+    public func listMonitorWillChange(
+        _ monitor: ListMonitor<ListEntityType>,
+        sourceIdentifier: Any?
+    ) {
+        
+        self.listMonitorWillChange(monitor)
+    }
     
-    public func listMonitorWillRefetch(_ monitor: ListMonitor<ListEntityType>) { }
+    public func listMonitorWillChange(
+        _ monitor: ListMonitor<ListEntityType>
+    ) {}
+    
+    public func listMonitorDidChange(
+        _ monitor: ListMonitor<ListEntityType>,
+        sourceIdentifier: Any?
+    ) {
+        
+        self.listMonitorDidChange(monitor)
+    }
+    
+    public func listMonitorWillRefetch(
+        _ monitor: ListMonitor<ListEntityType>,
+        sourceIdentifier: Any?
+    ) {
+        
+        self.listMonitorWillRefetch(monitor)
+    }
+    
+    public func listMonitorWillRefetch(
+        _ monitor: ListMonitor<ListEntityType>
+    ) {}
+    
+    public func listMonitorDidRefetch(
+        _ monitor: ListMonitor<ListEntityType>,
+        sourceIdentifier: Any?
+    ) {
+        
+        self.listMonitorDidRefetch(monitor)
+    }
 }
 
 
@@ -110,8 +201,44 @@ public protocol ListObjectObserver: ListObserver {
      - parameter monitor: the `ListMonitor` monitoring the list being observed
      - parameter object: the entity type for the inserted object
      - parameter indexPath: the new `NSIndexPath` for the inserted object
+     - parameter sourceIdentifier: an optional identifier provided by the transaction source
      */
-    func listMonitor(_ monitor: ListMonitor<ListEntityType>, didInsertObject object: ListEntityType, toIndexPath indexPath: IndexPath)
+    func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didInsertObject object: ListEntityType,
+        toIndexPath indexPath: IndexPath,
+        sourceIdentifier: Any?
+    )
+    
+    /**
+     Notifies that an object was inserted to the specified `NSIndexPath` in the list. (Optional)
+     The default implementation does nothing.
+     
+     - parameter monitor: the `ListMonitor` monitoring the list being observed
+     - parameter object: the entity type for the inserted object
+     - parameter indexPath: the new `NSIndexPath` for the inserted object
+     */
+    func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didInsertObject object: ListEntityType,
+        toIndexPath indexPath: IndexPath
+    )
+    
+    /**
+     Notifies that an object was deleted from the specified `NSIndexPath` in the list. (Optional)
+     The default implementation does nothing.
+     
+     - parameter monitor: the `ListMonitor` monitoring the list being observed
+     - parameter object: the entity type for the deleted object
+     - parameter indexPath: the `NSIndexPath` for the deleted object
+     - parameter sourceIdentifier: an optional identifier provided by the transaction source
+     */
+    func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didDeleteObject object: ListEntityType,
+        fromIndexPath indexPath: IndexPath,
+        sourceIdentifier: Any?
+    )
     
     /**
      Notifies that an object was deleted from the specified `NSIndexPath` in the list. (Optional)
@@ -121,7 +248,27 @@ public protocol ListObjectObserver: ListObserver {
      - parameter object: the entity type for the deleted object
      - parameter indexPath: the `NSIndexPath` for the deleted object
      */
-    func listMonitor(_ monitor: ListMonitor<ListEntityType>, didDeleteObject object: ListEntityType, fromIndexPath indexPath: IndexPath)
+    func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didDeleteObject object: ListEntityType,
+        fromIndexPath indexPath: IndexPath
+    )
+    
+    /**
+     Notifies that an object at the specified `NSIndexPath` was updated. (Optional)
+     The default implementation does nothing.
+     
+     - parameter monitor: the `ListMonitor` monitoring the list being observed
+     - parameter object: the entity type for the updated object
+     - parameter indexPath: the `NSIndexPath` for the updated object
+     - parameter sourceIdentifier: an optional identifier provided by the transaction source
+     */
+    func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didUpdateObject object: ListEntityType,
+        atIndexPath indexPath: IndexPath,
+        sourceIdentifier: Any?
+    )
     
     /**
      Notifies that an object at the specified `NSIndexPath` was updated. (Optional)
@@ -131,7 +278,29 @@ public protocol ListObjectObserver: ListObserver {
      - parameter object: the entity type for the updated object
      - parameter indexPath: the `NSIndexPath` for the updated object
      */
-    func listMonitor(_ monitor: ListMonitor<ListEntityType>, didUpdateObject object: ListEntityType, atIndexPath indexPath: IndexPath)
+    func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didUpdateObject object: ListEntityType,
+        atIndexPath indexPath: IndexPath
+    )
+    
+    /**
+     Notifies that an object's index changed. (Optional)
+     The default implementation does nothing.
+     
+     - parameter monitor: the `ListMonitor` monitoring the list being observed
+     - parameter object: the entity type for the moved object
+     - parameter fromIndexPath: the previous `NSIndexPath` for the moved object
+     - parameter toIndexPath: the new `NSIndexPath` for the moved object
+     - parameter sourceIdentifier: an optional identifier provided by the transaction source
+     */
+    func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didMoveObject object: ListEntityType,
+        fromIndexPath: IndexPath,
+        toIndexPath: IndexPath,
+        sourceIdentifier: Any?
+    )
     
     /**
      Notifies that an object's index changed. (Optional)
@@ -142,7 +311,12 @@ public protocol ListObjectObserver: ListObserver {
      - parameter fromIndexPath: the previous `NSIndexPath` for the moved object
      - parameter toIndexPath: the new `NSIndexPath` for the moved object
      */
-    func listMonitor(_ monitor: ListMonitor<ListEntityType>, didMoveObject object: ListEntityType, fromIndexPath: IndexPath, toIndexPath: IndexPath)
+    func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didMoveObject object: ListEntityType,
+        fromIndexPath: IndexPath,
+        toIndexPath: IndexPath
+    )
 }
 
 
@@ -150,13 +324,88 @@ public protocol ListObjectObserver: ListObserver {
 
 extension ListObjectObserver {
     
-    public func listMonitor(_ monitor: ListMonitor<ListEntityType>, didInsertObject object: ListEntityType, toIndexPath indexPath: IndexPath) { }
+    public func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didInsertObject object: ListEntityType,
+        toIndexPath indexPath: IndexPath,
+        sourceIdentifier: Any?
+    ) {
+        
+        self.listMonitor(
+            monitor,
+            didInsertObject: object,
+            toIndexPath: indexPath
+        )
+    }
     
-    public func listMonitor(_ monitor: ListMonitor<ListEntityType>, didDeleteObject object: ListEntityType, fromIndexPath indexPath: IndexPath) { }
+    public func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didInsertObject object: ListEntityType,
+        toIndexPath indexPath: IndexPath
+    ) {}
     
-    public func listMonitor(_ monitor: ListMonitor<ListEntityType>, didUpdateObject object: ListEntityType, atIndexPath indexPath: IndexPath) { }
+    public func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didDeleteObject object: ListEntityType,
+        fromIndexPath indexPath: IndexPath,
+        sourceIdentifier: Any?
+    ) {
+        
+        self.listMonitor(
+            monitor,
+            didDeleteObject: object,
+            fromIndexPath: indexPath
+        )
+    }
     
-    public func listMonitor(_ monitor: ListMonitor<ListEntityType>, didMoveObject object: ListEntityType, fromIndexPath: IndexPath, toIndexPath: IndexPath) { }
+    public func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didDeleteObject object: ListEntityType,
+        fromIndexPath indexPath: IndexPath
+    ) {}
+    
+    public func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didUpdateObject object: ListEntityType,
+        atIndexPath indexPath: IndexPath,
+        sourceIdentifier: Any?
+    ) {
+        
+        self.listMonitor(
+            monitor,
+            didUpdateObject: object,
+            atIndexPath: indexPath
+        )
+    }
+    
+    public func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didUpdateObject object: ListEntityType,
+        atIndexPath indexPath: IndexPath
+    ) {}
+    
+    public func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didMoveObject object: ListEntityType,
+        fromIndexPath: IndexPath,
+        toIndexPath: IndexPath,
+        sourceIdentifier: Any?
+    ) {
+        
+        self.listMonitor(
+            monitor,
+            didMoveObject: object,
+            fromIndexPath: fromIndexPath,
+            toIndexPath: toIndexPath
+        )
+    }
+    
+    public func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didMoveObject object: ListEntityType,
+        fromIndexPath: IndexPath,
+        toIndexPath: IndexPath
+    ) {}
 }
 
 
@@ -182,8 +431,44 @@ public protocol ListSectionObserver: ListObjectObserver {
      - parameter monitor: the `ListMonitor` monitoring the list being observed
      - parameter sectionInfo: the `NSFetchedResultsSectionInfo` for the inserted section
      - parameter sectionIndex: the new section index for the new section
+     - parameter sourceIdentifier: an optional identifier provided by the transaction source
      */
-    func listMonitor(_ monitor: ListMonitor<ListEntityType>, didInsertSection sectionInfo: NSFetchedResultsSectionInfo, toSectionIndex sectionIndex: Int)
+    func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didInsertSection sectionInfo: NSFetchedResultsSectionInfo,
+        toSectionIndex sectionIndex: Int,
+        sourceIdentifier: Any?
+    )
+    
+    /**
+     Notifies that a section was inserted at the specified index. (Optional)
+     The default implementation does nothing.
+     
+     - parameter monitor: the `ListMonitor` monitoring the list being observed
+     - parameter sectionInfo: the `NSFetchedResultsSectionInfo` for the inserted section
+     - parameter sectionIndex: the new section index for the new section
+     */
+    func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didInsertSection sectionInfo: NSFetchedResultsSectionInfo,
+        toSectionIndex sectionIndex: Int
+    )
+    
+    /**
+     Notifies that a section was inserted at the specified index. (Optional)
+     The default implementation does nothing.
+     
+     - parameter monitor: the `ListMonitor` monitoring the list being observed
+     - parameter sectionInfo: the `NSFetchedResultsSectionInfo` for the deleted section
+     - parameter sectionIndex: the previous section index for the deleted section
+     - parameter sourceIdentifier: an optional identifier provided by the transaction source
+     */
+    func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didDeleteSection sectionInfo: NSFetchedResultsSectionInfo,
+        fromSectionIndex sectionIndex: Int,
+        sourceIdentifier: Any?
+    )
     
     /**
      Notifies that a section was inserted at the specified index. (Optional)
@@ -193,7 +478,11 @@ public protocol ListSectionObserver: ListObjectObserver {
      - parameter sectionInfo: the `NSFetchedResultsSectionInfo` for the deleted section
      - parameter sectionIndex: the previous section index for the deleted section
      */
-    func listMonitor(_ monitor: ListMonitor<ListEntityType>, didDeleteSection sectionInfo: NSFetchedResultsSectionInfo, fromSectionIndex sectionIndex: Int)
+    func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didDeleteSection sectionInfo: NSFetchedResultsSectionInfo,
+        fromSectionIndex sectionIndex: Int
+    )
 }
 
 
@@ -201,7 +490,43 @@ public protocol ListSectionObserver: ListObjectObserver {
 
 extension ListSectionObserver {
     
-    public func listMonitor(_ monitor: ListMonitor<ListEntityType>, didInsertSection sectionInfo: NSFetchedResultsSectionInfo, toSectionIndex sectionIndex: Int) { }
+    public func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didInsertSection sectionInfo: NSFetchedResultsSectionInfo,
+        toSectionIndex sectionIndex: Int,
+        sourceIdentifier: Any?
+    ) {
+        
+        self.listMonitor(
+            monitor,
+            didInsertSection: sectionInfo,
+            toSectionIndex: sectionIndex
+        )
+    }
     
-    public func listMonitor(_ monitor: ListMonitor<ListEntityType>, didDeleteSection sectionInfo: NSFetchedResultsSectionInfo, fromSectionIndex sectionIndex: Int) { }
+    public func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didInsertSection sectionInfo: NSFetchedResultsSectionInfo,
+        toSectionIndex sectionIndex: Int
+    ) {}
+    
+    public func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didDeleteSection sectionInfo: NSFetchedResultsSectionInfo,
+        fromSectionIndex sectionIndex: Int,
+        sourceIdentifier: Any?
+    ) {
+        
+        self.listMonitor(
+            monitor,
+            didDeleteSection: sectionInfo,
+            fromSectionIndex: sectionIndex
+        )
+    }
+    
+    public func listMonitor(
+        _ monitor: ListMonitor<ListEntityType>,
+        didDeleteSection sectionInfo: NSFetchedResultsSectionInfo,
+        fromSectionIndex sectionIndex: Int
+    ) {}
 }