- A redis plugin for cache-service
- AND a standalone redis wrapper
- Background refresh
- Cache objects--automatic serialization/deserialization of values
- Easy config handling--pass the name of an ENV OR the
redis
connection config string OR allredis
connection params - Robust API
- Built-in logging with a
verbose
flag. - Compatible with
cache-service
andsuperagent-cache
- Public access to the underlying
node_redis
instance - A more logical API--
.mset()
takes an object of keys and values rather than a comma-separated argument list .mset()
allows you to set expirations on a per key, per function call, and/or percache-service-redis
instance basis (Vanillaredis
does not let.mset()
set expirations at all)- Built-in redis mock support for local testing
Require and instantiate
var csRedis = require('cache-service-redis');
var cacheModuleConfig = {redisEnv: 'REDISCLOUD_URL'};
var redisCache = new csRedis(cacheModuleConfig);
Cache!
redisCache.set('key', 'value');
cache-service-redis
's constructor takes an optional config object with any number of the following properties:
An arbitrary identifier you can assign so you know which cache is responsible for logs and errors.
- type: string
- default: 'redis'
The expiration to include when executing cache set commands. Can be overridden via .set()
's optional expiration param.
- type: int
- default: 900
- measure: seconds
This is the most generic way to pass in your redis configuraiton options.
- type: object
var redisData = {
port: myRedisPort,
hostname: myRedisHostname,
auth: myRedisAuth
}
If you have all of your redis params already prepared as a URL in the following format: http:https://uri:password@hostname:port
, then you can simply pass that URL with the object key redisUrl
.
- type: string
If you have a redis URL contained in an env variable (in process.env[redisEnv]), cache-service can retrieve it for you if you pass the env variable name with the object key redisEnv
.
- type: string
By default, cache-service-redis
attempts to JSON.stringify
and JSON.parse
values on set
and get
respectively. If it fails, it just sets/gets the raw value. This may not always meet your needs. As such, you can provide your own object with stringify
and parse
public functions.
- type: object
If you want to test your cache-service-redis
implementation, you can pass a redis mock with this key and cache-service-redis
will consume it for testing purposes. See the Using A Redis Mock section for a more throrough explanation.
- type: object that mocks redis
How frequently should all background refresh-enabled keys be scanned to determine whether they should be refreshed. For a more thorough explanation on background refresh
, see the Using Background Refresh section.
- type: int
- default: 60000
- measure: milliseconds
The maximum ttl a scanned background refresh-enabled key can have without triggering a refresh. This number should always be greater than backgroundRefreshInterval
.
- type: int
- default: 70000
- measure: milliseconds
Whether to throw an exception if backgroundRefreshInterval
is greater than backgroundRefreshMinTtl
. Setting this property to false is highly discouraged.
- type: boolean
- default: true
When used with
cache-service
, this property is overridden bycache-service
'sverbose
value.
When false, cache-service-redis
will log only errors. When true, cache-service-redis
will log all activity (useful for testing and debugging).
- type: boolean
- default: false
This module automatically attempts to JSON.stringify
values on set
and JSON.parse
values on get
. In the event that either JSON
function throws an error, the module assums the value being set or retrieved was not JSON and returns it as is. If you know you will only ever set and retrieve JSON and would therefore like errors to be logged when the JSON functions throw them, set this property to true.
- type: boolean
- default: false
Although this is a redis wrapper, its API differs in some small cases from redis's own API both because the redis API is sometimes dumb and because all cache-service
-compatible cache modules match cache-service
's API.
Retrieve a value by a given key.
- key: type: string
- callback: type: function
- err: type: object
- response: type: string or object
Retrieve the values belonging to a series of keys. If a key is not found, it will not be in response
.
- keys: type: an array of strings
- callback: type: function
- err: type: object
- response: type: object, example: {key: 'value', key2: 'value2'...}
See the Using Background Refresh section for more about the
refresh
andcallback
params.
Set a value by a given key.
- key: type: string
- callback: type: function
- expiration: type: int, measure: seconds
- refresh: type: function
- callback: type: function
Set multiple values to multiple keys
- obj: type: object, example: {'key': 'value', 'key2': 'value2', 'key3': {cacheValue: 'value3', expiration: 60}}
- callback: type: function
This function exposes a heirarchy of expiration values as follows:
- The
expiration
property of a key that also contains acacheValue
property will override all other expirations. (This means that, if you are caching an object, the string 'cacheValue' is a reserved property name within that object.) - If an object with both
cacheValue
andexpiration
as properties is not present, theexpiration
provided to the.mset()
argument list will be used. - If neither of the above is provided, each cache's
defaultExpiration
will be applied.
Delete a key or an array of keys and their associated values.
- keys: type: string || array of strings
- callback: type: function
- err: type: object
- count: type: int
Flush all keys and values.
- callback: type: function
This is the underlying node_redis
instance. If needed, you can access redis
functions I haven't abstracted.
With a typical cache setup, you're left to find the perfect compromise between having a long expiration so that users don't have to suffer through the worst case load time, and a short expiration so data doesn't get stale. cache-service-redis
eliminates the need to worry about users suffering through the longest wait time by automatically refreshing keys for you. Here's how it works:
cache-service-redis
employs an intelligent background refresh algorithm that makes it so only one dyno executes a background refresh for any given key. You should feel confident that you will not encounter multiple dynos refreshing a single key.
By default, background refresh is off. It will turn itself on the first time you pass a refresh
param to .set()
.
There are three options you can manipulate. See the API section for more information about them.
backgroundRefreshInterval
backgroundRefreshMinTtl
backgroundRefreshIntervalCheck
Background refresh is exposed via the .set()
command as follows:
cacheModule.set('key', 'value', 300, refresh, cb);
If you want to pass refresh
, you must also pass cb
because if only four params are passed, cache-service-redis
will assume the fourth param is cb
.
- key: type: string: this is the key that is being refreshed
- cb: type: function: you must trigger this function to pass the data that should replace the current key's value
The refresh
param MUST be a function that accepts key
and a callback function that accepts err
and response
as follows:
var refresh = function(key, cb){
var response = goGetData();
cb(null, response);
}
You're likely to want to test your implementation of cache-service-redis
. In order to write tests that will run anywhere, you'll need to use a redis mock. I recommend using redis-js. cache-service-redis
natively supports mock usage as follows:
var redisMock = require('redis-js');
var rcModule = require('cache-service-redis');
var redisCache = new rcModule({
redisMock: redisMock,
backgroundRefreshInterval: 500
});
If you use cache-service-redis
inside of AWS Lambda, ensure you follow this example so that your lambda process will terminate when complete.
exports.handler = function (event, context, callback) {
cache.get(key, function (err, val) {
// handle value
// terminate process with `context`
return context.succeed();
// OR terminate process with `callback`
context.callbackWaitsForEmptyEventLoop = false;
return callback(null);
});
};
If you use cache-service-redis
with superagent-cache
or superagent-cache-plugin
inside of AWS Lambda, follow this example.
exports.handler = function (event, context, callback) {
superagent
.get(uri)
.use(superagentCache)
.end(function (err, response){
// handle response here
// terminate process with `context`
return context.succeed();
// OR terminate process with `callback`
context.callbackWaitsForEmptyEventLoop = false;
return callback(null);
}
);
};