Welcome To NanoStore

What is NanoStore?

NanoStore is an open source, lightweight schema-less local key-value document store written in Objective-C for Mac OS X and iOS.

Relational databases tend to have a rich understanding of the structure of your data, but requires some planing beforehand and some level of maintenance as well. NanoStore provides the flexibility that comes with key-value document stores, but still understands something about your data. Because the data is key-value based, it can be accessed quickly and can grow as much as needed... all without ever worrying about the schema.

Main advantages

• No SQL knowledge required
• Schema-less
• Key-value based storage
• Store your own custom objects
• Bags, a free-form relational system
• Fast, direct object manipulation
• Dynamic queries
• Full index support, inner-objects, embedded arrays and dictionaries
• Convenience methods to access, manipulate and maintain SQLite databases
• Full SQLite access available
• Mac OS X Mountain Lion 10.8 and iOS 6 ready
• iOS library runs on the device and simulator
• ARC compliant

Latest changes

v2.5 - January 1, 2013

• Starting with v2.5, the plist mechanism has been replaced with NSKeyedArchiver. There are several reasons for it: it's more compact, faster and uses less memory. Perhaps the most important reason is that it opens the possibility to store other data types.

• NSNull is now supported. Big thanks to Wanny (https://github.com/mrwanny) for taking the time to improve this section of NanoStore.

Installation

Building NanoStore is very easy. Just follow these steps:

1) Download NanoStore
2) Open the NanoStore.xcodeproj file
3) Select Universal > My Mac 64-bit or 32-bit from the Scheme popup
4) Build (Command-B)

Now you should have a new Distribution directory within the NanoStore project directory which contains the Universal static library (armv6/armv7/i386) as well as the header files. To add it in your project, do the following:

1) Drag the Distribution directory to the Project Navigator panel
2) Include #import "NanoStore.h" in your code

Usage example:

#import "NanoStore.h"

@implementation MyDemoAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // Override point for customization after application launch.
    // Instantiate a NanoStore and open it
    
    NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFMemoryStoreType path:nil error:nil];
    ...

Note

If you want to add a dependency between your project and NanoStore so that it gets automatically rebuilt when
you update NanoStore, do the following (we'll assume your app is called "MyDemoApp"):

1) Select the MyDemoApp project in the Project Navigator
2) Select the MyDemoApp target
3) Expand the Target Dependencies box
4) Click "+" and add NanoStore
				

How does NanoStore work?

The basic unit of data in NanoStore is called NanoObject. A NanoObject is any object which conforms to the NSFNanoObjectProtocol protocol.

At its core, a NanoObject is nothing more than a wrapper around two properties:

• A dictionary which contains the metadata (provided by the developer)
• A key (UUID) that identifies the object (provided by NanoStore)

The dictionary must be serializable, which means that only the following data types are allowed:

• NSArray
• NSDictionary
• NSString
• NSData (*)
• NSDate
• NSNumber

Note

(*) The data type NSData is allowed, but it will be excluded from the indexing process.

To save and retrieve objects from the document store, NanoStore moves the data around by encapsulating it in NanoObjects. In order to store the objects in NanoStore the developer has three options:

• Use the NSFNanoObject class directly
• Expand your custom classes by inheriting from NSFNanoObject
• Expand your custom classes by implementing the NSFNanoObjectProtocol protocol

Regardless of the route you decide to take, NanoStore will be able to store and retrieve objects from the document store seamlessly. The beauty of this system is that NanoStore returns the object as it was stored, that is, instantiating an object of the class that was originally stored.

Note

If the document store is opened by another application that doesn't implement the object that was stored, NanoStore
will instantiate a NSFNanoObject instead, thus allowing the app to retrieve the data seamlessly. If the object is then
updated by this application, the original class name will be honored.

Example

App A stores an object of class Car.
App B retrieves the object, but since it doesn't know anything about the class Car, NanoStore returns a NSFNanoObject.
App B updates the object, with additional information. NanoStore saves it as a Car, not as a NSFNanoObject.
App A retrieves the updated object as a Car object, in exactly the same format as it was originally stored.

Types of Document Stores

There are three types of document stores available in NanoStore: in-memory, temporary and file-based. These document stores are defined by the NSFNanoStoreType type:

NSFMemoryStoreType

Create the transient backing store in RAM. Its contents are lost when the process exits. Fastest, uses more RAM (*).

NSFTemporaryStoreType

Create a transient temporary backing store on disk. Its contents are lost when the process exits. Slower, uses less
RAM than NSFMemoryStoreType.

NSFPersistentStoreType

Create a persistent backing store on disk. Slower, uses less RAM than NSFMemoryStoreType (*).

Note

Until the limit set by NSFNanoEngine's - (NSUInteger)cacheSize has been reached, memory usage would be the same for
in-memory and on-disk stores. When the size of the store grows beyond - (NSUInteger)cacheSize in-memory stores start to
consume more memory than on-disk ones, because it has nowhere to push pages out of the cache.

Typically, most developers may want to create and open the document store. To do that, use the following method:

+ (NSFNanoStore *)createAndOpenStoreWithType:(NSFNanoStoreType)aType path:(NSString *)aPath error:(out NSError **)outError

Example

// Instantiate an in-memory document store and open it. The path parameter is unused.
NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFMemoryStoreType path:nil error:nil];

// Instantiate a temporary document store and open it. The path parameter is unused.
NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFTemporaryStoreType path:nil error:nil];

// Instantiate a file-based document store and open it. The path parameter must be specified.
NSString *thePath = @"~/Desktop/myDatabase.database";
NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFPersistentStoreType path:thePath error:nil];

Note

In the case of file-based document stores, the file gets created automatically if it doesn't exist and then opened. If
it already exists, it gets opened and made available for use right away. There are instances where you may want to
fine-tune the engine. Tuning the engine has to be performed before the document store is opened. Another method is
available in NSFNanoStore for this purpose:

+ (NSFNanoStore *)createStoreWithType:(NSFNanoStoreType)theType path:(NSString *)thePath.

Example

// Instantiate a file-based document store but don't open it right away. The path parameter must be specified.
NSString *thePath = @"~/Desktop/myDatabase.database";
NSFNanoStore *nanoStore = [NSFNanoStore createStoreWithType:NSFPersistentStoreType path:thePath error:nil];

// Obtain the engine
NSFNanoEngine *nanoStoreEngine = [nanoStore nanoStoreEngine];

// Set the synchronous mode setting
[nanoStoreEngine setSynchronousMode:SynchronousModeOff];
[nanoStoreEngine setEncodingType:NSFEncodingUTF16];

// Open the document store
[nanoStore openWithError:nil];

Note

Check the section Performance Tips below for important information about how to get the most out of NanoStore.

Working with a NanoObject

There are three basic operations that NanoStore can perform with a NanoObject:

• Add it to the document store
• Update an existing object in the document store
• Remove it from the document store

To add an object, instantiate a NSFNanoObject, populate it and add it to the document store.

Example

// Instantiate a NanoStore and open it
NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFMemoryStoreType path:nil error:nil];

// Generate an empty NanoObject
NSFNanoObject *object = [NSFNanoObject nanoObject];

// Add some data
[object setObject:@"Doe" forKey:@"kLastName"];
[object setObject:@"John" forKey:@"kFirstName"];
[object setObject:[NSArray arrayWithObjects:@"jdoe@foo.com", @"jdoe@bar.com", nil] forKey:@"kEmails"];

// Add it to the document store
[nanoStore addObject:object error:nil];

// Close the document store
[nanoStore closeWithError:nil];

Alternatively, you can instantiate a NanoObject providing a dictionary via:

+ (NSFNanoObject*)nanoObjectWithDictionary:(NSDictionary *)theDictionary

NanoStore will assign a UUID automatically when the NanoObject is instantiated. This means that requesting the key from the NanoObject will return a valid UUID. The same holds true for objects that inherit from NSFNanoObject. However, classes that implement the NSFNanoObjectProtocol protocol should make sure they return a valid key via:

- (NSString *)nanoObjectKey

Warning

If an attempt is made to add or remove an object without a valid key, an exception of type NSFNanoObjectBehaviorException
will be raised. To update an object, simply modify the object and add it to the document stor