gjnilsen / jsqcoredatakit

A swifter Core Data stack

JSQCoreDataKit

A swifter Core Data stack

About

This library aims to do the following:

• Provide better interoperability with Swift
• Harness Swift features and enforce Swift paradigms
• Bring functional paradigms to Core Data
• Make Core Data more Swifty
• Simplify the processes of standing up the Core Data stack
• Aid in testing your Core Data models
• Reduce the boilerplate involved with Core Data

Further reading on Core Data:

• Core Data Programming Guide
• Core Data Core Competencies Guide
• objc.io issue #4 on Core Data
• Concurrent Core Data Stacks – Performance Shootout
• Backstage with Nested Managed Object Contexts
• BNR core data stack

Requirements

• Xcode 7.3+
• iOS 8.0+
• OSX 10.10+
• tvOS 9.0+
• watchOS 2.0+
• Swift 2.2+

Installation

CocoaPods (recommended)

use_frameworks!

# For latest release in cocoapods
pod 'JSQCoreDataKit'

# Feeling adventurous? Get the latest on develop
pod 'JSQCoreDataKit', :git => 'https://github.com/jessesquires/JSQCoreDataKit.git', :branch => 'develop'

Carthage

github "jessesquires/JSQCoreDataKit"

Documentation

Read the docs. Generated with jazzy. Hosted by GitHub Pages. More information on the gh-pages branch.

Getting Started

import JSQCoreDataKit

Standing up the stack

// Initialize the Core Data model, this class encapsulates the notion of a .xcdatamodeld file
// The name passed here should be the name of an .xcdatamodeld file
let bundle = NSBundle(identifier: "com.MyApp.MyModelFramework")!
let model = CoreDataModel(name: "MyModel", bundle: bundle)

// Initialize a stack with a factory
let factory = CoreDataStackFactory(model: model)

let stack: CoreDataStack?
factory.createStack { (result: StackResult) in
    switch result {
        case .Success(let s):
            stack = s

        case .Failure(let e):
            print("Error: \(e)")
    }
}

In-memory stacks for testing

let inMemoryModel = CoreDataModel(name: myName, bundle: myBundle, storeType: .InMemory)
let factory = CoreDataStackFactory(model: inMemoryModel)

let stack: CoreDataStack?
factory.createStack { (result: StackResult) in
    switch result {
        case .Success(let s):
            stack = s

        case .Failure(let e):
            print("Error: \(e)")
    }
}

Saving a managed object context

saveContext(stack.mainContext) { result in
    switch result {
        case .Success:
            print("save succeeded")

        case .Failure(let error):
            print("save failed: \(error)")
    }
}

Deleting the store

let bundle = NSBundle(identifier: "com.MyApp.MyModelFramework")!
let model = CoreDataModel(name: "MyModel", bundle: bundle)
do {
    try model.removeExistingStore()
} catch {
    print("Error: \(error)")
}

Performing migrations

let bundle = NSBundle(identifier: "com.MyApp.MyModelFramework")!
let model = CoreDataModel(name: "MyModel", bundle: bundle)
if model.needsMigration {
    do {
        try model.migrate()
    } catch {
        print("Failed to migrate model: \(error)")
    }
}

Using child contexts

// Create a main queue child context from the main context
let childContext = stack.childContext(concurrencyType: .MainQueueConcurrencyType)

// Create a background queue child context from the background context
let childContext = stack.childContext(concurrencyType: .PrivateQueueConcurrencyType)

Fetching

// Create a FetchRequest<T>, where T is a phantom type
let entity = entity(name: "MyModel", context: context)!
let request = FetchRequest<MyModel>(entity: entity)

var results = [MyModel]()
do {
    results = try stack.mainContext.fetch(request: request)
}
catch {
    print("Fetch error: \(error)")
}

print("Results = \(results)")

Deleting

let objects: [MyModel] = /* array of MyModel objects */

stack.mainContext.delete(objects: objects)

// Commit changes to remove objects from store
saveContext(context)

Example app

There's an example app in the Example/ directory. Open the ExampleApp.xcodeproj to run it. The project exercises all basic functionality of the library.

Unit tests

There's a suite of unit tests for JSQCoreDataKit.framework. You can run them in the usual way from Xcode by opening JSQCoreDataKit.xcodeproj. These tests are well commented and serve as further documentation for how to use this library.

Contribute

Please follow these sweet contribution guidelines.

Credits

Created and maintained by @jesse_squires.

License

JSQCoreDataKit is released under an MIT License. See LICENSE for details.

Copyright © 2015-present Jesse Squires.

Please provide attribution, it is greatly appreciated.