FetchableSource and QueryableSource protocols

Sources/Convenience/NSFetchedResultsController+Convenience.swift

@@ -34,6 +34,7 @@ public extension DataStack {
     
     /**
      Utility for creating an `NSFetchedResultsController` from the `DataStack`. This is useful when an `NSFetchedResultsController` is preferred over the overhead of `ListMonitor`s abstraction.
+     - Note: It is the caller's responsibility to call `performFetch()` on the created `NSFetchedResultsController`.
      
      - parameter from: a `From` clause indicating the entity type
      - parameter sectionBy: a `SectionBy` clause indicating the keyPath for the attribute to use when sorting the list into sections
@@ -53,6 +54,7 @@ public extension DataStack {
     
     /**
      Utility for creating an `NSFetchedResultsController` from a `DataStack`. This is useful when an `NSFetchedResultsController` is preferred over the overhead of `ListMonitor`s abstraction.
+     - Note: It is the caller's responsibility to call `performFetch()` on the created `NSFetchedResultsController`.
      
      - parameter from: a `From` clause indicating the entity type
      - parameter sectionBy: a `SectionBy` clause indicating the keyPath for the attribute to use when sorting the list into sections
@@ -72,6 +74,7 @@ public extension DataStack {
     
     /**
      Utility for creating an `NSFetchedResultsController` from the `DataStack`. This is useful when an `NSFetchedResultsController` is preferred over the overhead of `ListMonitor`s abstraction.
+     - Note: It is the caller's responsibility to call `performFetch()` on the created `NSFetchedResultsController`.
      
      - parameter from: a `From` clause indicating the entity type
      - parameter fetchClauses: a series of `FetchClause` instances for fetching the object list. Accepts `Where`, `OrderBy`, and `Tweak` clauses.
@@ -90,6 +93,7 @@ public extension DataStack {
     
     /**
      Utility for creating an `NSFetchedResultsController` from the `DataStack`. This is useful when an `NSFetchedResultsController` is preferred over the overhead of `ListMonitor`s abstraction.
+     - Note: It is the caller's responsibility to call `performFetch()` on the created `NSFetchedResultsController`.
      
      - parameter from: a `From` clause indicating the entity type
      - parameter fetchClauses: a series of `FetchClause` instances for fetching the object list. Accepts `Where`, `OrderBy`, and `Tweak` clauses.
@@ -114,6 +118,7 @@ public extension UnsafeDataTransaction {
     
     /**
      Utility for creating an `NSFetchedResultsController` from the `UnsafeDataTransaction`. This is useful when an `NSFetchedResultsController` is preferred over the overhead of `ListMonitor`s abstraction.
+     - Note: It is the caller's responsibility to call `performFetch()` on the created `NSFetchedResultsController`.
      
      - parameter from: a `From` clause indicating the entity type
      - parameter sectionBy: a `SectionBy` clause indicating the keyPath for the attribute to use when sorting the list into sections
@@ -133,6 +138,7 @@ public extension UnsafeDataTransaction {
     
     /**
      Utility for creating an `NSFetchedResultsController` from the `UnsafeDataTransaction`. This is useful when an `NSFetchedResultsController` is preferred over the overhead of `ListMonitor`s abstraction.
+     - Note: It is the caller's responsibility to call `performFetch()` on the created `NSFetchedResultsController`.
      
      - parameter from: a `From` clause indicating the entity type
      - parameter sectionBy: a `SectionBy` clause indicating the keyPath for the attribute to use when sorting the list into sections
@@ -152,6 +158,7 @@ public extension UnsafeDataTransaction {
     
     /**
      Utility for creating an `NSFetchedResultsController` from the `UnsafeDataTransaction`. This is useful when an `NSFetchedResultsController` is preferred over the overhead of `ListMonitor`s abstraction.
+     - Note: It is the caller's responsibility to call `performFetch()` on the created `NSFetchedResultsController`.
      
      - parameter from: a `From` clause indicating the entity type
      - parameter fetchClauses: a series of `FetchClause` instances for fetching the object list. Accepts `Where`, `OrderBy`, and `Tweak` clauses.
@@ -170,6 +177,7 @@ public extension UnsafeDataTransaction {
     
     /**
      Utility for creating an `NSFetchedResultsController` from the `UnsafeDataTransaction`. This is useful when an `NSFetchedResultsController` is preferred over the overhead of `ListMonitor`s abstraction.
+     - Note: It is the caller's responsibility to call `performFetch()` on the created `NSFetchedResultsController`.
      
      - parameter from: a `From` clause indicating the entity type
      - parameter fetchClauses: a series of `FetchClause` instances for fetching the object list. Accepts `Where`, `OrderBy`, and `Tweak` clauses.

Sources/Convenience/NSManagedObject+Convenience.swift

@@ -31,6 +31,52 @@ import CoreData
 
 public extension NSManagedObject {
     
+    /**
+     Exposes a `FetchableSource` that can fetch sibling objects of this `NSManagedObject` instance. This may be the `DataStack`, a `BaseDataTransaction`, the `NSManagedObjectContext` itself, or `nil` if the obejct's parent is already deallocated.
+     - Warning: Future implementations may change the instance returned by this method depending on the timing or condition that `fetchSource()` was called. Do not make assumptions that the instance will be a specific instance. If the `NSManagedObjectContext` instance is desired, use the `FetchableSource.internalContext()` method to get the correct instance. Also, do not assume that the `fetchSource()` and `querySource()` return the same instance all the time.
+     - returns: a `FetchableSource` that can fetch sibling objects of this `NSManagedObject` instance. This may be the `DataStack`, a `BaseDataTransaction`, the `NSManagedObjectContext` itself, or `nil` if the object's parent is already deallocated.
+     */
+    @nonobjc
+    public func fetchSource() -> FetchableSource? {
+        
+        guard let context = self.managedObjectContext else {
+            
+            return nil
+        }
+        if context.isTransactionContext {
+            
+            return context.parentTransaction
+        }
+        if context.isDataStackContext {
+            
+            return context.parentStack
+        }
+        return context
+    }
+    
+    /**
+     Exposes a `QueryableSource` that can query attributes and aggregate values. This may be the `DataStack`, a `BaseDataTransaction`, the `NSManagedObjectContext` itself, or `nil` if the obejct's parent is already deallocated.
+     - Warning: Future implementations may change the instance returned by this method depending on the timing or condition that `querySource()` was called. Do not make assumptions that the instance will be a specific instance. If the `NSManagedObjectContext` instance is desired, use the `QueryableSource.internalContext()` method to get the correct instance. Also, do not assume that the `fetchSource()` and `querySource()` return the same instance all the time.
+     - returns: a `QueryableSource` that can query attributes and aggregate values. This may be the `DataStack`, a `BaseDataTransaction`, the `NSManagedObjectContext` itself, or `nil` if the object's parent is already deallocated.
+     */
+    @nonobjc
+    public func querySource() -> QueryableSource? {
+        
+        guard let context = self.managedObjectContext else {
+            
+            return nil
+        }
+        if context.isTransactionContext {
+            
+            return context.parentTransaction
+        }
+        if context.isDataStackContext {
+            
+            return context.parentStack
+        }
+        return context
+    }
+    
     /**
      Provides a convenience wrapper for accessing `primitiveValueForKey(...)` with proper calls to `willAccessValueForKey(...)` and `didAccessValueForKey(...)`. This is useful when implementing accessor methods for transient attributes.