focalStorage

focalStorage is a Promise-based, localStorage-like wrapper around asynchronous IndexedDB storage.

focalStorage works wherever IndexedDB is supported. localStorage fallback coming soon.

To use focalStorage, just drop a single JavaScript file into your page:

<script src="focalStorage.js"></script>
<script>focalStorage.getItem('something', myCallback);</script>

Download the latest focalStorage from GitHub, or install with npm:

npm install focalStorage

focalStorage is compatible with browserify.

How to use focalStorage

Because focalStorage uses async storage, it has an async API. It's otherwise exactly the same as the Local Storage API.

focalStorage relies on native ES6 Promises (polyfilled by Babel, where unsupported).

Don't expect a return value from calls to focalStorage.getItem(). Instead, use Promises:

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

// Async, fast, and non-blocking!
focalStorage.setItem('key', 'value').then(function (value) {
  console.log(value + ' was set!');
}, function (error) {
  console.error(error);
});

Configuration

You can set database information with the focalStorage.config method. Available options are driver, name, version, and storeName.

Example:

focalStorage.config({
  driver: focalStorage.INDEXEDDB,  // Force IndexedDB. Or `focalStorage.INDEXEDDB` for localStorage.
  name: 'myApp',
  version: 1.0,
  storeName: 'keyvaluepairs',  // Limit to alphanumeric characters and underscores.
});

Note: you must call config() before you interact with your data. This means calling config() before using getItem(), getItems(), setItem(), removeItem(), clear(), key(), keys() or length().

Working on focalStorage

You'll need Node + npm.

To work on focalStorage, you should start by forking it and installing its dependencies. Replace USERNAME with your GitHub username and run the following:

git clone git@github.com:USERNAME/focalStorage.git
cd focalStorage
npm install

Building the bundle

Run this command to compile the JavaScript as a standalone module to dist/focalStorage.js:

npm run build

Maintainers

Run this command to publish a new tag to GitHub and version to npm:

npm run release

Licence

This program is free software and is distributed under an MIT License.