Redis-cache-decorator NPM

redis-cache-decorator

A decorator to cache your functions. Features:

Uses Redis caching, expiration, and pub/sub.
Concurrency locking - if the function is being run elsewhere with the same arguments, it will wait for the result of that function instead of executing again.
Caching - caches results for as long as you want. If you set ttl=0, then you're just this library for concurrency locking, which is completely fine.
Timeouts - throws when executing or waiting for a function call takes too long
Only tested with ioredis

Use Cases:

Race conditions
API calls with rate limits
Expensive database calls
Expensive function calls

Example

Here's a function that caches all your queries.

const assert = require('assert')
const Redis = require('ioredis')
const pg = require('pg-then')

const pool = pg.Pool(process.env.POSTGRES_URI)

const CreateCacheDecorator = require('redis-cache-decorator')({
  client: Redis.createClient(),
  subscriber: Redis.createClient()
})

const fn = CreateCacheDecorator({
  namespace: 'crazy-database-call',
})((query, values) => {
  return db.query(query).then(result => result.rows)
})

fn(`
  SELECT *
  FROM users
  WHERE id = $1
`, [
  1
]).then(users => {
  assert(Array.isArray(users))
})

API

const CreateCacheDecorator = require('redis-cache-decorator')(options)

Creates a constructor with the following options:

client <required> - a redis client for GET/SET/PUBLISH, etc.
subscriber <required> - a redis client for PSUBSCIRBE
namespace = '' - a prefix for all the events
encoding = 'json' - how data is encoded between redis and node.js. Supported values are:
- json - the default
- string
- buffer
ttl = '30s' - the TTL expiration in seconds.
timeout = '30s' - how long to wait for the function to execute.
pollFactor = 1 / 10 - the fraction of the timeout to poll. For example, a 30s timeout with a 1 / 10 factor means that redis is polled for new changes every 3 seconds.
minimumPollInterval = '100ms' - the minimum frequency of polling so you don't end up spamming redis
createTimeoutError = () => <Error>{ message: 'Timed out!', code: 'RCDTIMEDOUT' } - the function called to create a timeout error. By default, you can check for timeout errors by checking if (err.code === 'RCDTIMEDOUT').
onError = err => console.error(err.stack) - an error handler for redis network errors.
disabled = false - disable this decorator, specifically useful for testing.

const decorate = CreateCacheDecorator(options)

Create a decorator with a set of options.

namespace <required> - a namespace for this decorator
pollInterval - by default, calculated from timeout, pollFactor, and minimumPollInterval, but you can set this yourself.
ttl
timeout
pollFactor
minimumPollInterval
createTimeoutError
onError

const decoratedFunction = decorate(fn)

Decorates the function. The decorated function will have the same API as the original function.

The function should return a value or a Promise that can be JSON.stringify()d.
The function can be synchronous or asynchronous.
this is not supported. Do not access this within the function. The primary reason is that it's difficult to decide how to cache.

const job = decoratedFunction(...args)

Execute the decorated function. Will always return a Promise that resolves to the value. In addition, the promise will have the following properties:

.hash - hash of the arguments for this job.

job.then(value => {}, err => {})

Resolve the promise to retrieve the results of the job.

const hash = decoratedFunction.createHash(...args)

Create the hash string for the specified arguments.

decoratedFunction.set(hash, value).then(value => {})

Manually set the value of a hash.

Streams

If a stream is returned, the values will automatically be buffered.

encoding='json' - the stream will be concatenated as an object stream -> array. If the stream is not an object stream, it will throw.
encoding='string' - the stream will be buffered into a string.
encoding='buffer' - the stream will be buffered into a Buffer() instance.