Cache Advice

by Matthew Lyon matthew@lyonheart.us

A javascript module for caching the results of functions that take callbacks in the node [err, response] pattern. Useful for decorating functions that make slow database calls, http requests, etc.

The caching mechanism is pluggable, by default will use lru-cache. Other stores:

• redis

Coming soon:

• memcached
• riak
• sql table

Example

var cacher = require('cache-advice')();
var getter = cacher.readThrough(reallySlowDbQuery);

// will call `reallySlowDbQuery(params)`, store results in cache at the key
// generated by `Array.prototype.slice.call(arguments).join()`. You can
// override the key generator.
var now = Date.now();
getter(params, function(err, result){
  console.log("took %d ms", Date.now() - now);
});

setTimeout(function(){
  var now = Date.now();
  // will check the cache first, if found will serve from that
  getter(params, function(err, result){
    console.log("took %d ms", Date.now() - now);
  });
  }, 2000);

Public API

cacheAdvice(state)

Returns an advice giver, refered to as 'advice' below. State is an object with any of the following keys:

• cache: An object with functions at the keys:

  • get(key, callback): retrives an item from the cache, provides to callback.
  • set(key, value, callback): stores an item in the cache.
  • del(key, callback): removes an item from the cache.

  If not provided, will default to a wrapper of node-lru.

• prefix: Will prefix keys with this string.

• keyStrategy: Given Array.prototype.slice.call(arguments), returns the key to use for a given function.

Configuration

advice.prefix(prefixStr)

• prefix: String. If given, forks the advice with a new prefix. If not given, returns the existing prefix.

advice.appendPrefix(prefixStr)

• prefix (required): String. Forks the advice strategy, appending the given string to the current one.

advice.keyStrategy(fn)

• fn: Function. If given, forks the advice with a new key generation strategy function. If not given, returns the existnig key generation strategy. The default function is:

  function(){ return Array.prototype.join.apply(arguments); }
  

  The function will receive all arguments to the function except the final callback argument.

Function Decorators

Will augment a provided function that conforms to the node.js callback pattern (that is, is called with [arg1, arg2, ..., callback] and calls the callback with [err, result1, result2, ...]) with a strategy for managing a the results in a cache. The arguments to the function are used to generate the cache key using the prefix and strategies in the config, and the results are provided to the actual cache as an array, typically to be serialized via JSON.

advice.updates(fn)

Will call fn with provided arguments and update the cache key for the provided arguments with the result.

advice.readThrough(fn)

Will check the cache first. On a hit, will provide cached results. On a miss, will call fn with provided arguments and update the cache key for the provided arguments with the result.

advice.expires(fn)

Will expire the cache key for the provided arguments, then call fn with them.