nanoidb

IndexedDB is a web-api for client-side storage, and although widely used, the API
itself is at times confusing. Nanoidb is small wrapper to help standardize most
useful methods in a callback based fashion.

IndexedDB is an async transactional database that lets you store objects as
<key, value> pairs. The pairs get stored in object stores that are
essentially a set of database tables, but in an indexedDB context.

Usage

var db = Nanoidb('catStore', 1)
db.on('upgrade', function (diffData) {
  diffData.db.createObjectStore('catStore')
})
db.on('open', function (stores) {
  putOp(stores.catStore)
  function putOp (store) {
    stores.catStore.put('key-12345', 'ChashuCat', function (err) {
      if (err) throw err
      console.log('put done')
      batchOp(stores.catStore)
      getOp(stores.catStore)
      getAllOp(stores.catStore)
    })
  }
  function getAllOp (store) {
    store.getAll('dang', 10, function (err, values) {
      if (err) throw err
      values.forEach(function (value) {
        console.log('new value', value)
      }) 
    })
  }
  function getOp (store) {
    store.get('key-12345', function (err, val) {
      if (err) throw err
      console.log('get value', val)
      deleteOp(store)
    })
  }
  function deleteOp (store) {
    store.del('catStore', function (err) {
      if (err) throw err
      console.log('deleted')
      batchOp(store)
    })
  }
  function batchOp (store) {
    store.batch()
      .put('coolThang', 'hell yea')
      .put('dang', 'no wayyy')
      .put('ding', 'whoaaa yea')
      .del('ding')
      .flush(function (err) {
        if (err) throw err
        console.log('it flushed successfully')
      })
  }
})

API

db = Nanoidb(name, version)

This creates an instance of IndexedDB. It takes in a database name and
version. IndexedDB’s versioning starts with 1, rather than 0.

db.upgrade(version)

Upgrades the current version of Nanoidb with the specified version. This is
useful for when you need to create an extra object store under the same
Nanoidb instance.

db.on('upgrade', callback(diffData))

Returns an object composed of a previously created indexedDB and a
IDBVersionChangeEvent. This is where you should create your object store by
calling diffData.db.createObjectStore('<name>').

diffData.event provides you with an oldVersion property to help with
schema updates.

db.on('open', callback(stores))

Returns an instance of an object store that you can later use.

db.on('error', callback(error))

Returns an IndexedDB error object. This event will be sent when IndexedDB runs
into an error creating a database.

store = stores.<name>

Instance of an Object Store.

store.put(key, val, callback(err))

Given the Object Store you previously created, you can add a value to the
database via the put method. Takes an object key, val, and an error
callback.

store.get(key, callback(err, val))

You can also get a value from the database with a get. Takes a key and an
error callback.

store.getAll([query, count], callback(err, val))

Get all records in a given store. Can optionally take a query
key or
range, as well as a count for values to be returned if there are duplicates.
Will return all records if neither query nor count are provided.

store.del(key, callback(err))

Delete method takes a key and an error callback.

batch = store.batch()

You can also batch chain del and get methods. When you’re done, you have to
call a .flush() to handle your callback.

batch.put(key, val)

Add an object within a batch operation. Takes a key and a val.

batch.del(key)

Delete an object within a batch operation. Takes a key.

batch.flush(callback(err))

When working with a batch() method, you have to call a flush to handle your
errors. This just takes an error callback.

Install

npm install nanoidb

Related content

• choo
• mdn/IndexedDB

License

MIT