localForage is a key-value store for browsers

localForage — offline key/value store for browsers

localForage is a project started at Mozilla for the purpose of providing a stable, simple key/value store API on top of various offline storage options available in modern browsers: IndexedDB, WebSQL, or localStorage.

Pretty much every storage option in modern browsers has drawbacks:

  1. localStorage is slow, synchronous, and works only with strings.
  2. IndexedDB has a very verbose API, and Safari only recently started supporting it (not without bugs).
  3. WebSQL requires writing SQL, is non-standard and dying.

When all you need is set some values for some keys, use localForage to avoid these shortcomings: it has the interface similar to localStorage, except that it’s asynchronous, supports many different data types (you can store not only strings, but also objects, typed arrays, etc.), and powered by the most suitable storage engine for the current browser (most likely, IndexedDB).

Installing localForage

localForage is available from bower: bower install localforage. You can also download it manually.

To use it, simply include localforage.min.js on your page. There’s also localforage.nopromises.min.js, which doesn’t include Promises shim, so that you can use it if your project already includes some sort of Promises/A+ library.

Using localForage to store data

You can use localForage functions with callbacks or promises.

Example with callbacks. Setting items:

localforage.setItem('key', 'value', function(err, value) {
  if (err)
    console.error(err);
  else    
    console.log('Set value ', value);
});

Getting items:

localforage.getItem('key', function(err, value) {
  if (err)
    console.error(err);
  else
    console.log('Got value', value);
});

Example with ES6 Promises:

localforage.setItem('key', 'value').then(function(value) {
  console.log(value);
});

To remove a stored item, call removeItem. To remove all items, call clear.

In addition to setting, getting, and removing items, localForage can iterate over them:

localforage.iterate(function(value, key) {
    console.log([key, value]);
}, function() {
    console.log('finished iterating');
});

You can also get all keys by calling keys.

Configuring localForage

Using setDriver function you can bypass automatic storage detection, and use the particular backend (supported: IndexedDB, WebSQL, localStorage). You can also write your own driver (storage backend).

By calling config you can also set the order of preference for drivers, database name, etc.

Conclusion

LocalForage is an nice abstraction library that you can use to implement simple offline storage in your browser apps. It uses the fastest backend available, provides async API, and an ability to iterate over stored keys. Give it a try!

Source code and license

Project site: https://mozilla.github.io/localForage/
GitHub: https://github.com/mozilla/localForage
Authors: Mozilla
License: Apache License 2.0

Leave a Reply

Your email address will not be published. Required fields are marked *