request-easy-cache

A caching wrapper around request.

npm install --save request-easy-cache

request-easy-cache wraps calls to request in a layer that caches HTTP responses automatically. Multiple identical requests produce a cached response and body.

Caching is done in-memory using lru-cache, keyed on {url,options}. Calls with identical url and options return the same response and a cloned body.

Usage

Provided in ES6 for clarity.

import request from 'request-easy-cache';

function get(callback) {
	request.get('http://pokeapi.co/api/v1/pokemon/1', {
		json: true
	}, (err, res, body) => {
		callback(body);
	});
}

// simple test example
get( body => {

	let start = Date.now();
	get( body2 => {
		let time = Date.now() - start;

		assert.ok(time<10, 'Should be a cache hit (<10ms)');

		assert.deepEqual(body, body2, 'Should return the same data for a cached call');
	});
});

Note: In addition to request's options, request-easy-cache adds a {boolean} cache option that, when set to false, disables caching for the request.

Methods

.get(url, callback)

Fetch a URL using the default options.

Callback signature is identical to request's: (err, res, body).

.get(url, options, callback)

Fetch a URL with the specified options.

Supports all request options.

.get(options, callback)

Fetch via the specified options.

One of options.url or options.uri must be set.

Supports all request options.

Configuration

The default export is an instance of RequestEasyCache with all default options.

• max: 100: Maximum number of responses to keep cached. Least-recently-used responses are dropped in favor of new ones.
• maxAge: 60000: Maximum time to keep cached responses, in milliseconds. Defaults to 1 minute.

You can override the default settings:

requestEasyCache.enableCache({
	max: 100,		   // 100 cached responses
	maxAge: 60000	   // 60 seconds, in milliseconds
});

It is also possible to create customized instances of RequestEasyCache:

import { RequestEasyCache } from 'request-easy-cache';

let cachedRequest = new RequestEasyCache({
	cacheHttpErrors: false,		// don't cache 4xx/5xx errors
	cache: {
		max: 200,		// max number of responses to keep
		maxAge: 5*6e4	// 5 minute cache lifetime
	}
});

cachedRequest.get('...', (err, res, body) => {});

How It Works

Caching uses a compound key { url, options }. Calls with identical url and options return the same data.

Version History

• 1.3.0 - Passthrough support for non-GET requests, added request(opts) method.
• 1.2.0 - Support time strings for cache.maxAge via ms.
• 1.1.1 - Added preferred support for .get(). .cached() is now an alias.
• 1.1.0 - Updated to be simpler and more similar to the request API (retains backwards compatibility).
• 1.0.0 - Forked from request-again, rewritten in ES6.