idb-kv-store

idb-kv-store

Simple key-value store backed by IndexedDB

idb-kv-store uses asynchronous operations to persist and retrieve key-value pairs from the underlying database. The idb-kv-store instance presents a much simpler api than IndexedDB, doesn't have the very limiting data size constraints of localStorage, and the persisted data is available between different instances, web sessions, and web workers.

Additionally, mutation events allow users to listen for database changes that occur in different instances, windows, or workers.

This module can be used with browserify or the idbkvstore.min.js script can be included which will attach IdbKvStore to window.

Usage

var store = new IdbKvStore('the name of store')

// Store the value 'def' at key 'abc'
store.set('abc', 'def', function (err) {
  store.get('abc', function (err, value) {
    console.log('key=abc  value=' + value)
  })
})

Promises are also supported!

store.get('abc').then(value => {
  console.log('key=abc  value=' + value)
})

Listen for database mutation events

store.on('add', change => {
  console.log('key=' + change.key, 'value=' + change.value)
})

// 'add' fails if the key already exists
someOtherStore.add('foo', 'bar')

API

store = new IdbKvStore(name, [opts], [cb])

Instantiates a new key-value store. name is the name of the database used to persist the data. So multiple Store instances with the same name will be sharing the same data.

cb(err) is called when the databases is opened. If the open was successful then err is null, otherwise err contains the error.

opts can have the following property:

• opts.channel - If the browser does not natively support BroadcastChannel then a custom implementation can be passed in.

store.set(key, value, [cb])

Stores the value at key; the value can be retrieved through store.get(key). When the store operation completes, cb is called with cb(err). err is null if the store was successful. If cb is undefined then a promise is returned instead. If the key already exists then the old value is replaced with the new one.

store.add([key], value, [cb])

The same as store.set(...) except if the key already exists, an error is returned in the callback.

Additionally, the key is optional. If left empty then an integer key will be automatically generated. Example: store.add('value')

store.get(key, [cb])

Retrieves the value at key. When the value is retrieved, cb is called with cb(err, value). If the retrieval was successful then err will be null. If cb is undefined then a promise is returned instead. If the key does not exist then undefined is returned as the value; no error is raised.

store.remove(key, [cb])

Removes the given key from the store and calls cb(err) upon completion. err is null if the removal was successful. If the key did not exist before the removal, the removal is still considered successful. If cb is undefined then a promise is returned.

store.clear([cb])

Removes all entries from the store, and calls cb(err) upon completion. err is null the clear was successful. If cb is undefined then a promise is returned.

store.keys([cb])

Retrieves the list of keys stored. When the list is retrieved, cb is called with cb(err, keys). If cb is undefined then a promise is returned.

store.values([cb])

Retrieves the list of values stored. When the list is retrieved, cb is called with cb(err, keys). If cb is undefined then a promise is returned.

store.json([cb])

Retrieves the entire key-value store as a json object. When the json representation has been retrieved, cb is called with cb(err, json). If cb is undefined, then a promise is returned.

store.count([cb])

Retrieves the number of entries in the store, and calls cb(err, count) upon retrieval. err is null if the count was successful, in which case count will hold the value. If cb is undefined, then a promise is returned.

store.close()

Closes the IndexedDB database and frees the internal resources. All subsequent calls to methods in store will throw errors.

IdbKvStore.INDEXEDDB_SUPPORT

Detects native IndexedDB support

IdbKvStore.BROADCAST_SUPPORT

Detects native BroadcastChannel support. If the BroadcastChannel api is not present then the mutation events will not be emitted.

Events

store.on('open', function () {})

Emitted when the database is open

store.on('add', function (change) {})

Emitted when another instance adds an item to the database by calling store.add(...). The change object has the following properties:

• change.method - always set to 'add'
• change.key - the key that value was added to
• change.value - the new value

See Supported Browsers for more info on which browsers support this event.

store.on('set', function (change) {})

Emitted when another instance sets the value of a key in the database by calling store.set(...). The change object has the following properties:

• change.method - always set to 'set'
• change.key - the key that value was set to
• change.value - the new value

See Supported Browsers for more info on which browsers support this event.

store.on('remove', function (change) {})

Emitted when another instance removes an item from the database by calling store.remove(...). The change object has the following properties:

• change.method - always set to 'remove'
• change.key - the key of the value that was removed

See Supported Browsers for more info on which browsers support this event.

store.on('close', function () {})

Emitted when the database is closed

store.on('error', function (err) {})

Emitted if any unhandled error occures.

Supported Browsers

idb-kv-store supports all browsers that have implemented the IndexedDB api. However, the mutation events, add/set/remove, are only available in browsers that have implemented the BroadcastChannel api. Attempting to listen on a add/set/remove event in a browser that does not support the BroadcastChannel api will cause an error to be emitted. IdbKvStore.BROADCAST_SUPPORT will indicate if the browser supports this api.

The list of browsers that support BroadcastChannels can be found on caniuse.com

License

MIT. Copyright (c) Austin Middleton.