@r/rest-cache

restcache

A caching solution for data fetching. Reduces the number of API calls you have

to make.

What it is

This cache turns a request, such as api.listings.get({ subreddit: 'funny '}) into two caches:

• A cache of ids returned by that particular query
• A global cache of data objects

The intent is that you can now run api.listings.get({ id: 1 }), and if the previous query had already populated a listing with id 1, you get an immediate response rather than making another server round-trip.

You can also reset specific instances of objects in the cache, for example, on the event of a patch that edits an object.

How it works

(See ./test for examples)

The constructor, new Cache({ }), takes settings:

• rules, a list of rules that operate on the parameters passed into an api request. Rules are functions that return booleans: if they return false, the cache is skipped (and does not invalidate the data cache.)
• defaultRequestCacheConfig, the default config for all API calls if a config is not specified. The cache rules here also set the default request cache LRU settings. defaultRequestCacheConfig.cache uses the same parameters as the LRU.
• dataTypes is an object that contains key - config pairs. The config optionally contains idProperty, which defaults to id if not set (this is how the request IDs are mapped to the data IDs), and cache, which is the LRU cache config. (If not specified, uses the default as noted above.)

The primary function, cache.get, takes a series of arguments:

• The API function (must return a promise)
• The arguments to be passed to the function
• An options object, may optionally contain:
  • key, used to look up a cache of ids returned by a given. This can be ommitted if your function has a unique name (function.name)
  • Optionally, the cache configuration to be used; otherwise, default configuration will be used. Provided config will not be merged with the default.
  • Optionally, a response value formatting function to be returned pre-cache. This should return a flat object such as { datatype: data } so that the cache can put data into the proper place. (This also means you can work with multiple data types at once.)

The cache will generate a key based on a sha1 of the JSON.stringified parameters. It will then look up a list of IDs returned for that key+sha. If it does not exist, it will return a Promise, and attempt to resolve the function passed in with the parameters supplied. It will pass on a promise rejection, or if it is successful, it will:

• Add an id, or a list of ids, to a request cache based on [key][sha]. This maintains a list of ids, not data objects, returned by requests.
• Add the returned data object to a global object cache based on the data type returned.
• Resolve the promise.

If the data is in the cache, it will:

• Use the ids to look up the objects in the global data cache. If they exist, they will be Promise.resolved immediately. If not, the above process will be run, as we will assume the cache is stale.

Another function, cache.resetData, allows you to reset a single object, a list of objects, or to reset a cache entirely for a given data type. It takes the arguments:

• Data type name
• Object or array to update

It will attempt to match the object (or, each object in the array), and replace the objects in the cache with the supplied data. Or, if none was passed in, the cache will be cleared for that data type.

If no arguments are provided, it will reset the entire data cache.

You can also use cache.resetRequests() to reset the request cache. It takes up to three optional arguments as well:

• Cache key
• Cache parameters list
• List of ids

If only key is used, the entire cache for that key will be reset; if both, then it will reset for that single reset; if key, parameters, and ids are sent, it will update the ids to the passed-in list.

If no arguments are provided, it will reset the entire request cache.

Caveats

• API responses must return in the format { headers:{}, body:{} }, and responses from restcache will follow the same format. This allows HTTP headers to be passed around. The contents of headers can be anything, and will be stored in an LRU with the same configration as the request's LRU.
• body must be formatted as { datatype: [data] } to be stored in the caches properly. Use the format option to set up your data properly.

A Sample

function loggedOut (params) {
  return !params.token;
}

var cache = new cache.get({
  rules: {
    loggedOut: function(params) {
      return !params.token;
    },
  },
  defaultRequestCacheConfig: {
    cache: {
      max: 50, //50 items
      length: function(n) { return n.length }, //how length is determined
      dispose: function(key, n) { n.close() }, // optional handling on disposal
      maxAge: 1000 * 60 * 5, // 5 minutes
    },
    rules: [ loggedOut ]
  },
  dataTypes:
    listings: {
      idProperty: '_id',
      cache: {
        max: 75,
        maxAge: 1000 * 60 * 3
      }
    },
    comments: {
      cache: false, // don't cache comments
    }
  }
});

function formatListings(data) {
  return { listings: data };
}

function unFormatListings(data) {
  return data.listings;
}

function getData(url) {
  return new Promise(function(resolve, reject) {
    superagent
      .get(url)
      .then(function(err, res) {
        if(err) { return reject(err); }

        resolve({
          headers: res.headers,
          body: res.body
        });
      });
  });
}

var apiParams = { subreddit: 'funny' };

// Use `api.listings.get.name` as the key, and use the default config.
var listings = cache.get(api.listings.get, [apiParams], {
  format: formatListings
  unformat: unformatListings
});

listings.then(
  function(data) { /*...*/ },
  function(error) { /*...*/ }
);

// Use a custom key and config. Because it has a different key, it will force a
// cache refresh of the listing in question, even though it may already be in
// the listing cache.

var apiParams = { subreddit: 'funny' };
var apiParameters = { _id: 1 };
var key = 'edit-listing-cache';
var listing = cache.get(
                key,
                api.listings.get,
                [apiParams],
                {
                  format: formatListings,
                  unformat: unformatListings
                }
              );

listing.then(
  function(listings) { /*...*/ },
  function(error) { /*...*/ }
);

// Reset an object in the cache that was updated
api.listings.patch(params).then(function(res) {
  cache.resetData('listings', res.listing);
});

// Obliterate the cache
cache.resetData('listings');

// Load a single object
var apiParams = { id: 17 };
cache.getById('listings', apiParams.id, api.listings.get, [apiParams], {
  format: formatListings,
  unformat: unformatListings
});

// Delete an object, then fix the caches
api.listings.delete(17).then(function(res) {
  // Remove the object from the data cache
  cache.deleteData('listings', 17);

  // Optionally force-reset the request if you know the params ahead of time
  cache.resetRequests(api.listings.get, [], { listings: [15,16,18] });
});

Other Notes for Your Careful Consideration

• This assumes the global availability of Promise, provided by iojs, node harmony, and some ES6 transpilers such as babel.