SuperRecord an ActiveRecord implementation in Swift

All the media buzz around swift seems to be having some tangible effect. I won’t go into the opinionated slaw of Swift VS Objective-C VS Swift VS XYZ here :). Many of you know I freelance in the iOS space around London and beyond for SuperArmstrong and one of my recent clients asked me to work on a greenfield project to replace a very old wrapped web app they had. When we got down to the nitty gritties, one of their few requirements was that it should be written in Swift. My jaw did drop a little… considering this was about 20 days after Swift had first been publicly announced. After some conversation, we came to the mutual conclusion that they were brave.

Like many of the apps I work on, this project relied heavily on CoreData, as a convenience I decided i’d try out a library that I have a lot of respect for (even though its had its challenging moments) “MagicalRecord”, having only done organic CoreData for the past few years. As you probably know, Objective-C and Swift can sit alongside in a project and work in unison… however, not all the interoperability is 100% sound. I soon started to endure strange bugs and thanks to the incompleteness of Swift lldb support at the time (especially when mixing with Objective-C) these bugs soon became quite difficult to track down.

The most annoying was this:

let entityDescription = NSEntityDescription.entityForName("Pokemon", inManagedObjectContext: context)

Although harmless… this would actually fail when trying to insert an entity of that description into your managed object context. The culprit here? the NSString to String bridging (or vice versa).

To get around this bug (which I won’t go into too much detail) I began using:

let entityName = "Pokemon" as NSString
let entityDescription = NSEntityDescription.entityForName(entityName, inManagedObjectContext: context)

Performing a forced downcast to NSString. So great, now it works… However, many of the MagicalRecord finders and helpers I was using, would not have these forced downcasts as they came from the Objective-C world. I first forked MagicalRecord, after delving into the source-code, making many changes for better Swift support, fixing some threading irregularities I then realised I was putting a lot of work into making something work that had more functionality than I required at the time. So I embarked on making a Swift ActiveRecord style “companion” to CoreData.

The reason I say “companion” and not “wrapper” is that I didn’t want to abstract away CoreData too much or remove the power from the hands of the developer. I wanted to make the developer’s life easier, whilst maintaining their flexibility.

I’d much rather do something like this:

let pokemon = Pokemon.createNewEntity() as Pokemon

and avoid the above lines + more.

Thereby SuperRecord was born. The original goals for SuperRecord were simple.

  1. Give me the ActiveRecord style finders I crave, optimise them, keep my application level code tidy, but still performant.
  2. Rather than me typing out the same code in each project to handle batch updates on my UITableView and UICollectionView classes, have a special “one size fits all” class that will act as your NSFetchedResultsControllerDelegate, providing “safe” batch updated to your reusable views.
  3. Additionally, I didn’t wanna have to spend too much time creating NSFetchedResultsControllers all the time either, so I added some helpers for this too.
  4. Be written in Swift, keeping the public API’s simple and stable, but changing the implementation as Swift changed and moved with updates.

In late October 2014 whilst still very much a work in progress, I released the first public version and it was featured in the great iOS Dev Weekly newsletter. I decided to release it early as I saw a lot of discussion around CoreData and Swift and thought there’d be a lot of people interested in this OSS effort, so we could build up a good toolset as a community. I’m still the only maintainer… (not by choice) but its early days :).

Below is some extract from the README.md but I suggest you head over to the project on github for more information and feel free to checkout the demo project also on github which shows how to use the safe batched updates along with some other common tasks.

 

Core Files

  • NSManagedObjectExtension.swift This extension is responsible for most of the “finder” functionality and has operations such as deleteAll()findOrCreateWithAttribute()createEntity() and allows you to specify your own NSManagedObjectContext or use the default one (running on the main thread).
  • NSFetchedResultsControllerExtension.swift In constant development, this Extension allows the easy creation of FetchedResultsControllers for use with UICollectionView and UITableView that utilise the SuperFetchedResultsControllerDelegate for safe batch updates.
  • SuperFetchedResultsControllerDelegate.swift heavily inspired by past-projects i’ve worked on along with other popular open source projects. This handles safe batch updatesto UICollectionView and UITableView across iOS 7 and iOS 8. It can be used on its own with your NSFetchedResultsController or alternatively, its automatically used by the NSFetchedResultsControllerExtension methods included in SuperRecord.
  • SuperCoreDataStack.swift a boilerplate experimental main thread CoreData stack. Can be used either as a sqlite store or in memory store. Simply by calling SuperCoreDataStack.defaultStack() for SQLite or SuperCoreDataStack.inMemoryStack() for an in memory store. Of course you have access to your context .context / .saveContext()

Usage

Create a new Entity

Assuming you have an NSManagedObject of type “Pokemon” you could do the following

let pokemon = Pokemon.createNewEntity() as Pokemon

Please add @objc(className) above the class name of all your NSManagedObject subclasses (as shown in the demo project) for now. Better support will be coming in the future.

Creating an NSFetchedResultsController

This feature is currently in progress with basic support so far, in future versions, sorting and sectionNameKeyPath’s will be supported. Until then you can create your own NSFetchedResultsController, however, if you have no need for the above missing functionality then simply use

lazy var fetchedResultsController: NSFetchedResultsController = self.superFetchedResultsController()

func superFetchedResultsController() -> NSFetchedResultsController {
return NSFetchedResultsController.superFetchedResultsController("Pokemon", tableView: tableView)
}

With Pokemon being the entity name of your NSManagedObject.

Delete Entities

I’m planning on adding much more powerful functionality around Delete soon, such as deleteAllWithPredicate() or deleteEntity(), right now all that is available is

Pokemon.deleteAll()

Method Listing

This isn’t an exhaustive list of all methods and classes, however it includes some of the most useful ones.

  • NSManagedObjectExtension
  • findAllWithPredicate(predicate: NSPredicate!, context: NSManagedObjectContext) -> NSArray
  • findAllWithPredicate(predicate: NSPredicate!) -> NSArray
  • deleteAll(context: NSManagedObjectContext) -> Void
  • deleteAll() -> Void
  • findAll(context: NSManagedObjectContext) -> NSArray
  • findAll() -> NSArray
  • findFirstOrCreateWithPredicate(predicate: NSPredicate!) -> NSManagedObject
  • findFirstOrCreateWithPredicate(predicate: NSPredicate!, context: NSManagedObjectContext) -> NSManagedObject
  • createNewEntity() -> NSManagedObject
  • findFirstOrCreateWithAttribute(attribute: NSString!, value: NSString!, context: NSManagedObjectContext) -> NSManagedObject
  • findFirstOrCreateWithAttribute(attribute: NSString!, value: NSString!) -> NSManagedObject
  • NSFetchedResultsControllerExtension
  • superFetchedResultsController(entityName: NSString!, collectionView: UICollectionView) -> NSFetchedResultsController
  • superFetchedResultsController(entityName: NSString!, tableView: UITableView) -> NSFetchedResultsController

NSFetchedResultsControllers created using this method will automatically handle safe batch updates.

Developer Notes

This whole project is a work in progress, a learning exercise and has been released “early” so that it can be built and collaborated on with feedback from the community. I’m using it in a project I work on everyday, so hopefully it’ll improve and gain more functionality, thread-safety and error handling over time.

The next key things to be worked on are Optionality (as this has changed in every Swift BETA), the CoreDataStack, adding more finders with more functionality and improving the NSFetchedResultsControllerExtension.

 

 

 

Leave a Reply