Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/alekseykulikov/storage

Asynchronous browser storage with multiple back-ends (IndexedDB, WebSQL, localStorage)
https://github.com/alekseykulikov/storage

indexeddb localforage localstorage websql

Last synced: about 2 months ago
JSON representation

Asynchronous browser storage with multiple back-ends (IndexedDB, WebSQL, localStorage)

Awesome Lists containing this project

README 

        
# Storage [![Build Status](https://travis-ci.org/alekseykulikov/storage.png?branch=master)](https://travis-ci.org/alekseykulikov/storage)



  Storage is a functional wrapper around [localForage](https://github.com/mozilla/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](https://github.com/yields/store)

  - development mode



## Installation



```

$ npm install asyncstorage --save

$ bower install storage

$ component install alekseykulikov/storage

```



  Standalone build available as [./dist/storage.js](./dist/storage.js).



```html



window.storage('key', fn);

```



## Example



```js

// 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](https://github.com/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](https://hacks.mozilla.org/2014/02/localforage-offline-storage-improved/).



### 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.



```js

// 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`.



```js

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`.



```js

storage.forage.config({ name: 'my-name' });

if (!window.indexedDB) storage.forage.setDriver(storage.forage.LOCALSTORAGE);



storage.forage.keys().then(function(keys) {

  console.log(keys);

});

```