Stale / Expire cache implementation.

CircleCI Known Vulnerabilities

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

Check out the /examples folder.

cd examples/request
npm install # install dependencies in the example folder
npm start # run the example application

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 or undefined 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

• 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
  • options: an Object of default options:
    • expire: expiration time in ms
    • stale: stale time in ms

• getStats(): get and hit count

• resetStats(): reset the statistics

• get(key): get the value for the key or undefined 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
• 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

• new RSCache.LRUStore(options) - uses LRU cache
  • options: an Object of lru-cache options
• new RSCache.MemoryStore() - uses simple Map
• new RSCache.RedisStore(options)
  • options: an Object of ioredis options

Skip cache, useful at 404 status code issue for example.

const error = new Error('error')
error.noCache = true