#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

``shell
npm install TDPBrowserCache


or


git clone https://github.com/neilstuartcraig/TDPBrowserCache.git
`


##Usage
`html


`

##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.