Storer.js - HTML5 Web Storage for Any Browser

Originally written for Viafoura by Shahyar G, released for public consumption by Viafoura, Inc.

Introduction

Storer.js is a fallback-reliant, HTML5 Storage-based storage system. It implements a completely cross-browser-compatible system with implementations of localStorage, sessionStorage, cookieStorage, and memoryStorage.

All of its storage subsystems implement getItem, setItem, removeItem, clear, key, and length, as the HTML5 Web Storage specification is written. However, there are some enhancements on these methods, and slight deviations from it with memoryStorage and cookieStorage.

Usage

initStorer is called, takes a callback function, which will return the storage subsystems. Why? This is necessary because the Internet Explorer 7- fallback for localStorage is userData, which needs to be able to insert an element into the document before proceeding. On any modern (or non-IE7) browser, the callback function is triggered synchronously and immediately. There is no delay at all in this scenario. domReady or jQuery is required for userData functionality in IE7 or lower.

In a worst-case scenario, all of the storages are memoryStorage, which means the data will not persist across pages. In a best-case scenario, each of the storage types are implemented using native sessionStorage and localStorage with cookie support as well with cookieStorage.

Light Version (IE8+ only)

Storer-light.min.js has userData and window.name support removed, reducing the minified filesize by approximately 40%. If you do not need IE6 or IE7 support, this version will enable you to still retain the other fallbacks (cookie and memory). This version does not require using the callback function (see example below "using return"). It WILL work in those browsers, however, localStorage will fall back to cookies, and sessionStorage will fall back to memory.

Examples

Using callback and a custom prefix (callback supports IE7 and lower):

initStorer(function (Storer) {
    cookieStorage  = Storer.cookieStorage;
    memoryStorage  = Storer.memoryStorage;
    sessionStorage = Storer.sessionStorage;
    localStorage   = Storer.localStorage;
}, { 'prefix': '_MyStorage_' });

// Set some stuff
Storer.memoryStorage.setItem('falsey', 0);
Storer.localStorage.setItem('this_expires', "in 10 seconds", 10);

Using return (return does not support localStorage in IE7; best to use the Light version in this scenario):

var Storer = initStorer();
//...

Arguments for initStorer

initStorer([Function callback[, Object params]]);

Function callback(Object Storer)

The callback function to call once the storage has been initialized. In most modern browsers, it is called synchronously. In older versions of IE that require the use of userData for localStorage, it is triggered asynchronously once the page has loaded.

It returns an Object called Storer, which contains cookieStorage, localStorage, memoryStorage, and sessionStorage.

Object params

{
    prefix:             String='' // automatic key prefix for sessionStorage and localStorage
    default_domain:     String='' // default domain for cookies
    default_path:       String='' // default path for cookies
    no_cookie_fallback: Boolean=false // set to true to disable cookieStorage fallback for localStorage

Any storage expiry support with setItem(key, value, end)

As of 0.1.0, all storage subsystems implement an expiry time with the end argument. If not set, it expires normally for that given storage type (eg. stays permanently for localStorage).

As int, it is assumed to be the number of seconds from now. As String, it is assumed to be a Date string, unless it is a numeric string over 4 characters long, in which case it is assumed a local timestamp. As a Date object, it will use the object's UTC string.

cookieStorage global argument

cookieStorage also supports an additional 'global' Boolean argument on all of its methods, allowing you to escape out of the 'prefix' defined, so that you may use it to fetch general cookies as well.

Important notice regarding dependencies

For Internet Explorer 7 and lower, initStorer requires a function called domReady, or uses jQuery(document).ready if available. If no function is found, localStorage will silently fail and is not usable in old IE browsers. domReady is included in the dependencies subdirectory of this repository. (In a future revision, this functionality may fall back to cookieStorage when no such function is present.)

How it works

It piggybacks on the real HTML5 storage when available, and creates the additional functionality of being able to prepend a 'prefix' to all key names automatically (see initStorer params). This is useful for projects where you would like to use Storage without worrying about name collisions.

It always returns every type of storage, and falls back to others, as listed below. In the worst-case scenario, all the storage subsystems are instances of memoryStorage, which means no persistance is available, but that no code will break while performing actions on the current page.

The fallbacks are as follows:

localStorage   = localStorage   || userData    || cookieStorage || memoryStorage;
sessionStorage = sessionStorage || window.name || memoryStorage;
cookieStorage  = cookieStorage  || memoryStorage;
memoryStorage  = memoryStorage;

License

Creative Commons Attribution 3.0 Unported (CC BY 3.0). http://creativecommons.org/licenses/by/3.0/ It's free. All we ask is that you maintain the @copyright and @author comments in the code. Nothing else is necessary.

Addendum

Here is a cat. =^.^= His name is Frisbee.

-- Copyright (c) 2011 Viafoura, Inc.