UsefulJS.Storage

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.

Syntax

new UsefulJS.Storage(name[, props])

Parameters

name String
The name of the data store.
props Object
Cookie properties to control expiry and suchlike.

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

Description

The optional props parameter can have the following properties:

lifetime: how long (in days) the cookie is valid for; defaults to 365; if no explicit lifetime is set, the expiry time will be updated when the store is updated. If a lifetime of 0 is set, a session cookie will be created
domain: the domain (such as example.com) that the cookie should be served to; defaults to null.
path: expressed as an absolute path; cookies will be only be served to URLs when the cookie path is a prefix of the URL path; defaults to "/"
secure: if true, the cookie will only be served over secure HTTPS connections; defaults to false.

Static properties

UsefulJS.featureSupport.storage

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

cookies

Whether cookies are enabled.
local

Whether localStorage is supported and enabled.
session

sessionStorage is supported and enabled.

DOMStorage interface

See the W3C documentation for more information.

Instance properties

length

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

clear

Clears the store; the underlying cookie is removed

Syntax

storage.clear()

getItem

Retrieves an item from the data store

Syntax

storage.getItem(key)

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

key

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

Syntax

storage.key(index)

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

removeItem

Removes an item from the data store

Syntax

storage.removeItem(key)

setItem

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

Syntax

storage.setItem(key, value)

toString

Stringifies the cookie data

Syntax

storage.toString()

Returns String

Description

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.

Example

// Load the user's high score
var score = 0, store = new UsefulJS.Storage("my.game.data"), 
    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.

Fixes

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

localStorage

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 UsefulJS.featureSupport.storage.local 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.

sessionStorage

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