An extensible caching interface for HTTP traffic.
Switch branches/tags
Nothing to show
Latest commit 9d33107 Nov 25, 2013 @asilvas asilvas do not add suo files
Failed to load latest commit information.
LICENSE.txt initial commit Nov 1, 2013


Build Status NPM version


npm install http-cache

What is it?

A simple HTTP caching interface with extensible provider support.

Getting Started with Connect/Express

Using Connect or Express?

	connect = require("connect"),
	http = require("http"),
	HttpCache = require("http-cache")

var app = connect()
	.use(new HttpCache({ }))
	.use(function(req, res) {
		res.end("Cache this response! Time=" + new Date().getTime());


Getting Started with HTTP

Real coders use no middleware? We've got you covered...

	http = require("http"),
	HttpCache = require("http-cache")

var httpcache = new HttpCache({ });
http.createServer(function(req, res) {
	httpcache(req, res, function() {
		res.end("Cache this response! Time=" + new Date().getTime());

HttpCache Options

Options may be provided when constructing your HttpCache object...

var HttpCache = require("http-cache");
var httpcache = new HttpCache({ /* my options go here */ });

Options include:

  • ttl (default: 600) - Time (in seconds) before cache object will be purged.
  • provider (default: require("lib/providers/InProcProvider")) - Alternate providers may be specified, including your own Custom Provider.
  • headersToExclude (default: see code) - You may optionally manage which HTTP headers are included/excluded via this object.
  • rules (default: []) - An optional set of custom caching rules. See Custom Rules.
  • varyByHeader (default: []) - An array of strings that will cache key by specific header fields.
  • varyByParam (default: []) - An array of strings that will cache key by specific querystring parameters.
  • purgeAll (default: false) - If true, will clear all cache objects from the provider. Typically only useful during testing.
  • confirmCacheBeforeEnd (default: false) - If set to true, will confirm successful cache writes before ending response. Typically only used for unit tests to avoid race conditions. Should not be used in a production setting.

Custom Rules

Both synchronous and asynchronous rules may be provided:

	rules: function(req, res) {
		// do not cache users folder
		return (/\/users\//i.test(req.url) === false);

Async rules leverage cb instead of returning...

	rules: function(req, res, cb) {
		setTimeout(function() {
			// do not cache users folder
			cb(null, /\/users\//i.test(req.url) === false);
		}, 100);

Multiple rules may be provided as well... (will be processed in parallel)

	rules: [ rule1, rule2, rule3 ]

Custom Provider

Providers are intended to be very simple and extensible, so feel free to contribute your own providers if what is provided does not suite your needs.

  • provider.isTTLManaged - If set to true, http-cache will not be responsible for purging expired entries. Reserved for distributed providers that have internal support for TTL that will be more reliable.
  • provider.get(key, cb) - Returns object via callback. If no object found, null or undefined should be returned, NOT an error.
  • provider.set(key, cache, cb) - Stores a JavaScript object in whatever means necessary.
  • provider.remove(key, cb) - Removes cache entry if it exists.
  • provider.clear(cb) - Purges all cache entries.

See lib/providers/in-proc-provider.js to see how to create your own provider.

Available Providers

If you build your own custom provider, feel free to issue a pull request so we can reference your provider as well.

Tests & Code Coverage

Download and install:

git clone
cd node-http-cache
npm install

Now test:

npm test

View code coverage in any browser:





  • Add FileSystem Provider
  • Add sliding TTL support? (Possible performance impact)
  • Add per-request TTL customization? (Possible performance impact)
  • Add support for array based header values (part of node spec), i.e.
    • res.writeHead(200, { "set-cookie": [cookie1, cookie2] });