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

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