The ability to access cookies has been a feature of JavaScript since, well, forever. Cookies are now obsolete for client-side storage (unless you need to support really old browser versions) but they can still be a useful mechanism for exchanging non-critical data between the server and client. Unfortunately, accessing cookies via document.cookie is simply horrible. UsefulJS.Storage presents a DOM storage-compatible interface to document.cookie that allows you to treat cookies as named key-value data stores. If you're unlucky enough to have to support a browser that does not offer storage, it can provide a fix to emulate both local storage and session storage using cookies.

If you are using cookies to provide client-side storage, note that the amount of data you can store in a cookie is several orders of magnitude less than in localstorage: ~1 KB compared to ~5 MB.
new UsefulJS.Storage(name[, props])

Throws: TypeError if name is anything other than a non-empty string.


The optional props parameter can have the following properties:

Static properties

Adds a storage entry to UsefulJS.featureSupport that allows for testing localStorage / sessionStorage support. Exposes the following properties:

DOMStorage interface

See the W3C documentation for more information.

Instance properties


Read-only property that reflects the number of items in the datastore.

This property is read-only in browsers that support Object.defineProperty. Otherwise it can be written to. Assigning a value to it doesn't change the underlying data.

Instance methods


Clears the store; the underlying cookie is removed



Retrieves an item from the data store


Returns String if the key exists in the store, otherwise returns null.


Retrieves a key name from the store at a given numeric index


Returns String if there is a key at the given index, otherwise returns null.


Removes an item from the data store



Stores an item in the data store; the value stored is coerced to a String if it is not a String

storage.setItem(key, value)


Stringifies the cookie data


Returns String


The returned string takes the form name=<ENCODED_VALUE> where "name" is the name of the data store and "<ENCODED_VALUE>" is the store data with URI-encoding applied. When the value is URI-decoded, it takes the same form as a query string: key1=value1&key2=value2.... Each key and value is individually URI-encoded.


// Load the user's high score
var score = 0, store = new UsefulJS.Storage(""), 
    hiScore = Number(store.getItem("hs"));

// If there's a new high score, persist it
if (score > hiScore) {
    store.setItem("hs", score);

Implementation notes

The storage specification says that an event should be issued to all open tabs that might be interested in the modified data. Well, that ain't going to happen.

Cookies may trivially be disabled by the browser user. If that is the case, values may be stored but they won't be persisted.

In Chrome (at least), cookies are not allowed with file:// URLs, which is handy when you're developing stuff locally. Can't quite see what security issue this restriction solves myself since native storage works just fine.


The fixes for the Storage module are defined in the _storage namespace of the fix options.


If, by some chance, your code is running in a browser that doesn't offer a native storage implementation, this fix will emulate window.localStorage using a cookie called UsefulJSLocalStorage. This fix will not be applied if storage has been disabled in browser settings. If is false and so is _storage.localStorage in the return Object from UsefulJS.fix, storage has probably been disabled either explicitly or as a side effect of private browsing.


If required, this fix emulates window.sessionStorage with a session cookie called UsefulJSSessionStorage.