Distributable files can be found under releases.
webStorage is a minimal Javascript library that improves the way you work with localStorage or sessionStorage.
The API methods below deal with getting and setting data in an offline store.
getItem(key)Gets an item from an offline store. If the key does not exist, getItem() will return null.
setItem(key, value)Saves an item to an offline store. You can store the following types of JavaScript objects:
- String
- Number
- Array
- Object
removeItem(key)Removes the value of a key from the offline store.
clear([clearAll])Use this method with caution.
If clearAll is set to true, removes every key from the storage, returning it to a blank slate.
If clearAll is set to false or any other falsy value it will remove only the keys that belong to the specific databse.
keys()Gets the list of all keys in the offline storage for a specific database.
length()Gets the number of keys in the datastore.
iterate(iteratorCallback)Iterate over all value/key pairs in datastore.
iteratorCallback is called once for each pair, with the following arguments:
- key
- value
- iterationNumber (one-based number)
You can early exit from iterator by returning false inside iteratorCallback.
quota()Approximately display the size for each key in datastore and the total size of all keys in MB.
supported()Checks if the driver of choice (localStorage or sessionStorage) is supported by the browser.
config(options)Set and persist webStorage options. This must be called before any other calls to webStorage are made. The following options can be set:
| Option | Type | Description | Default value |
|---|---|---|---|
| driver | Object |
The preferred driver to use. Use one between localStorage and sessionStorage. |
localStorage |
| name | String |
The name of the database. This is used as prefix for all keys stored in the offline storage. | webStorage |
createInstance([options])Creates a new instance of the webStorage. The options can be the same as config(options).
var users = [
{id: 1, name: 'John Doe', email: '[email protected]'},
{id: 2, name: 'George Cooper', email: '[email protected]'},
{id: 2, name: 'Tim Smith', email: '[email protected]'}
];
var companies = ['Google', 'Yahoo', 'Microsoft', 'Mozilla'];
/* Saving some items with the default configuration */
webStorage.setItem('user', users[0]);
webStorage.setItem('company', companies[0]);
/* Create a new instance and save some items */
var ls = webStorage.createInstance({
name: 'MyApp'
});
ls.setItem('user', users[1]);
ls.setItem('company', companies[2]);
ls.setItem('dummyKey', 100);
/* Retrieving saved items */
webStorage.getItem('user'); // => Object { id: 1, name: "John Doe", email: "[email protected]" }
webStorage.getItem('company'); // => "Google"
ls.getItem('user'); // => Object { id: 2, name: "George Cooper", email: "[email protected]" }
ls.getItem('company'); // => "Microsoft"
/* Get length of datastores */
webStorage.length(); // => 2
ls.length(); // => 3
/* Get datastores' keys */
webStorage.keys(); // => Array [ "company", "user" ]
ls.keys(); // => Array [ "dummyKey", "company", "user" ]
/* Itereate over datastores */
ls.iterate(function (key, value, iterNum) {
console.log(iterNum, ':', key, ':', value);
});
// => 1 : dummyKey : 100
// => 2 : company : Microsoft
// => 3 : user : Object { id: 2, name: "George Cooper", email: "[email protected]" }
/* Quota */
ls.quota();
// => Object { "total": 0.0001430511474609375, "items": { "MyApp/dummyKey": 0.0000057220458984375, "MyApp/company": 0.0000209808349609375, "MyApp/user": 0.0001163482666015625 } }"
/* Removing items */
webStorage.removeItem('user');
webStorage.length(); // => 1
webStorage.keys(); // => Array [ "company" ]
ls.length(); // => 3 (still same as before)
ls.clear(); /* Clear only the "MyApp" datastore */
ls.length(); // => 0
ls.keys(); // => Array []
webStorage.length(); // => 1
ls.clear(true); /* Flush away everything in localStorage */
webStorage.length(); // => 0$ npm install webStorage$ git clone https://github.com/georapbox/webStorage.git$ cd webStorage
$ npm install$ npm run buildThe command above will create a dist/ folder that contains the library to be used in production. It will also lint the code and run the tests.