@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 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

Stores

• 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

Implementations

• 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

Stale if error

No cache

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

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