cache-control

Format and parse HTTP Cache-Control header.

Supports all 16 IANA-registered Cache-Control directives as defined in:

• RFC 9111 — HTTP Caching
• RFC 8246 — HTTP Immutable Responses
• RFC 5861 — HTTP Cache-Control Extensions for Stale Content

CI

Getting started

$ npm install @tusbar/cache-control

API

This library exposes a CacheControl class and two shortcut methods: parse() and format().

parse(header)

import { parse } from "@tusbar/cache-control";

parse() takes a Cache-Control HTTP header value and returns a CacheControl instance.

For example, parse('max-age=31536000, public') will return

CacheControl {
  maxAge: 31536000,
  sharedMaxAge: null,
  maxStale: false,
  maxStaleDuration: null,
  minFresh: null,
  immutable: false,
  mustRevalidate: false,
  mustUnderstand: false,
  noCache: false,
  noCacheFields: null,
  noStore: false,
  noTransform: false,
  onlyIfCached: false,
  private: false,
  privateFields: null,
  proxyRevalidate: false,
  public: true,
  staleIfError: null,
  staleWhileRevalidate: null }

format(cacheControl)

import { format } from "@tusbar/cache-control";

format() takes a CacheControl instance (or similar object) and returns a Cache-Control HTTP header value.

For example, format({maxAge: 31536000, public: true}) will return

max-age=31536000, public

Example usage

import { format } from "@tusbar/cache-control";

res.setHeader(
  "Cache-Control",
  format({
    public: true,
    immutable: true,
  }),
);

Supported directives

Request directives

| Property | Directive | Type | Reference | | ------------------ | ---------------- | ----------------- | ------------------------------------------------------------------------------------------------- | | maxAge | max-age | number \| null | RFC 9111 §5.2.1.1 | | maxStale | max-stale | boolean \| null | RFC 9111 §5.2.1.2 | | maxStaleDuration | max-stale | number \| null | RFC 9111 §5.2.1.2 | | minFresh | min-fresh | number \| null | RFC 9111 §5.2.1.3 | | noCache | no-cache | boolean \| null | RFC 9111 §5.2.1.4 | | noStore | no-store | boolean \| null | RFC 9111 §5.2.1.5 | | noTransform | no-transform | boolean \| null | RFC 9111 §5.2.1.6 | | onlyIfCached | only-if-cached | boolean \| null | RFC 9111 §5.2.1.7 | | staleIfError | stale-if-error | number \| null | RFC 5861 §4 |

Response directives

| Property | Directive | Type | Reference | | ---------------------- | ------------------------ | ------------------ | ---------------------------------------------------------------------------------------------------- | | maxAge | max-age | number \| null | RFC 9111 §5.2.2.1 | | mustRevalidate | must-revalidate | boolean \| null | RFC 9111 §5.2.2.2 | | mustUnderstand | must-understand | boolean \| null | RFC 9111 §5.2.2.3 | | noCache | no-cache | boolean \| null | RFC 9111 §5.2.2.4 | | noCacheFields | no-cache | string[] \| null | RFC 9111 §5.2.2.4 | | noStore | no-store | boolean \| null | RFC 9111 §5.2.2.5 | | noTransform | no-transform | boolean \| null | RFC 9111 §5.2.2.6 | | private | private | boolean \| null | RFC 9111 §5.2.2.7 | | privateFields | private | string[] \| null | RFC 9111 §5.2.2.7 | | proxyRevalidate | proxy-revalidate | boolean \| null | RFC 9111 §5.2.2.8 | | public | public | boolean \| null | RFC 9111 §5.2.2.9 | | sharedMaxAge | s-maxage | number \| null | RFC 9111 §5.2.2.10 | | immutable | immutable | boolean \| null | RFC 8246 | | staleWhileRevalidate | stale-while-revalidate | number \| null | RFC 5861 §3 | | staleIfError | stale-if-error | number \| null | RFC 5861 §4 |

Qualified directives

The no-cache and private response directives optionally accept a list of header field names:

// no-cache="Set-Cookie, Authorization"
parse('no-cache="Set-Cookie, Authorization"');
// → { noCache: true, noCacheFields: ['Set-Cookie', 'Authorization'], ... }

// private="Set-Cookie"
parse('private="Set-Cookie"');
// → { private: true, privateFields: ['Set-Cookie'], ... }

When formatting, field names are included when both the boolean flag and the fields array are set:

format({ noCache: true, noCacheFields: ["Set-Cookie"] });
// → 'no-cache="Set-Cookie"'

format({ noCache: true });
// → 'no-cache'

FAQ

Why another cache-control library?

None of the existing libraries focus on just parsing the Cache-Control headers. There are some that expose Express (or connect-like) middlewares, and some unmaintained other ones that do rudimentary parsing of the header. The idea of this module is to parse the header according to the RFCs with no further analysis or integration.

License

MIT

Miscellaneous

    ╚⊙ ⊙╝
  ╚═(███)═╝
 ╚═(███)═╝
╚═(███)═╝
 ╚═(███)═╝
  ╚═(███)═╝
   ╚═(███)═╝