Categories

Objective-C

@interface NSFetchRequest (KBAExtensions)

/**
 Create and return a NSFetchRequest with the provided parameters. Calls through to KBA_fetchRequestWithOptions: with the appropriate options dictionary.
 
 @param entityName The name of the entity to fetch
 @param predicate The predicate to apply to the fetch request
 @param sortDescriptors The sort descriptors to apply to the fetch request
 @param limit The fetch limit to apply to the fetch request
 @param offset The fetch offset to apply to the fetch request
 @return The fetch request
 */
+ (instancetype)KBA_fetchRequestForEntityName:(NSString *)entityName predicate:(nullable NSPredicate *)predicate sortDescriptors:(nullable NSArray<NSSortDescriptor *> *)sortDescriptors limit:(NSUInteger)limit offset:(NSUInteger)offset;
/**
 Create and return a fetch request with the provided options.
 
 @param options The dictionary of options to use when creating the fetch request
 @return The fetch request
 */
+ (instancetype)KBA_fetchRequestWithOptions:(NSDictionary<KBANSFetchRequestOptionsKey, id> *)options;

@end

Objective-C

@interface NSManagedObjectContext (KBAExtensions)

/**
 Recursively saves the receiver and its `parentContext`.
 
 This is a blocking call.
 
 @param error On failure, the `NSError` object explaining the reason for failure
 @return YES if the save was successful, otherwise NO
 */
- (BOOL)KBA_saveRecursively:(NSError *__autoreleasing *)error;

/**
 Calls KBA_fetchEntityNamed:predicate:sortDescriptors:limit:offset:error:, passing _entityName_, _predicate_, _sortDescriptors_, and _error_ respectively.
 
 @param entityName The name of the entity of fetch
 @param predicate The predicate that will constrain the resulting set of objects
 @param sortDescriptors An array of sort descriptors to apply to the resulting set of objects
 @param error On failure, the NSError object explaining the reason for failure
 @return The resulting set of NSManagedObject instances
 @exception NSException Thrown if _entityName_ is nil
 */
- (nullable NSArray<__kindof NSManagedObject *> *)KBA_fetchEntityNamed:(NSString *)entityName predicate:(nullable NSPredicate *)predicate sortDescriptors:(nullable NSArray<NSSortDescriptor *> *)sortDescriptors error:(NSError *__autoreleasing *)error;
/**
 Calls KBA_fetchEntityNamed:predicate:sortDescriptors:limit:offset:error:, passing _entityName_, _predicate_, _sortDescriptors_, _limit_, and _error_ respectively.
 
 @param entityName The name of the entity of fetch
 @param predicate The predicate that will constrain the resulting set of objects
 @param sortDescriptors An array of sort descriptors to apply to the resulting set of objects
 @param limit If _limit_ > 0, constrain the resulting set of objects to _limit_ count
 @param error On failure, the NSError object explaining the reason for failure
 @return The resulting set of NSManagedObject instances
 @exception NSException Thrown if _entityName_ is nil
 */
- (nullable NSArray<__kindof NSManagedObject *> *)KBA_fetchEntityNamed:(NSString *)entityName predicate:(nullable NSPredicate *)predicate sortDescriptors:(nullable NSArray<NSSortDescriptor *> *)sortDescriptors limit:(NSUInteger)limit error:(NSError *__autoreleasing *)error;
/**
 Constructs and executes a NSFetchRequest using _entityName_, _predicate_, _sortDescriptors_, _limit_, _offset_, and _error_.
 
 @param entityName The name of the entity to fetch
 @param predicate The predicate that will constrain the resulting set of objects
 @param sortDescriptors An array of sort descriptors to apply to the resulting set of objects
 @param limit If _limit_ > 0, constrain the resulting set of objects to _limit_ count
 @param offset If _offset_ > 0, start fetching the resulting set of objects from index _offset_
 @param error On failure, the NSError object explaining the reason for failure
 @return The resulting set of NSManagedObject instances
 @exception NSException Thrown if _entityName_ is nil
 */
- (nullable NSArray<__kindof NSManagedObject *> *)KBA_fetchEntityNamed:(NSString *)entityName predicate:(nullable NSPredicate *)predicate sortDescriptors:(nullable NSArray<NSSortDescriptor *> *)sortDescriptors limit:(NSUInteger)limit offset:(NSUInteger)offset error:(NSError *__autoreleasing *)error;

/**
 Calls `KBA_fetchEntityNamed:predicate:sortDescriptors:limit:offset:completion:`, passing `entityName`, `predicate`, `sortDescriptors`, 0, 0, and `completion` respectively.
 
 @param entityName The name of the entity to fetch
 @param predicate The predicate that will constrain the resulting set of objects
 @param sortDescriptors The sort descriptors to apply to the resulting set of objects
 @param completion The completion block that is invoked when the operation is complete, objects contains NSManagedObject instance, if nil, error contains information about the reason for failure
 @exception NSException Thrown if entityName or completion are nil
 */
- (void)KBA_fetchEntityNamed:(NSString *)entityName predicate:(nullable NSPredicate *)predicate sortDescriptors:(nullable NSArray<NSSortDescriptor *> *)sortDescriptors completion:(KBACoreDataCompletionBlock)completion;
/**
 Calls `KBA_fetchEntityNamed:predicate:sortDescriptors:limit:offset:completion:`, passing `entityName`, `predicate`, `sortDescriptors`, `limit`, 0, and `completion` respectively.
 
 @param entityName The name of the entity to fetch
 @param predicate The predicate that will constrain the resulting set of objects
 @param sortDescriptors The sort descriptors to apply to the resulting set of objects
 @param limit The fetch limit to apply to the fetch request
 @param completion The completion block that is invoked when the operation is complete, objects contains NSManagedObject instance, if nil, error contains information about the reason for failure
 @exception NSException Thrown if entityName or completion are nil
 */
- (void)KBA_fetchEntityNamed:(NSString *)entityName predicate:(nullable NSPredicate *)predicate sortDescriptors:(nullable NSArray<NSSortDescriptor *> *)sortDescriptors limit:(NSUInteger)limit completion:(KBACoreDataCompletionBlock)completion;
/**
 Performs an asynchronous fetch request, using NSAsynchronousFetchRequest if it is available. Falls back to fetching object IDs and converting them to managed objects on the calling thread.
 
 @param entityName The name of the entity to fetch
 @param predicate The predicate that will constrain the resulting set of objects
 @param sortDescriptors The sort descriptors to apply to the resulting set of objects
 @param limit The fetch limit to apply to the fetch request
 @param offset The fetch offset to apply to the fetch request
 @param completion The completion block that is invoked when the operation is complete, objects contains NSManagedObject instance, if nil, error contains information about the reason for failure
 @exception NSException Thrown if entityName or completion are nil
 */
- (void)KBA_fetchEntityNamed:(NSString *)entityName predicate:(nullable NSPredicate *)predicate sortDescriptors:(nullable NSArray<NSSortDescriptor *> *)sortDescriptors limit:(NSUInteger)limit offset:(NSUInteger)offset completion:(KBACoreDataCompletionBlock)completion;

/**
 Constructs and executes a NSFetchRequest using _entityName_, _predicate_, and _error_.
 
 The result type is set to NSCountResultType.
 
 @param entityName The name of the entity to fetch
 @param predicate The predicate that will constrain the resulting set of objects
 @param error On failure, the NSError object explaining the reason for failure
 @return The number of objects in the result set
 @exception NSException Thrown if _entityName_ is nil
 */
- (NSUInteger)KBA_countForEntityNamed:(NSString *)entityName predicate:(nullable NSPredicate *)predicate error:(NSError *__autoreleasing *)error;

/**
 Constructs and executes a NSFetchRequest using _entityName_, _predicate_, _sortDescriptors_, and _error_.
 
 The result type is set to NSDictionaryResultType and _properties_ are used for `propertiesToFetch`.
 
 @param entityName The name of the entity to fetch
 @param properties The properties to fetch
 @param predicate The predicate that will constrain the resulting set of objects
 @param sortDescriptors An array of sort descriptors to apply to the resulting set of objects
 @param error On failure, the NSError object explaining the reason for failure
 @return The resulting set of NSManagedObject instances
 @exception NSException Thrown if _entityName_ or _properties_ are nil
 */
- (NSArray<NSDictionary<NSString *, id> *> *)KBA_fetchPropertiesForEntityNamed:(NSString *)entityName properties:(NSArray *)properties predicate:(nullable NSPredicate *)predicate sortDescriptors:(nullable NSArray<NSSortDescriptor *> *)sortDescriptors error:(NSError *__autoreleasing *)error;

/**
 Creates and executes a NSFetchRequest with the provided *options*.
 
 @param options The options to use when creating the fetch request
 @return The result of executing the fetch request
 */
- (NSArray *)KBA_fetchWithOptions:(NSDictionary<KBANSFetchRequestOptionsKey, id> *)options;
/**
 Creates and executes a NSFetchRequest with the provided *options* and *error*.
 
 @param options The options to use when creating the fetch request
 @param error The error that resulted from executing the fetch request
 @return The result of executing the fetch request
 */
- (NSArray *)KBA_fetchWithOptions:(NSDictionary<KBANSFetchRequestOptionsKey, id> *)options error:(NSError *__autoreleasing *)error;

@end

Objective-C

@interface NSManagedObjectContext (KBAImportExtensions)

/**
 Set and get the key used for testing equality when importing. If you require a custom key, this should be set before calling `KBA_importJSON:entityOrder:entityMapping:completion:`.
 
 The default is @"identity".
 */
@property (class,copy,nonatomic,null_resettable) NSString *KBA_defaultIdentityKey;
/**
 Set and get the date formatter used to convert between JSON and NSDate objects.
 
 The default is an NSDateFormatter with @"yyyy-MM-dd'T'HH:mm:ssZZZZZ" as its date format.
 */
@property (class,strong,nonatomic,null_resettable) NSDateFormatter *KBA_defaultDateFormatter;

/**
 Get the object responsible for mapping between entity properties and JSON keys.
 
 The default is an instance of KBADefaultManagedObjectPropertyMapping.
 
 @param entityName The name of the entity
 @return The property mapping object for the entity with name
 */
+ (id<KBAManagedObjectPropertyMapping>)KBA_propertyMappingForEntityNamed:(NSString *)entityName;
/**
 Register a property mapping for a particular entity.
 
 @param propertyMapping An object conforming to KBAManagedObjectPropertyMapping
 @param entityName The name of the entity
 */
+ (void)KBA_registerPropertyMapping:(nullable id<KBAManagedObjectPropertyMapping>)propertyMapping forEntityNamed:(NSString *)entityName;

/**
 Returns a NSManagedObject of entityName by mapping keys and values in dictionary using propertyMapping.
 
 @param dictionary The dictionary of property/relationship key/value pairs
 @param entityName The name of the entity to create
 @param propertyMapping The property mapping to use during creation
 @param error If the method returns nil, an error describing the reason for failure
 @return The managed object
 */
- (nullable __kindof NSManagedObject *)KBA_managedObjectWithDictionary:(NSDictionary *)dictionary entityName:(NSString *)entityName propertyMapping:(id<KBAManagedObjectPropertyMapping>)propertyMapping error:(NSError *__autoreleasing *)error;

/**
 Imports the provided JSON, creating managed objects for each entry using entityMapping, which maps between JSON keys and entity names. Invokes the completion block when the operation is finished.
 
 @param JSON A collection conforming to NSFastEnumeration, if a NSDictionary is provided, entityOrder can be nil
 @param entityOrder The order to import the entities in JSON
 @param entityMapping The entity mapping
 @param completion The completion block invoked when the operation is finished
 */
- (void)KBA_importJSON:(id<NSFastEnumeration,NSObject>)JSON entityOrder:(nullable NSArray *)entityOrder entityMapping:(nullable id<KBAManagedObjectEntityMapping>)entityMapping completion:(void(^)(BOOL success, NSError *_Nullable error))completion;

@end