localforage

What is localforage?

The localForage npm package is a fast and simple storage library for JavaScript. It improves the offline experience of web apps by using asynchronous storage (IndexedDB or WebSQL) with a simple, localStorage-like API. localForage uses a driver system that supports IndexedDB, WebSQL, and localStorage.

What are localforage's main functionalities?

Storing Data

This feature allows you to store data in the browser's asynchronous storage. The code sample demonstrates setting and then getting an item.

localforage.setItem('key', 'value').then(function () { return localforage.getItem('key'); }).then(function (value) { console.log(value); }).catch(function (err) { console.error(err); });

Retrieving Data

This feature allows you to retrieve data from the browser's asynchronous storage. The code sample demonstrates getting an item.

localforage.getItem('key').then(function (value) { console.log(value); }).catch(function (err) { console.error(err); });

Removing Data

This feature allows you to remove data from the browser's asynchronous storage. The code sample demonstrates removing an item.

localforage.removeItem('key').then(function () { console.log('Key is removed'); }).catch(function (err) { console.error(err); });

Clearing Storage

This feature allows you to clear all data from the browser's asynchronous storage. The code sample demonstrates clearing the storage.

localforage.clear().then(function () { console.log('Storage is now empty'); }).catch(function (err) { console.error(err); });

Iterating Over Keys

This feature allows you to iterate over all key-value pairs in the browser's asynchronous storage. The code sample demonstrates iterating over keys.

localforage.iterate(function (value, key, iterationNumber) { console.log([key, value]); }).then(function () { console.log('Iteration has completed'); }).catch(function (err) { console.error(err); });

Other packages similar to localforage

dexie

Dexie is a wrapper library for indexedDB, which is a low-level API for client-side storage of significant amounts of structured data. Dexie provides a more powerful query language than localForage and is designed to work with complex data structures.

pouchdb

PouchDB is an open-source JavaScript database inspired by Apache CouchDB that is designed to run well within the browser. PouchDB was created to help web developers build applications that work as well offline as they do online. It is more feature-rich than localForage, with synchronization capabilities.

idb-keyval

idb-keyval is a super-simple-small promise-based keyval store implemented with IndexedDB, providing a localStorage-like API. It is much smaller in size than localForage but does not have the same level of browser support or features.

README

localForage

localForage is a handy library that improves the offline experience of your web app by using asynchronous storage (via IndexedDB or WebSQL where available) but with a simple, localStorage-like API.

localForage includes a localStorage-backed fallback store for browsers with no IndexedDB or WebSQL support. This means that asynchronous storage is available in Chrome, Firefox, and Safari (including Safari Mobile).

Browser Support

All of 'em. Worst-case localStorage fallback will be used, but asynchronous storage will be used for:

• Android Browser (2.1+)
• Blackberry (7+)
• Chrome (23+)
• Chrome for Android (32+)
• Firefox (10+)
• Firefox for Android (25+)
• IE (10+)
• IE Mobile (10+)
• Opera (15+)
• Opera Mobile (11+)
• Phonegap/Apache Cordova (1.2.0+)
• Safari (3.1+)

Note that, because of WebSQL support, apps packaged with Phonegap will also use asynchronous storage. Pretty slick!

Support

Lost? Need help? This README has some simple guides and the code has decent documentation, but I'm working on a real API guide. In the meantime, if you're stuck using the library, running the tests, or want to contribute, you can visit irc.mozilla.org and head to the #apps channel to ask questions about localForage.

How to use localForage

Callbacks

Because localForage uses async storage, it has an async API. It's otherwise exactly the same as the localStorage API.

// In localStorage, we would do:
localStorage.setItem('key', JSON.stringify('value'));
doSomethingElse();

// With localForage, we use callbacks:
localforage.setItem('key', 'value', doSomethingElse);

Similarly, please don't expect a return value from calls to localforage.getItem(). Instead, use a callback:

// Synchronous; slower!
var value = JSON.parse(localStorage.getItem('key'));
alert(value);

// Async, fast, and non-blocking!
localforage.getItem('key', alert);

You can store any type in localForage; you aren't limited to strings like in localStorage. Even if localStorage is your storage backend, localForage automatically does JSON.parse() and JSON.stringify() when getting/setting values.

Promises

Promises are pretty cool! If you'd rather use promises than callbacks, localForage supports that too:

function doSomethingElse(value) {
    console.log(value);
}

// With localForage, we allow promises:
localforage.setItem('key', 'value').then(doSomethingElse);

localForage relies on native ES6 Promises, but ships with an awesome polyfill for browsers that don't yet support ES6 Promises natively.

Driver Selection (i.e. forcing localStorage)

For development, it can be easier to use the slower--but easier to debug--localStorage driver (mostly because localStorage can easily be inspected from the console). You can use the setDriver() method to change the driver localForage is using at any time.

// If you aren't using JS modules, things are loaded synchronously.
localforage.setDriver('localStorageWrapper');
alert(localforage.driver);
  => 'localStorageWrapper'

// If you're using modules, things load asynchronously, so you should use
// callbacks or promises to ensure things have loaded.
localforage.setDriver('localStorageWrapper', function() {
    alert(localforage.driver);
});
  => 'localStorageWrapper'

// The promises version:
localforage.setDriver('localStorageWrapper').then(function() {
    alert(localforage.driver);
});
  => 'localStorageWrapper'

You can actually force any available driver with this method, but given that the best driver will be selected automatically when the library is loaded, this method is mostly useful in forcing localStorage.

Note that trying to load a driver unavailable on the current browser (like trying to load WebSQL in Gecko) will fail and the previously loaded "best choice" will continue to be used.

Backbone.js

localForage includes a Backbone.js storage library that you can use to store your Backbone collections offline with only a few lines of really simple code.

Of course, Backbone.js is entirely optional and you can use localForage without it!

Running Tests

localForage is designed to run in the browser, so the tests explicitly require a browser environment instead of any JavaScript environment (i.e. node.js). The tests are run on both a headless WebKit (using PhantomJS) and "headless" Gecko (using SlimerJS). The tests are written using CasperJS's tester module. We run tests against Gecko and WebKit to ensure that IndexedDB and WebSQL support is functioning as-expected.

On OS X, you'll need to install both PhantomJS and SlimerJS like so:

brew install phantomjs slimerjs

Generally you'll need a version of Firefox or XULRunner installed for SlimerJS to run your tests. Once everything is installed you can simply type make test to make sure the code is working as expected.

TODO: Provide Windows/Linux instructions; check into XULRunner setup.

License

This program is free software; it is distributed under an Apache License.

---

Copyright (c) 2013-2014 Mozilla (Contributors).