jStorage - store data locally with JavaScript

jStorage is a cross-browser key-value store database to store data locally in the browser - jStorage supports all major browsers, both in desktop (yes - even Internet Explorer 6) and in mobile.

Additionally jStorage is library agnostic, it works well with any other JavaScript library on the same webpage, be it jQuery, Prototype, MooTools or something else. Though you still need to have either a third party library (Prototype, MooTools) or JSON2 on the page to support older IE versions.

jStorage supports storing Strings, Numbers, JavaScript objects, Arrays and even native XML nodes. jStorage also supports setting TTL values for auto expiring stored keys and - best of all - notifying other tabs/windows when a key has been changed or publishing/subscribing to events from the same or another tab/window, which makes jStorage also a local PubSub platform for web applications.

jStorage is pretty small, about 7kB when minified and 4kB gzipped.

Donate

Support jStorage development

1. Basics

jStorage makes use of HTML5 local storage where available and userData behavior in Internet Explorer older versions.

Current availability: jStorage supports all major browsers - Internet Explorer 6+, Firefox 2+, Safari 4+, Chrome 4+, Opera 10.50+

If the browser doesn't support data caching, then no exceptions are raised - jStorage can still be used by the script but nothing is actually stored.

jStorage is really small, just about 7kB when minified (4kB when gzipped)!

2. Download

jStorage can be downloaded at github (direct download link)

3. Interactive test

Add some values and refresh the page - if your browser supports storing local data, then the values should survive the page refresh.

KEY	VALUE
		ADD
	Clicking "GET" alerts the value for provided key with the method $.jStorage.get(key)	GET
	Clear all saved data	FLUSH

Test Publish/Subscribe

Test this functionality with a specific library

Unit tests

4. Browser support

Browser	Storage support	Survives browser restart	Survives browser crash	Storage size
Chrome 4	+	+	+	5 MB
Firefox 3.6	+	+	+	5 MB
Firefox 3	+	+	+	5 MB
Firefox 2	+	+	+	5 MB
IE8	+	+	+	10 MB
IE7	+	+	+	128 kB
IE6	+	+	+	128 kB
Opera 10.50	+	+	-	5 MB
Opera 10.10	-	N/A	N/A	N/A
Safari 4	+	+	+	5 MB
Iphone Safari	+	+	+	5 MB
Safari 3	-	N/A	N/A	N/A

5. Usage

jStorage requires Prototype, MooTools or jQuery + jQuery-JSON or JSON2. Either way, the syntax stays the same.

Simple setup to support jStorage with JSON2

<script src="//cdnjs.cloudflare.com/ajax/libs/json2/20110223/json2.js"></script>
<script src="https://raw.github.com/andris9/jStorage/master/jstorage.js"></script>
<script> /* $.jStorage is now available */ </script>

Setup with jQuery2

<script src="//cdnjs.cloudflare.com/ajax/libs/json2/20110223/json2.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.8.0/jquery.min.js"></script>
<script src="https://raw.github.com/andris9/jStorage/master/jstorage.js"></script>
<script> /* $.jStorage is now available */ </script>

6. Function reference

set(key, value[, options])

$.jStorage.set(key, value, options)

Saves a value to local storage. key needs to be string otherwise an exception is thrown. value can be any JSONeable value, including objects and arrays or a XML node.
Currently XML nodes can't be nested inside other objects: $.jStorage.set("xml", xml_node) is OK but $.jStorage.set("xml", {xml: xml_node}) is not.

Options is an optional options object. Currently only available option is options.TTL which can be used to set the TTL value to the key ($.jStorage.set(key, value, {TTL: 1000});). NB - if no TTL option value has been set, any currently used TTL value for the key will be removed.

get(key[, default])

value = $.jStorage.get(key)
value = $.jStorage.get(key, "default value")

get retrieves the value if key exists, or default if it doesn't. key needs to be string otherwise an exception is thrown. default can be any value.

deleteKey(key)

$.jStorage.deleteKey(key)

Removes a key from the storage. key needs to be string otherwise an exception is thrown.

setTTL(key, ttl)

$.jStorage.set("mykey", "keyvalue");
$.jStorage.setTTL("mykey", 3000); // expires in 3 seconds

Sets a TTL (in milliseconds) for an existing key. Use 0 or negative value to clear TTL.

getTTL(key)

ttl = $.jStorage.getTTL("mykey"); // TTL in milliseconds or 0

Gets remaining TTL (in milliseconds) for a key or 0 if not TTL has been set.

flush()

$.jStorage.flush()

Clears the cache.

index()

$.jStorage.index()

Returns all the keys currently in use as an array.
var index = $.jStorage.index();
console.log(index); // ["key1","key2","key3"]

storageSize()

$.jStorage.storageSize()

Returns the size of the stored data in bytes

currentBackend()

$.jStorage.currentBackend()

Returns the storage engine currently in use or false if none

reInit()

$.jStorage.reInit()

Reloads the data from browser storage

storageAvailable()

$.jStorage.storageAvailable()

Returns true if storage is available

subscribe(channel, callback)

$.jStorage.subscribe("ch1", function(channel, payload){
    console.log(payload+ " from " + channel);
});

Subscribes to a Publish/Subscribe channel (see demo)

publish(channel, payload)

$.jStorage.publish("ch1", "data");

Publishes payload to a Publish/Subscribe channel (see demo)

listenKeyChange(key, callback)

$.jStorage.listenKeyChange("mykey", function(key, action){
    console.log(key + " has been " + action);
});

Listens for updates for selected key. NB! even updates made in other windows/tabs are reflected, so this feature can also be used for some kind of publish/subscribe service.

stopListening(key[, callback])

$.jStorage.stopListening("mykey"); // cancel all listeners for "mykey" change

Stops listening for key change. If callback is set, only the used callback will be cleared, otherwise all listeners will be dropped.

7. Usage example

jQuery

jQuery doesn't come with built in JSON encoder/decoder so if you need to support IE6/IE7 you should include one yourselt like in the example

<script src="//cdnjs.cloudflare.com/ajax/libs/json2/20110223/json2.js"></script>
<script src="//code.jquery.com/jquery-1.9.1.min.js"></script>
<script src="jstorage.js"></script>
<script>
// Check if "key" exists in the storage
var value = $.jStorage.get("key");
if(!value){
	// if not - load the data from the server
 	value = load_data_from_server()
 	// and save it
	$.jStorage.set("key",value);
}
</script>

Prototype

<script src="//ajax.googleapis.com/ajax/libs/prototype/1.7.1.0/prototype.js"></script>
<script src="jstorage.js"></script>
<script>
// Check if "key" exists in the storage
var value = $.jStorage.get("key");
if(!value){
	// if not - load the data from the server
 	value = load_data_from_server()
 	// and save it
	$.jStorage.set("key",value);
}
</script>

8. Issues

Why would you want to use jStorage when cookies work already in every browser?
Cookies are not meant to save large quantities of data locally - they are meant to pass around ID values to keep track of users. Internet Explorer allows to use up to 20 cookies per domain with the payload of 4kB per cookie. It isn't very much, especially considering the need to chunk larger data into smaller bits. The fact that the data (max. 80 kB) is sent to the server with *every* call doesn't sound much of a good idea either.

9. Contact and Copyright

© 2010 - 2012 Andris Reinman, andris.reinman@gmail.com
jStorage is licensed under MIT-styled license, so basically you can do whatever you want to do with it.