Simple key/value based client side storage abstraction lib using IndexedDB with fallback to WebSQL
JavaScript
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bower_components
dist
src
test
utils
.gitignore
.jshintignore
.jshintrc
.phantomjsrc
.travis.yml
Gruntfile.js
bower.json
index.html
package.json
phantomjs_tests.js
readme.md
testem.yml

readme.md

VanillaStorage.js

Deprecated Warning!

I am now using LocalForage from Mozilla and so I will not maintain this code anymore.









Build Status

Run the tests in your browser

Watch the tests on saucelabs

Simple key/value based storage abstraction lib for usage in browser based environments. Uses IndexedDB with fallback to [deprecated but still widely supported and needed] WebSQL. If none of both storage adapters is available or the initialization fails, the ready-callback will be called with an error as the first parameter.

Demo

JSFiddle (Use chrome dev tools to inspect the stored IndexedDB data)

Installation

Via bower

$ bower info vanilla-storage
$ bower install vanilla-storage

From source

$ git clone https://github.com/mwager/VanillaStorage.git
$ cd VanillaStorage
$ npm install && bower install
$ grunt test

Note that gh-pages is the default branch to make sure to update the project site and tests on every push (see this tweet). That's why we commit the bower_components too.

Optimized source

See dist/vanilla-storage.js, or if you want to build it yourself:

$ grunt build # creates dist/vanilla-storage.js ready for production usage

Dependencies

  • none (-;

Global vs. AMD

Either include the files via script tags:

<script src="path/to/vanilla-storage/src/storageHelpers.js"></script>
<script src="path/to/vanilla-storage/src/WebSQLStorage.js"></script>
<script src="path/to/vanilla-storage/src/IDBStorage.js"></script>
<script src="path/to/vanilla-storage/src/VanillaStorage.js"></script>

...or add something like the following to your requirejs config:

...
    paths: {
        VanillaStorage: 'path/to/src/VanillaStorage',
        WebSQLStorage:  'path/to/src/WebSQLStorage',
        IDBStorage:     'path/to/src/IDBStorage',
        storageHelpers: 'path/to/src/storageHelpers'
    },
...

Usage

The API is all async and pretty simple, basically there are 5 public methods:

  • get(key, fn) // fetch data for key
  • getAll(fn) // fetch data for all keys ("all rows")
  • save(key, data, fn) // store data for key
  • drop(key, fn) // drop data for key
  • nuke(fn) // drop data for all keys ("all rows")

Callback functions always have the error as first parameter, data as second if any. So if the first parameter of a callback is undefined it means the operation was successful.

Examples

Default usage

var options = {
        storeName: 'my_data_store', // name of the store ("name of database")
        version: '1.0' // string for websql, on idb we parseInt
    },
    vanilla,
    KEY       = 'some-key',
    DEMO_DATA = {foo: 'bar', num:42};

// vanilla api ready to use
var readyToUseAPI = function(err) {
    console.log(err, this); // -> this instanceof VanillaStorage

    this.save(KEY, DEMO_DATA, function _saved(err) {
        console.log(err); // should be undefined

        vanilla.get(KEY, function _fetched(err, data) {
            console.log(data); // -> DEMO_DATA

            vanilla.drop(KEY, function _deleted_(err) {
                // calling get(KEY) now should have the error passed with message not found
            });
        });
    });
};

// pre-checks possible:
console.log(VanillaStorage.isValid('websql-storage'))
console.log(VanillaStorage.isValid('indexeddb-storage'))

// NOTE: you must provide a `ready`-calback
vanilla = new VanillaStorage(options, readyToUseAPI);

Standalone usage

// you can also use the adapters standalone
var wsql = new WebSQLStorage({
    storeName: 'my_store',
    version: '1.0'
});
console.log(wsql.isValid());

wsql.init(function ready(err) {
    if(!err) {
        wsql.save('some-key', {foo:'bar'}, function __saved(err, data) {
            console.log(err, data);
        });
        // ...
    }
});

var idb = new IDBStorage({
    storeName: 'my_data_store',
    version: 1.0
});
if(idb.isValid()) {
    idb.init(function ready(err) {
        if(!err) {
            idb.save('some-key', {foo:'bar'}, function __saved(err, data) {
                console.log(err, data);
            });
            // ...
        }
    });
}

Testing

$ grunt test

# or:
$ grunt test-server&
$ phantomjs --debug=false --local-storage-path=. --local-storage-quota=100000000000??? ./node_modules/mocha-phantomjs/lib/mocha-phantomjs.coffee http://localhost:1234/test

Run the suite in real browsers via testem:

$ grunt testem

TODOs