README

request-promise-cache

Request promise with cache

2.0.0 Breaks backward compatibility

The resolved first argument is no longer {response, body, ?error} but just the body. But, you can pass in resolveWithFullResponse=true to the request({..params}) to get the full response object instead of the body.

Other promise libraries?

By default, this module uses the native javascript Promise introduced in Node.js 0.12+, however you can use it with others, by passing your own Promise constructor


// if you want to use bluebird for example
// just do this once, somewhere in your app, ideally whatever file loads first, i.e. app.js
var request = require('request-promise-cache').use( require('bluebird').Promise )

// you dont have to do it again in the same app's other files

Tested with

bluebird
when
q
and native Promise

if you want me to test another one, just add it and make a pull request to the promiseTypes

Usage

var request = require('request-promise-cache');

var query = { recordId: 27 };

var queryString = Object.keys(query).sort().map(function (k) { return k + '=' query[k] }).join('&');
var cacheKey = url + '?' + queryString;

var url = 'http://google.com';
request({
    url: url,
    cacheKey: url,
    cacheTTL: 3600,
    cacheLimit: 12,
    /* bust the cache and get fresh results
    qs: query || {
        _: +new Date()
    },
    */
    // like https://github.com/request/request-promise#get-the-full-response-instead-of-just-the-body
    resolveWithFullResponse: false,
  })
  .then(function(body) {
    // ...
  })
  .catch(function(error) {
    // ...
  });

Options

All of the original request library's options, plus the following:

cacheKey: string, the cache key use, typically, it's just the URL, maybe add the query string
cacheTTL: milliseconds, automatically expire a cache entry after Y number of milliseconds, if used with cacheLimit, whichever comes first will take precedence
cacheLimit: integer, automatically expire a cache entry after X amount of reads, if used with cacheTTL, whichever comes first will take precedence
fresh: true/false, delete the cached entry and get a fresh one
qs._: 123456789 /* anything truthy */, same as fresh however, this query param will be sent over to the remote server, so it will, most likely, bypass the cache on the other end if there is one
resolveWithFullResponse: true/false, copied from request-promise options, defaults to false, basically instead of resolving with the body, it uses the response, which then you need to do response.body to access the body

Asynchronous calls with the same `cacheKey`

If you make 2 or more requests with the same cacheKey at the same time, and of course, the response comes back within the cacheTTL of the first request, only 1 request will go out, the rest will wait for it and resolve at the same time.

Extras

On the returned request object, you can:

request.original access the original request function,
request.defaults() another request object function generator, which is used exactly like the original request.defaults but this one will return a promisified request with the caching.
request.cache is the cache instance using, which is a nano-cache instance, say you need to request.cache.clear()

License

MIT

Usage no npm install needed!