Skip to content
This repository has been archived by the owner. It is now read-only.
The Big Nerd Ranch Core Data Stack
Swift Ruby Shell Objective-C
Branch: master
Clone or download

Latest commit

Latest commit 1592253 Oct 17, 2017


Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Fix typos in contributing doc [ci skip] Mar 3, 2016
Container Example Update container’s readme May 24, 2017
CoreDataStack.xcodeproj Fixed @objc warnings Oct 2, 2017
Example SwiftLint: Shaddup May 23, 2017
Resources Skip Carthage validation when testing forked pull request Mar 28, 2017
Sample Model Add objc declaration to first initial variable on Book Oct 17, 2017
Sources Removed redundant protocol conformance Oct 2, 2017
Tests Corrected notifications code naming Oct 2, 2017
fastlane Replace echo with puts to suppress fastlane warning May 17, 2017
.cocoadocs.yml Add cocoadocs font and color formatting. Nov 2, 2015
.gitignore Add build folder to gitignore May 12, 2016
.hound.yml Add hound configuration file Mar 11, 2016
.jazzy.yml Update jazzy doc generation configuration Oct 12, 2016
.ruby-version Bump ruby version and dependencies Sep 30, 2016
.swift-version Bump swift version May 17, 2017
.swiftlint.yml SwiftLint: Shaddup May 23, 2017
.travis.yml Update travis configuration for newer xcode Oct 17, 2017
BNRCoreDataStack.podspec Podspec updated Oct 2, 2017
Gemfile Use master version of cocoa pods Oct 12, 2016
Gemfile.lock Update fastlane Oct 17, 2017
LICENSE Adds MIT license. Aug 18, 2015
Package.swift Reorganize to support Swift Package Manager Feb 26, 2016 Mark code block as Swift May 23, 2017
circle.yml Comment out CircleCI configuration Sep 30, 2016

BNR Core Data Stack

Carthage compatible CocoaPods Compatible GitHub license Build Status

Big Nerd Ranch

The BNR Core Data Stack is a small Swift framework that makes it both easier and safer to use Core Data.

A better fetched results controller and delegate

Our FetchedResultsController<ManagedObjectType> sends Swifty delegate messages, rather than a mess of optionals.

Turn this:

func controller(
    _ controller: NSFetchedResultsController<NSFetchRequestResult>,
    didChange anObject: Any,
    at indexPath: IndexPath?,
    for type: NSFetchedResultsChangeType,
    newIndexPath: IndexPath?
) {
    guard let book = anObject as? Book else {
        preconditionFailure("Why is this thing an Any anyway? WTH!")

    switch type {
    case .insert:
        guard let newIndexPath = newIndexPath else {
            preconditionFailure("Insertion to nowheresville? WHY IS THIS OPTIONAL?")

        print("We have a new book! \(book.title)")
        tableView?.insertRows(at: [newIndexPath], with: .automatic)

    case .delete:
        guard let indexPath = indexPath else {
            preconditionFailure("Deletion you say? Where? WHY IS THIS OPTIONAL?")

        tableView?.deleteRows(at: [indexPath], with: .automatic)

    case .move:
        guard let newIndexPath = newIndexPath else {
            preconditionFailure("It moved to NOWHERE! WHY IS THIS OPTIONAL?")
        guard let indexPath = indexPath else {
            preconditionFailure("It moved from NOWHERE?! WHY IS THIS OPTIONAL!")

        tableView?.moveRow(at: indexPath, to: newIndexPath)

    case .update:
        guard let indexPath = indexPath else {
            preconditionFailure("I give up! Remind me, why are we using Swift, again?")

        tableView?.reloadRows(at: [indexPath!], with: .automatic)

Into this:

func fetchedResultsController(
    _ controller: FetchedResultsController<Book>,
    didChangeObject change: FetchedResultsObjectChange<Book>
) {
    switch change {
    case let .insert(book, indexPath):
        print("Hey look, it's not an Any! A new book: \(book.title)")
        tableView?.insertRows(at: [indexPath], with: .automatic)

    case let .delete(_ /*book*/, indexPath):
        print("A deletion, and it has a from-where? Finally!")
        tableView?.deleteRows(at: [indexPath], with: .automatic)

    case let .move(_ /*book*/, fromIndexPath, toIndexPath):
        print("Whoah, wait, I actually HAVE index paths? Both of them? Yay!")
        tableView?.moveRow(at: fromIndexPath, to: toIndexPath)

    case let .update(_ /*book*/, indexPath):
        print("It's almost like I'm actually using Swift and not Obj-C!")
        tableView?.reloadRows(at: [indexPath], with: .automatic)

It also has properly typed sections and subscripting operators. Because, we are writing Swift, are we not?

As a further bonus, you get our workarounds for some misbehavior of Core Data that contradicts the documentation, like this one:

// Work around a bug in Xcode 7.0 and 7.1 when running on iOS 8 - updated objects
// sometimes result in both an Update *and* an Insert call to didChangeObject,
// … (explanation continues) …

Convenient store change listening

Our EntityMonitor<ManagedObjectType> makes it easy to listen to all changes for a given ManagedObjectType:

let authorMonitor = EntityMonitor<Author>(context: moc, entity: authorEntityDescription, frequency: .onSave)
let authorMonitorDelegate = AuthorMonitorDelegate()

class AuthorMonitorDelegate: EntityMonitorDelegate {
    func entityMonitorObservedInserts(
        _ monitor: EntityMonitor<Author>,
        entities: Set<Author>
    ) {
        print("inserted authors:", entities)

    func entityMonitorObservedModifications(
        _ monitor: EntityMonitor<Author>,
        entities: Set<Author>
    ) {
        print("modified authors:", entities)

    func entityMonitorObservedDeletions(
        _ monitor: EntityMonitor<Author>,
        entities: Set<Author>
    ) {
        print("deleted authors:", entities)

A friendlier managed object context

Extension methods on ManagedObjectContext ensure saves happen on the right queue and make your life easier:

// Gotta catch 'em all
let allBooks = try Book.allInContext(moc)

// Or at least one of 'em
let anyBook = try Book.findFirstInContext(moc)

// Ah, forget it. Rocks fall, everyone dies.
try Book.removeAllInContext(moc)

// Blocking save, including up through parent contexts,
// on the appropriate queue.
try moc.saveContextToStoreAndWait()


Check out the documentation!

For more details on the design methodology, read "Introducing the Big Nerd Ranch Core Data Stack."

Why "Stack"? Previously, the Core Data Stack provided a full, ready-made Core Data stack. Apple now provide that themselves in NSPersistentContainer, so we're free to focus on the other benefits listed above, and we have [deprecated][#sec:deprecations] our own stack in favor of Apple's.

Swift-Only: Note that the Core Data Stack is intended to be used from Swift. Any use you can make of it from Objective-C is by luck, not design.


Big Nerd Ranch can help you develop your app, or train you or your team in Swift, iOS, and more. We share what we learn here on GitHub and in bookstores near you.

For questions specific to the Core Data Stack, please open an issue.

Minimum Requirements


Apps using BNR Core Data Stack can be used on devices running these versions or later:

  • macOS 10.10
  • tvOS 9.0
  • iOS 8.0


To build an app using BNR Core Data Stack, you'll need:

  • Xcode 8.0
  • Swift 3.0


Type Safe Monitors

Fetched Results Controller

FetchedResultsController<T> is a type safe wrapper around NSFetchedResultsController using Swift generics.


See BooksTableViewController.swift for an example.

Entity Monitor

EntityMonitor<T> is a class for monitoring inserts, deletes, and updates of a specific NSManagedObject subclass within an NSManagedObjectContext.


See EntityMonitorTests.swift for an example.

NSManagedObject Extensions

Adds convenience methods on NSManagedObject` subclasses. These methods make fetching, inserting, deleting, and change management easier.


let allBooks = try Book.allInContext(moc)
let anyBook = try Book.findFirstInContext(moc)
try Book.removeAllInContext(moc)


Installing with Carthage

Add the following to your Cartfile:

github "BigNerdRanch/CoreDataStack"

Then run carthage update.

In your code, import the framework as CoreDataStack.

Follow the current instructions in Carthage's README for up to date installation instructions.

Installing with CocoaPods

Add the following to your Podfile:

pod 'BNRCoreDataStack'

You will also need to make sure you're opting into using frameworks:


Then run pod install.

In your code, import the framework as BNRCoreDataStack.


Please see our guide to contributing to the CoreDataStack.

Debugging Tips

To validate that you are honoring all of the threading rules it's common to add the following to a project scheme under Run > Arguments > Arguments Passed On Launch. 1

This will throw an exception if you happen to break a threading rule. For more on setting up Launch Arguments check out this article by NSHipster.

Excluding sensitive data from iCloud and iTunes backups

The default store location will be backed up. If you're storing sensitive information such as health records, and perhaps if you're storing any personally identifiable information, you should exclude the store from backup by flagging the URL on disk:

var excludeFromBackup = URLResourceValues()
excludeFromBackup.isExcludedFromBackup = true

let someParentDirectoryURL: URL = 
var storeFileURL = URL(
    string: "MyModel.sqlite",
    relativeTo: someParentDirectoryURL)!
try! storeFileURL.setResourceValues(excludeFromBackup)

You then need to point your persistent container at that location:

// Ensure parent directory exists
try! FileManager.default.createDirectory(
    at: storeFileURL.deletingLastPathComponent(),
    withIntermediateDirectories: true)

// Configure the persistent container to use the specific URL
container.persistentStoreDescriptions = [
    NSPersistentStoreDescription(url: storeFileURL),

Prior to NSPersistentContainer, this would be done with Core Data Stack by:

    withModelName: "MyModel",
    withStoreURL: storeFileURL) { result in
        switch result {
        case .success(let stack):
            // Use your new stack

        case .failure(let error):
            //handle error ...


iOS 10.0 / macOS 10.12

  • Deprecated: The CoreDataStack class itself.
    • Replacement: Use Apple's NSPersistentContainer instead. The [Container Example](./Container Example/ demonstrates how to use NSPersistentContainer with the BNR Core Data Stack.
  • Deprecated: The CoreDataModelable protocol.
    • Replacement: Use the type method NSManagedObject.entity(). Many of the convenience methods formerly available on CoreDataModelable are now offered by BNR Core Data Stack as extension methods on NSManagedObject as FetchHelpers.
You can’t perform that action at this time.