@risingstack/cache
Stale / Expire cache implementation.
Getting Started
npm install --save @risingstack/cache
yarn add @risingstack/cache
RSCache assumes Node version 6 or above.
To get started create an RSCache
instance.
const RSCache = require('@risingstack/cache')
const memoryStore = new RSCache.MemoryStore()
const redisStore = new RSCache.RedisStore(/* ioredis options */)
const cache = new RSCache([memoryStore, redisStore], {
timeout: 200
})
Wrap:
Wrap Promise into cache.
cache.wrap('key', () => Promise.resolve({
value: { foo: 'bar' },
cacheOptions: {
stale: 50, // stale is optional: refresh after stale
expire: 100 // expire is required: only used when fn fails (0 removed from cache, undefined skips cache)
}
}))
.then((value) => {
console.log(value) // { foo: 'bar' }
})
or with global cache options, just:
cache.wrap('key', () => Promise.resolve({ foo: 'bar' }))
.then((value) => {
console.log(value) // { foo: 'bar' }
}, {
stale: 50,
expire: 100
})
or with both. With both local and global cache options, the two objects are merged and local has higher priority.
stale: optional: refresh after stale, time until value can be used from cache expire: required: time until value can be used from cache if fn fails
0 <= stale < expire
Some examples:
-
{ expire: 24 * 60 * 1000 }
: use cache only at error -
{ expire: 24 * 60 * 1000, stale: 60 * 1000 }
: use from cache until stale, use until expire at error
Examples
Check out the /examples folder.
cd examples/request
npm install # install dependencies in the example folder
npm start # run the example application
API
RSCache
new RSCache([store, ...], options)
- store order specifies get
precedency, which means that the cache will try to get the value from stores with lower indexes first
-
options
: optional-
timeout
: optional, Number in milliseconds, maximum time that cache waits for get
-
-
get(key)
: get the value for the key orundefined
if not found -
set(key, value, options)
: sets the value-
options: an Object of options:
-
expire: expiration time in
ms
-
stale: stale time in
ms
-
expire: expiration time in
-
options: an Object of options:
-
delete(key)
: delete a value for the key -
clear()
: remove all values -
wrap(key, func, options)
: wrap a function with cache-
func: a Function returning a
Promise
of value or Object of{ value, cacheOptions }
-
cacheOptions: an Object of options:
-
expire: expiration time in
ms
-
stale: stale time in
ms
-
expire: expiration time in
-
cacheOptions: an Object of options:
-
options: an Object of default options:
-
expire: expiration time in
ms
-
stale: stale time in
ms
-
expire: expiration time in
-
func: a Function returning a
-
getStats()
: get and hit count -
resetStats()
: reset the statistics
Stores
-
get(key)
: get the value for the key orundefined
if not found -
set(key, value, options)
: sets the value-
options: an Object of options:
-
expire: expiration time in
ms
-
stale: stale time in
ms
-
expire: expiration time in
-
options: an Object of options:
-
delete(key)
: delete a value for the key -
clear()
: remove all values -
size()
: size of the store -
getStats()
: get and hit count -
resetStats()
: reset the statistics
Implementations
-
new RSCache.LRUStore(options)
- uses LRU cache- options: an Object of lru-cache options
-
new RSCache.MemoryStore()
- uses simpleMap
-
new RSCache.RedisStore(options)
- options: an Object of ioredis options
Stale if error
No cache
Skip cache, useful at 404 status code issue for example.
const error = new Error('error')
error.noCache = true