cache-headers

Cache Headers

Create cache headers as application-level or route-level middleware. This has only been tested as middleware for an express app. The primary cache header set is the Cache-Control header value. All time values are set as seconds per the w3 spec.

This package is developed using ES6 and transpiled with babel. It is also using the 1stdibs eslint rules.

Installation

$ npm install --save cache-headers

Tests

$ npm install
$ npm test

Usage

App-level middleware

const express = require('express');
const app = express();
const cache = require('cache-headers');
const cacheOptions = {
    paths: {
        '/**/generic': {
            maxAge: 'TEN_MINUTES',
            sMaxAge: 'ONE_DAY',
            staleRevalidate: 'ONE_HOUR',
            staleError: 'ONE_HOUR'
        },
        '/short-cached/route': {
            maxAge: 60,
            sMaxAge: 600
        },
        '/user/route': false,
        '/**': {
            maxAge: 600
        }
    }
};

// some other middleware

app.use(cache.middleware(cacheOptions));

// rest of app setup

With the example above, the Cache-Control header is set as follows when a user hits these different site routes:

• /**/generic (any route ending in generic): Cache-Control: max-age=600, s-maxage=84600, stale-while-revalidate=3600, stale-if-error=3600
• /cached/route: Cache-Control: max-age=60, s-maxage=600
• /user/route: Cache-Control: no-cache, max-age=0
• /** (any other route not listed): Cache-Control: max-age=600

Alternatively for no-cache, the following could be used:

'/user/route': {
    setNoCache: true
}

Router-level middleware

Taking the app-level setup above, you can additionally override the default paths initially set in the cacheOptions.

const express = require('express');
const router = express.Router();
const cache = require('cache-headers');
const cacheOptions = {
    cacheSettings: {
        "maxAge": 2000
    }
};

// app.use(cache.middleware(cacheOptions)) is loaded prior to this route, therefore running by default
// and any subsequent call to set the header is then overwritten

router.get('/endswith/generic', cache.middleware(cacheOptions), (req, res, next) => {
    // do route-y stuff
    next();
});

Rather than set the original headers defined in the paths config in the app-level setup (for the /**/generic path), this will output the following: Cache-Control: max-age=2000

API

cache.middleware (all properties optional)

{
    cacheSettings: {
        maxAge: number|string,
        sMaxAge: number|string,
        staleRevalidate: number|string,
        staleError: number|string
    },
    paths: {
        '/glob/**/path': object|boolean=false
    }
}

The following are acceptable values to use if a string is passed in for cache values:

• 'ONE_MINUTE'
• 'TEN_MINUTES'
• 'ONE_HOUR'
• 'ONE_DAY'
• 'ONE_WEEK'
• 'ONE_MONTH'
• 'ONE_YEAR'

If no options are passed in, the default value set is Cache-Control: max-age=600

Contributing

All code additions and bugfixes must be accompanied by unit tests. Tests are run with mocha and written with the node assert module.

Acknowledgement

A portion of this code was taken from this cache-control package/repo.