Asynchronous browser storage with multiple back-ends (IndexedDB, WebSQL, localStorage)
Clone or download
Latest commit 7ce45bc Mar 14, 2015
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist 1.5.0 release Mar 14, 2015
lib remove local version of localForage Nov 26, 2014
test update dev deps Mar 14, 2015
.gitignore fix Readme (there's less difference with localForage now) Nov 26, 2014
.travis.yml add .travis.yml config May 26, 2014
History.md 1.5.0 release Mar 14, 2015
LICENSE Create LICENSE Mar 14, 2015
Readme.md docs Mar 14, 2015
bower.json 1.5.0 release Mar 14, 2015
component.json 1.5.0 release Mar 14, 2015
package.json 1.5.0 release Mar 14, 2015

Readme.md

Storage Build Status

Storage is a functional wrapper around localForage. That means it's an asynchronous browser storage with multiple back-ends (IndexedDB, WebSQL, localStorage), which is built for a better offline experience.

The main differences with localForage:

  • batch get/set support
  • callbacks or promises
  • browserify friendly
  • simple API inspired by yields/store
  • development mode

Installation

$ npm install asyncstorage --save
$ bower install storage
$ component install alekseykulikov/storage

Standalone build available as ./dist/storage.js.

<script src="storage.js"></script>
<script>window.storage('key', fn);</script>

Example

// set
storage({ key: 'val', key2: 'val2'}, function(err) {});

// get
storage('key', function(err, val) {});
storage(['key', 'key2'], function(err, all) {}); // all.length == 2

// count
storage(function(err, count) {}); // count == 2

// delete
storage('key', null, function(err) {});
storage(['key', 'key2'], null, function(err) {});

API

Each method returns promise, and accepts optional callback.

storage([key, val, fn])

Main function is facade to get/set/del/count methods. It's inspired by yields/store. Setting a key to null is equivalent to deleting the key via storage.del(key).

storage.get(key, [fn])

Get key value.

storage.get([key1, key2, ..., keyn], [fn])

Get group of values. Callbacks return array of values for each key. If key does not exist, it returns null on this position.

storage.set(key, val, [fn])

Set key to val. You can store any kind of data, including blobs.

storage.set({ key1: val1, key2: val2, key3: val3 }, [fn])

Run a batch operation. Simple way to create, update, remove multiple records. Use null to remove record.

// assume we have 2 records
storage.set('foo', 7, fn)
storage.set('bar', ['one', 'two', 'three'], fn);

storage.set({
  baz: 'val' // create new val
  foo: 1000, // update `foo` value
  bar: null, // remove `bar`
}, function(err) {});

storage.del(key, [fn])

Delete key.

storage.del([key1, key2, ..., keyn], [fn])

Delete a group of keys in one request.

storage.clear()

Clear storage.

storage.count()

Count records.

storage.development

Work with async code console can be unpleasant. Setup development flag and storage will console.log() results of get or count.

storage.development = true;
storage.set({ foo: 1, bar: 2 });
storage.get(['foo', 'bar']);
// => [1 ,2]
storage.del('bar');
storage.count();
// => 1
// shortcut to: storage.count().then(console.log.bind(console));

storage.forage

It gives you access to the localForage instance. You can use it to configure backend or for advanced methods as keys or iterate.

storage.forage.config({ name: 'my-name' });
if (!window.indexedDB) storage.forage.setDriver(storage.forage.LOCALSTORAGE);

storage.forage.keys().then(function(keys) {
  console.log(keys);
});