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 aset()
(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
Configuration
Configuration is virtually zero though you can pass a few options in to the constructor if you wish:
preferLocalStorage
:Boolean
(defaulttrue
) - 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
(notfunction
) - the value to cache. This can be any javascript type exceptfunction
- ttl:
integer
(optional) - The number of seconds for which the cached data will be deemed valid. Once the TTL has expired, anyget()
for the data will returnnull
and the first such request will trigger apurge()
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.