README.md

JavaScript LRU Cache

Just a simple LRU cache written in javascript. It is loosely based on ASP.NET's Cache, and includes many caching options such as absolute expiration, sliding expiration, cache priority, and a callback function. It can be used to cache data locally in the user's browser, saving a server roundtrip in AJAX heavy applications.

How It Works

	// Create a new cache item
	// The constructor accepts an optional integer
	// parameter which places a limit on how many
	// items the cache holds
	var cache = new Cache();

	// add an item to the cache
	// parameters: key - the key to refer to the object
	//             value - the object to cache
	//             options - an optional parameter described below
	// the last parameter accepts an object which controls various caching options:
	//      expirationAbsolute: the datetime when the item should expire
	//      expirationSliding: an integer representing the seconds since
	//                         the last cache access after which the item
	//                         should expire
	//      priority: How important it is to leave this item in the cache.
	//                You can use the values Cache.Priority.LOW, .NORMAL, or
	//                .HIGH, or you can just use an integer.  Note that
	//                placing a priority on an item does not guarantee
	//                it will remain in cache.  It can still be purged if
	//                an expiration is hit, or if the cache is full.
	//      callback: A function that gets called when the item is purged
	//                from cache.  The key and value of the removed item
	//                are passed as parameters to the callback function.
	cache.setItem("A", "1", {expirationAbsolute: null,
	                         expirationSliding: 60,
	                         priority: Cache.Priority.HIGH,
	                         callback: function(k, v) { alert('removed ' + k); }
	                        });

	// retrieve an item from the cache
	// takes one parameter, the key to retreive
	// returns the cached item
	cache.getItem("A");

	// Remove and return an item from the cache.
	// If the item doesn't exist it returns null.
	cache.removeItem("A");
	
	// Removes items from the cache which pass the provided test.
	// If the test function returns true, the item will be removed.
	// E.g., Remove keys which start with 'RemoveMe'
	cache.removeWhere(function(k, v) { return /^RemoveMe/.test(k); });

	// Returns the number of items in the cache.
	cache.size();

	// Return stats about the cache, like {"hits": 1, "misses": 4}
	cache.stats();

	// clears all items from the cache
	cache.clear();

LocalStorage Persistance

You can have the cache persist its values to localStorage on browsers that support it. To do this simply create the cache with a different storage backend like:

var cache = new Cache(-1, false, new Cache.LocalStorageCacheStorage());

All values have to be JSON stringifiable, which means the callback option to setItem won't work.

If you want to have multiple independent caches, pass in a namespace argument, like:

var cache = new Cache(-1, false, new Cache.LocalStorageCacheStorage('myNameSpace'));

If -1 is used for the cache size, the cache will be limited to the size of localStorage, which is currently 5MB on Chrome/Safari.

History

• 4/16/2013: Thanks to Nick Young for AMD module support and the removeWhere() method.
• 11/29/2011: Thanks to Andrew Carman for tests, pluggable backends, localStorage persistance, and bug fixes.
• 1/8/2011: Migrated project to GitHub.
• 1/20/2010: Thanks to Andrej Arn for some syntax updates.
• 5/30/2008: First version.