#TDPBrowserCache

##Version Master: v0.1.4

##Semver This project aims to maintain the semver version numbering scheme.

##Changelog See the changelog file

##Overview TDPBrowserCache is a very simple javascript library which provides in-browser data caching via a localStorage backend (falling back to an in-memory storage backend if the browser doesn't support localStorage)

##Features

• Cache any javascript data type (except functions) e.g. strings, numbers, objects, arrays (if it is JSON.stringify() and JSON.parse()-able then you can store it)
• Namespacing to help prevent collisions
• Small codebase - ~2kiB minified, single file
• Very fast, usually <1ms for a get() and a set() (on common hardware) - much faster than requesting data from a remote source
• In-browser caching for any javascript data types except functions
• Super simple to use (simple instantiator returns and object with getter, setter and purger methods)
• localStorage backend, falling back automatically to in-memory storage if localStorage is not supported (this will not persist across page loads but will still help for single page apps or those with repetetive requests)
• Support for TTLs for each stored object
• Support for cache purge (via the purge() method)
• (Runtime defineable) Automatic namespacing to prevent localStorage key collisions
• (Runtime defineable) override of localStorage backend

##Requirements None - there are no dependencies, this is vanilla JS

##Installation

npm install TDPBrowserCache
# or
git clone https://github.com/neilstuartcraig/TDPBrowserCache.git

##Usage

<script type="text/javascript" src="/path/to/TDPBrowserCache.min.js"></script>
<script type="text/javascript">
    var cache=new TDPBrowserCache();
    cache.set("someKey", {some:"data",more:"data"}, 86400); // Cache a key (named "someKey") whose value is an object ({some:"data",more:"data"}) for 1 day
    cache.get("someKey"); // {some:"data",more:"data"}
    cache.purge("someKey"); // Purge the cached object from the cache
</script>

##Configuration Configuration is virtually zero though you can pass a few options in to the constructor if you wish:

• preferLocalStorage: Boolean (default true) - whether or not to use localStorage (as opposed to the fallback of in-memory storage).
• keyNamespace: String (default "__BC_") - the namespace (a prefix for the key name). This is aimed at preventing key name collisions

##Public methods

###set(key, value[, ttl])

#####Overview The cache setter.

####Arguments

• key: string - the key name under which to store the cached data
• value: mixed (not function) - the value to cache. This can be any javascript type except function
• ttl: integer (optional) - The number of seconds for which the cached data will be deemed valid. Once the TTL has expired, any get() for the data will return null and the first such request will trigger a purge() of the data (in order to retrieve the localStorage space consumed by the data)

####Returns null - always

###get(key) #####Overview The cache getter.

####Arguments

• key: string - the key name for which to retrieve the cached data

####Returns Data or null if there is no valid (due to ttl) or existing data under the specified key

###purge(key) #####Overview The cache purge (delete).

####Arguments

• key: string - the key name for which to purge the cached data

####Returns null - always

###General principals All public methods conform to the below principals:

• They are synchronous - because localStorage is synchronous
• They will return null if there is no value to return
• They will never throw errors, instead they will return appropriate values

##To do/roadmap

• Create in-browser tests (mocha)
• Handle errors from full localStorage
• Optimise performance
• Fix bugs

##Tests To do!

##License TDPBrowserCache is issued under a Creative Commons attribution share-alike license. This means you can share and adapt the code provided you attribute the original author(s) and you share your resulting source code. If, for some specific reason you need to use this library under a different license then please contact me and i'll see what I can do - though I should mention that I am committed to all my code being open-source so closed licenses will almost certainly not be possible.