1.9.0 • Public • Published


    Build Status

    cachemachine is a simple caching engine for HTTP GET requests that your Node.js applications make. It is designed to be run with Redis as the cache data-store but can be used without it in a single-node configuration during development.

    Normally, to create an HTTP request, you would use the request library like so:

      var request = require('request');
      request('', function(e, r, b) {

    If you use cachemachine instead you can do this:

    // startup cachemachine (default = cache every GET request for 1 hour)
    var request = require('cachemachine')();
    // make a request
    request('', function(e, r, b) {
      // at this point, the request has completed and has been cached too

    And subsequent requests for the same content will be returned from an in-memory cache without making the same request again.


    Install cachemachine into your Node.js app with

    npm install --save cachemachine


    Set up cachemachine in your own app with the default cache store:

    var cachemachine = require('cachemachine')();

    or with Redis (localhost:6379)

    var cachemachine = require('cachemachine')({redis: true});

    or with a remote Redis server:

    var opts = {
      redis: true,
      hostname: '',
      port: 8000,
      password: 'mysecretpassword'
    var request = require('cachemachine')(opts);

    Configure paths to cache

    To specify which paths you'd like to be cached by cachemachine, then supply a paths parameter containing an array of objects e.g.:

    var opts = {
      paths: [
        { path: '/api/v1/.*', ttl: 3600 }
    var request = require('cachemachine')(opts);

    The objects that you pass in should contain:

    • path - a string or RegExp that defines the path you wish to match
    • ttl - the time-to-live of the cache key in seconds

    Make requests

    Simply use the request object as normal:

    request({method: 'get', url: '', qs: {limit:20}}, function(e, h, b) {

    Note that cachemachine's request object supports being called with a single 'object' or string parameter or using the get/head/post/put/patch/del helper functions. It also supports Node.js streaming.


    How does it work?

    When an outgoing request is made through cachemachine where the path matches one of your regular expressions, the url and query string are formed into a hash. This becomes the cache key for the cache data store. If the request can be retrieved from cache, it is fetched and the callback called. If the item is not in cache, it is fetched using a real 'request' object, cached and then returned to you.

    Why cachemachine?

    If you're using request already and don't want to change your code, then you can use cachemachine as a drop-in replacement and decide which HTTP calls to cache and for how long. This can take the load of over-burdened API servers and speed up your service.

    Using cachemachine to cache CouchDB/Cloudant databases

    Apache CouchDB & Cloudant have an HTTP API and you may wish to cache certain GET requests, such as queries on views. The Cloudant Node.js library allows a custom request object to be passed in so we can pass in a pre-configured cachemachine object e.g.:

    var paths = [ { path: '^/mydb/_design/.*', ttl: 60*60 }];
    var cachemachine = require('cachemachine')({paths: paths});
    var nano = require('nano')({ url: myurl, request: cachemachine });

    Then requests that match cachemachine's paths will be cached:

    var db = nano.db.use('mydb');
    db.view('clicks', 'byday', {group: true}, function(err, data) {
      // data is returned and cached transparently

    Using with IBM Redis cloud service

    Furthermore I want to use it with IBM Redis service that makes use of explicit TLS certificates.

    For an example how to use it with IBM Cloud Redis please see example.js. Instead of defining hostname, password and port

    var opts = {
      redis: true,
      connectionString: "rediss://"
      cert: "L***********************************o="

    with connectionString copied from the redis credential entry connection.redis.composed[0] and the certificate from connection.rediss.certificate.certificate_base64.


    npm i cachemachine

    DownloadsWeekly Downloads






    Unpacked Size

    31.1 kB

    Total Files


    Last publish


    • glynnbird