README_en.md

WebStorageCache

WebStorageCache extends HTML5 localStorage and sessionStorage with adding time expires and object serialization.It's easy to set timeout for the cache data and also can save a JSON Object directly.
optimize: While access a time expires cache data, WebStorageCache will clean it immediately.On the other hand manually invoke wsCache.deleteAllExpires(); can also delete all the time expires cache data.

Usage

Download the latest WebStorageCache from GitHub.

npm

npm install web-storage-cache -save-dev

To use WebStorageCache, just drop a single JavaScript file into your page:

<script src="src/web-storage-cache.js"></script>
<script>
// create WebStorageCache instance.
var wsCache = new WebStorageCache();
// cache 'wqteam' at 'username', expired in 100 seconds
wsCache.set('username', 'wqteam', {exp : 100});
</script>

You can also use WebStorageCache with RequireJS:

define(['web-storage-cache'], function(WebStorageCache) {
    // create WebStorageCache instance.
    var wsCache = new WebStorageCache();
    // cache 'wqteam' at 'username', expired in 100 seconds
    wsCache.set('username', 'wqteam', {exp : 100});
});

Demo

var wsCache = new WebStorageCache();

// cache 'wqteam' at 'username', expired in 100 seconds
wsCache.set('username', 'wqteam', {exp : 100});

// deadline in  nextYear
var nextYear = new Date();
nextYear.setFullYear(nextYear.getFullYear() + 1);
wsCache.set('username', 'wqteam', {exp : nextYear});

// get 'username'
wsCache.get('username');

// cache an object literal - default uses JSON.stringify under the hood
wsCache.set('user', { name: 'Wu', organization: 'wqteam'});

// Get the cache object - default uses JSON.parse under the hood
var user = wsCache.get('user');
alert(user.name + ' belongs to ' + user.organization);

// delete 'username'
wsCache.delete('username');

// manually delete all expires CacheItem. return deleted key's array.
wsCache.deleteAllExpires();

// Clear all keys
wsCache.clear();

// Set a new expiration time for an existing key.
wsCache.touch('username',  1);

// Add key-value item to cache, success only when the key is not exists in cache
wsCache.add('username2', 'wqteam', {exp : 1});

// Replace the key's data item in cache, success only when the key's data item is exists in cache.
wsCache.replace('username', 'new wqteam', {exp : 1});

// check if the 'storage' supported by the user browser. if it`s not supported by the user browser all the  WebStorageCache API methods will do noting.
wsCache.isSupported();

API

Constructor

var wsCache = new WebStorageCache({
    // [option] 'localStorage', 'sessionStorage', window.localStorage, window.sessionStorage or
    // other storage instance implement [Storage API].
    // default 'localStorage'.
    storage: 'localStorage',
    // [option] //An expiration time, in seconds. default never .
    exp: Infinity
});

isSupported

Check if the Storage API be supported by the browser.

wsCache.isSupported(); // return Boolean.

set

Set a new CacheItem to storage.

wsCache.set(key, value, options);

get

Get a cached item by key.

wsCache.get(key);

delete

Delete a cached item by 'key'.

wsCache.delete(key);

deleteAllExpires

Delete all expired items.

wsCache.deleteAllExpires();

clear

Delete all items in the storage, not only save by wsCache.

wsCache.clear();

touch

Set a new expire time for the cache item.

wsCache.touch(key, exp: 1);

add

add a new cache item to the storage,success only when the key is not exists.

wsCache.add(key, value, options);

replace

Replace the key's cache item in storage,success only when the key's data item is exists in memcached.

wsCache.replace(key, value, options);