jStorage - store data locally with JavaScript

jStorage is a simple wrapper plugin for Prototype, MooTools and jQuery to cache data (string, numbers, objects, even XML nodes) on browser side. Note that functions, DOM nodes, host objects and such can not be saved.

jStorage was first developed under the name of DOMCached but since a lot of features were dropped to make it simpler (like the support for namespaces and such) it was renamed. DOMCached had separate files for working with Prototype and jQuery but jStorage can handle both in one go.

1. Basics

jStorage makes use of HTML5 local storage where available and userData behavior in Internet Explorer older versions. Webkit SQLite is not supported.

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 2 kB when minified (under 1kB 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 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. Either way, the syntax stays the same.

set(key, value)

$.jStorage.set(key, value)

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.

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.

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 (for example if you have reasons to believe that the data has been altered in another tab etc.)

storageAvailable()

$.jStorage.storageAvailable()

Returns true if storage is available

6. Usage example

This example uses Prototype library

<script src="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>

7. Issues

Why no Webkit SQLite API support?
WebKit SQLite - although being a fantastic API and definitely part of the future of the web - doesn't add much value to jStorage. SQLite API would only broaden support to Safari 3 (which is now more or less outdated anyway) since Safari 3 doesn't contain support for localStorage. The problem with SQLite API is that it's really slow (in terms of milliseconds, not as in hours) but jStorage is designed to be usable as soon as jstorage.js is loaded. SQLite API calls run in separate threads so when jstorage.js is loaded and an application tries to make uso of it already, then the data might not be available yet, since the SQLite thread hadn't finished its job.
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.

8. How to use non-supported libraries

jStorage is written in plain JavaScript and it requires a library (jQuery, Prototype, MooTools) for JSON encoding/decoding purposes only. If you have your own JSON implementation then you might want to skip the usage of an external library altogether.

<script>
$ = {
	toJSON   : your_json_encoder,
	evalJSON : your_json_decoder
}
</script>
<script src="jstorage.js"></script>
<script>alert($.jStorage.get("key"));</script>

NB! json2.js support is also included - but in this case you still need to define the dollar $ object (but no methods of it), since $ is required by the script.

<script src="json2.js"></script>
<script>
$ = {}
</script>
<script src="jstorage.js"></script>
<script>alert($.jStorage.get("key"));</script>

9. Contact and Copyright

© 2010 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.