quipu [kee-poo, kwip-oo]: Sometimes called talking knots, were recording devices historically used in the region of Andean South America. A system also used for collecting data and keeping records, ranging from monitoring tax obligations, properly collecting census records, calendrical information, and military organization.

Kipu eases your every day job of parsing a JSON response and getting it into Core Data. It uses a convention over configuration paradigm to facilitate your workflow.

• Handles operations in safe background threads
• Thread safe saving, we handle retrieving and storing objects in the right threads
• Diffing of changes, updated, inserted and deleted objects (which are automatically purged for you)
• Auto-mapping of relationships (one-to-one, one-to-many and many-to-many)
• Smart-updates, only updates your NSManagedObjects if the server values are different (useful when using NSFetchedResultsController delegates)
• Uniquing, Core Data does this based on objectIDs, we use your remote key (such as id) for this

Interface

+ (void)processChanges:(NSArray *)changes
       usingEntityName:(NSString *)entityName
             dataStack:(DATAStack *)dataStack
            completion:(void (^)(NSError *error))completion

• changes: JSON response
• entityName: Core Data's Model Entity Name (such as User, Note, Task)
• dataStack: Your DATAStack

Real World Example

Model

JSON

[
  {
    "id": 6,
    "name": "Shawn Merrill",
    "email": "[email protected]",
    "created_at": "2014-02-14T04:30:10+00:00",
    "updated_at": "2014-02-17T10:01:12+00:00",
    "notes": [
      {
        "id": 0,
        "text": "Shawn Merril's diary, episode 1",
        "created_at": "2014-03-11T19:11:00+00:00",
        "updated_at": "2014-04-18T22:01:00+00:00"
      }
    ]
  }
]

Kipu

[Kipu processChanges:JSON
     usingEntityName:@"User"
           dataStack:dataStack
          completion:^{
              // Objects saved in Core Data, do something
           }];

(You can see another example here).

PROFIT!

Requirements

iOS 7 or above, DATAStack Core Data stack

Components

Kipu wouldn't be possible without the help of this fully tested components:

• DATAStack: Core Data stack and thread safe saving

• NSManagedObject-ANDYMapChanges: Helps you purge deleted objects, internally we use it to diff inserts, updates and deletes. Also it's used for uniquing Core Data does this based on objectIDs, ANDYMapChanges uses your remote keys (such as id) for this

• NSManagedObject-HYPPropertyMapper: Maps JSON fields with their Core Data counterparts, it does most of it's job using the paradigm "convention over configuration"

Getting Started

Installation

Kipu is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'Kipu', '~> 0.4'

DATAStack

Replace your Core Data stack with an instance of DATAStack:

- (void)applicationWillTerminate:(UIApplication *)application
{
    [self.dataStack persistWithCompletion:nil];
}

NSManagedObject-HYPPropertyMapper

Your Core Data models should match your backend entities, your classes can have a different name. Your fields should match their JSON counterparts. For example first_name maps to firstName, address to address.

There are only two exceptions to this rule:

• ids should match remoteID
• created_at and updated_at should match createdDate and updatedDate

Networking

You are free to use any networking library or NSURLConnection.

Finally

You are ready to go, check the example project that uses App.net for how to use Kipu.

Author

Elvis Nuñez, [email protected]

License

Kipu is available under the MIT license. See the LICENSE file for more info.