DOMCached

Introduction | Download | Test | Documentation | Compatibility | Usage | Methods | To-do list

Introduction

DOMCached is a simple wrapper library for the use of DOM Storage provided by the modern browsers. The library is designed after the hugely popular memcached caching system, providing similar "caching" options in JavaScript in the form of local storage.

While the original DOM Storage provides only methods to save and read string values, DOMCached can input and output any JSON compatible objects. DOMCached includes also support for namespaces and data expiring.

DOMCached comes in two versions - as a module which requires Prototype (prototypejs.org) and in the for of a jQuery plugin. When using DOMCached as the jQuery plugin, then jquery-json plugin is also needed, since jQuery doesn't provide methods to decode/encode JSON strings.

© 2009 Andris Reinman, FlyCom - andris.reinman@gmail.com

Download

DOMCached is licenced under a MIT-style licence.

Test

This is the Prototype version. To test the jQuery plugin, use this demo instead.

Refresh the browser page or navigate away and back to see if the saved values survive the transition.

Documentation

Compatibility

DOMCached can be used in any browser in the form that where it doesn't work no cache hits will ever occur.

Usage

With Prototype:

<script src="prototype.js"></script>
<script src="domcached.js"></script>
<script>
//Lets try to read some data from DOMCached
var value = DOMCached.get("key");
if(!value){
	//If there wasn't a cache hit, lets load the data from the server...
 	value = load_data_from_server()
 	// ...and try to set the cache for future requests
	DOMCached.set("key",value);
}
</script>

As the jQuery plugin:

<script src="jquery.js"></script>
<script src="jquery-json.js"></script>
<script src="domcached.js"></script>
<script>
//Lets try to read some data from DOMCached
var value = $.DOMCached.get("key");
if(!value){
	//If there wasn't a cache hit, lets load the data from the server...
 	value = load_data_from_server()
 	// ...and try to set the cache for future requests
	$.DOMCached.set("key",value);
}
</script>

Available methods

• set(key, value, time=false, namespace='default')

  Sets a key's value, regardless of previous contents in cache.

  key - Key to set. If this value is not set or not a string an exception is raised.

  value - Value to set. This can be any value that is JSON compatible (Numbers, Strings, Objects etc.).

  time - Optional expiration time, either relative number of milliseconds from current time, or an absolute Unix epoch time in milliseconds.

  namespace - An optional namespace for the key. This must be string, otherwise an exception is raised.

  Method returns the used value or true if saved value was false

• get(key, namespace='default')

  Looks up a key in cache

  key - Key to look up. If this value is not string an exception is raised.

  namespace - An optional namespace for the key. This must be string, otherwise an exception is raised.

  Method returns the key value or if not found

• deleteKey(key, namespace=None) (former delete)

  Deletes a key from cache.

  key - Key to delete. If this value is not string an exception is raised.

  namespace - An optional namespace for the key. This must be string, otherwise an exception is raised.

  Method returns true

• add(key, value, time=false, namespace='default')

  Sets a key's value, if and only if the item is not already in cache.

  key - Key to set. If this value is not set or not a string an exception is raised.

  value - Value to set. This can be any value that is JSON compatible (Numbers, Strings, Objects etc.).

  time - Optional expiration time, either relative number of milliseconds from current time, or an absolute Unix epoch time in milliseconds.

  namespace - An optional namespace for the key. This must be string, otherwise an exception is raised.

  Method returns the used value or false if the key was already used

• replace(key, value, time=false, namespace='default')

  Replaces a key's value, failing if item isn't already in cache.

  key - Key to set. If this value is not set or not a string an exception is raised.

  value - Value to set. This can be any value that is JSON compatible (Numbers, Strings, Objects etc.).

  time - Optional expiration time, either relative number of milliseconds from current time, or an absolute Unix epoch time in milliseconds.

  namespace - An optional namespace for the key. This must be string, otherwise an exception is raised.

  Method returns the used value or false if the key was already used

• incr(key, delta=1, namespace=None, initial_value=None)

  Automically increments a key's value.

  key - Key to increment. If this value is not set or not a string an exception is raised.

  delta - Numric value to increment key by, defaulting to 1.

  namespace - An optional namespace for the key. This must be string, otherwise an exception is raised.

  initial_value - An initial value to be used if the key does not yet exist in the cache. Ignored if the key already exists.

  Method returns the new value

• decr(key, delta=1, namespace=None, initial_value=None)

  Automically decrements a key's value.

  key - Key to decrement. If this value is not set or not a string an exception is raised.

  delta - Numric value to decrement key by, defaulting to 1.

  namespace - An optional namespace for the key. This must be string, otherwise an exception is raised.

  initial_value - An initial value to be used if the key does not yet exist in the cache. Ignored if the key already exists.

  Method returns the new value

• flush_all()

  Deletes everything in cache.

  Method returns true

To-do list

• openDatabase support. Safari 3 doesn't support DOM storage but it has a fully functional SQL database (SQLite) embedded inside which can be used as a local storage mechanism for DOMCached.
  Might not be happen since Safari 4 has been widely adopted.
• Tests. There's currently no unit tests to confirm if the library is working or not.
• Code review. There's a lot of optimization to do inside the code.