I am now using LocalForage from Mozilla and so I will not maintain this code anymore.
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.
JSFiddle (Use chrome dev tools to inspect the stored IndexedDB data)
$ bower info vanilla-storage
$ bower install vanilla-storage
$ 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.
See dist/vanilla-storage.js
, or if you want to build it yourself:
$ grunt build # creates dist/vanilla-storage.js ready for production usage
- none (-;
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'
},
...
The API is all async and pretty simple, basically there are 5 public methods:
get(key, fn)
// fetch data for keygetAll(fn)
// fetch data for all keys ("all rows")save(key, data, fn)
// store data for keydrop(key, fn)
// drop data for keynuke(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.
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);
// 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);
});
// ...
}
});
}
$ 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
- search the repo for
TODO
... - create more advanced tests in more browsers
- see this https://developer.apple.com/library/ios/documentation/AppleApplications/Reference/SafariWebContent/Client-SideStorage/Client-SideStorage.html#//apple_ref/doc/uid/TP40002051-CH4-SW5