Skip to content

mwager/VanillaStorage

gh-pages
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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

About

Simple key/value based client side storage abstraction lib using IndexedDB with fallback to WebSQL

Resources

Stars

Watchers

Forks

Packages

No packages published