cache-service-memcached v1.0.0

Cache service Memcached

• A memcached plugin for cache-service

This module is highly inspired by cache-service-redis

Features

• Background refresh
• Cache objects-automatic serialization/deserialization of values
• Built-in logging using debug-levels.
• Compatible with cache-service and superagent-cache
• .mset() allows you to set expirations on a per key, per function call, and/or per cache-service-memcached instance basis.

Usage

Require and instantiate

//Require superagent and the cache module I want
var superagent = require('superagent');
var CacheServiceMemcached = require('cache-service-memcached');
var memcachedCache = new CacheServiceMemcached('127.0.0.1:11211');
var defaults = {cacheWhenEmpty: false, expiration: 900};

//Patch my superagent instance and pass in my memcached cache
require('superagent-cache')(superagent, memcachedCache, defaults);

Cache!

var lifetime = 300; // 5 minutes
memcachedCache.set('key', 'value', lifetime);

Cache Module Configuration Options

cache-service-memcached's constructor takes an optional config object with any number of the following properties:

defaultLifetime

The expiration to include when executing cache set commands. Can be overridden via .set()'s optional expiraiton param.

• type: int
• default: 90
• measure: seconds

memcachedOptions

The object that is passed to memcached as 2nd parameter. Memcached client options

• type: object

Example

var options = {
  memcachedOptions: {
    maxKeySize: 50,
    maxValue: 20000000
  }
}

backgroundRefreshInterval

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

backgroundRefreshMinTtl

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

backgroundRefreshIntervalCheck

Whether to throw an exception if backgroundRefreshInterval is greater than backgroundRefreshMinTtl. Setting this property to false is highly discouraged.

• type: boolean
• default: true

API

Although this is a memcached wrapper, its API differs in some small cases from memcached's own API both because the memcached API is sometimes dumb and because all cache-service-compatible cache modules match cache-service's API.

.get(key, callback (err, response))

Retrieve a value by a given key.

• key: type: string
• callback: type: function
• err: type: object
• response: type: string or object

.mget(keys, callback (err, response))

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'...}

.set(key, value, expiraiton, refresh(key, cb), callback)

See the Using Background Refresh section for more about the refresh and callback 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

.mset(obj, expiration, callback)

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 a cacheValue 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 and expiration as properties is not present, the expiration provided to the .mset() argument list will be used.
• If neither of the above is provided, each cache's defaultExpiration will be applied.

.del(keys, callback (err, count))

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(cb)

Flush all keys and values.

• callback: type: function

.memcachedClient

This is the underlying Memcached client instance. If needed, you can access memcachedClient functions that haven't abstracted in the cache plugin.

Using Background Refresh

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-memcached 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-memcached 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.

How do I turn it on?

By default, background refresh is off. It will turn itself on the first time you pass a refresh param to .set().

Configure

There are three options you can manipulate. See the API section for more information about them.

• backgroundRefreshInterval
• backgroundRefreshMinTtl
• backgroundRefreshIntervalCheck

Use

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-memcached will assume the fourth param is cb.

The Refresh Param

refresh(key, cb(err, response))

• 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);
}