Usage

Including the idbstore.js file will add an IDBStore constructor to the global scope.

Alternatively, you can use an AMD loader such as RequireJS, or a CommonJS loader to load the module, and you will receive the constructor in your load callback (the constructor will then, of course, have whatever name you call it).

You can then create an IDB store:

var myStore = new IDBStore();

You may pass two parameters to the constructor: the first is an object with optional parameters, the second is a function reference to a function that is called when the store is ready to use.

The options object may contain the following properties (default values are shown -- all properties are optional):

{
  storeName: 'Store',
  storePrefix: 'IDBWrapper-',
  dbVersion: 1,
  keyPath: 'id',
  autoIncrement: true,
  indexes: [],
  implementationPreference: [
    'indexedDB',
    'webkitIndexedDB',
    'mozIndexedDB',
    'shimIndexedDB'
  ],
  onStoreReady: function(){},
  onError: function(error){ throw error; }
}

storeName is the name of the store: for different stores, use different names.

storePrefix is an additional prefix; the created database will finally have the name "storePrefix+storeName". You can safely ignore this property, but if you want to have full control over the IDB name, you can pass your own prefix.

dbVersion is the version number of your store. You'll only have to provide this if you change the structure of the store at a later time.

keyPath is the name of the property to be used as key index. If autoIncrement is set to true, the database will automatically add a unique key to the keyPath index when storing objects missing that property. If you want to use out-of-line keys, you must set this property to null (see below for details on out-of-line keys).

autoIncrement is a boolean and toggles, well, auto-increment on or off. You can leave it to true, even if you do provide your own ids.

indexes is an array of objects defining indexes (see the Indexes page for details).

implementationPreference is an array of strings containing the implementations to check for availability.

onError gets called if an error occurred while trying to open the store. It receives the error instance as only argument.

As an alternative to passing a ready handler as second argument, you can also pass it in the 'onStoreReady' property. If a callback is provided both as second parameter and inside of the options object, the function passed as second parameter will be used.

Out-of-line Keys

IDBWrapper supports working with out-of-line keys. This is a feature of IndexedDB, and it means that an object's identifier is not kept on the object itself. Usually, you'll want to go with the default way, using in-line keys. If you, however, want to use out-of-line keys, note that the put() and batch() methods behave differently, and that the autoIncrement property has no effect – you MUST take care of the ids yourself!

Defining implementation preference, a.k.a. Make IDBWrapper Use the Shim

In certain situations you will want IDBWrapper to prefer a specific IndexedDB implementation. E.g. if you build an iOS app with Cordova, and you want to outgo Safari's buggy implementation, you want to make IDBWrapper use the shim instead of the native impl. To do so, you can change the implementation preference in the constructor (in this example, we tell IDBWrapper to just use the shim):

var myStore = new IDBStore({
  storeName: 'my-ios-store',
  implementationPreference: ['shimIndexedDB'] // thx Apple
});