tusbar/cache-control

Format and parse HTTP Cache-Control header

cache-control

Format and parse HTTP Cache-Control header

CI

Getting started

$ npm install @tusbar/cache-control

API

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

parse(header)

const {parse} = require('@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,
  noCache: false,
  noStore: false,
  noTransform: false,
  onlyIfCached: false,
  private: false,
  proxyRevalidate: false,
  public: true,
  staleIfError: null,
  staleWhileRevalidate: null }

format(cacheControl)

const {format} = require('@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

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

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 RFC with no further analysis or integration.

See also

• cachecontrol: Golang HTTP Cache-Control Parser and Interpretation

License

MIT

Miscellaneous

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

cache-control's Issues

Flaky installs when installing via yarn

I'm seeing occasional installation failures for this package when installing via yarn 4, which is making my CI very flaky. It'll report errors like:

13:54:26  ➤ YN0000: │ @tusbar/cache-control@npm:1.0.1 STDERR npm WARN exec The following package was not found and will be installed: [email protected]
13:54:26  ➤ YN0000: │ @tusbar/cache-control@npm:1.0.1 STDERR npm WARN exec The following package was not found and will be installed: [email protected]
13:54:26  ➤ YN0000: │ @tusbar/cache-control@npm:1.0.1 STDERR sh: 1: only-allow: not found
13:54:26  ➤ YN0009: │ @tusbar/cache-control@npm:1.0.1 couldn't be built successfully (exit code 127, logs can be found here: /tmp/xfs-7e933b3f/build.log)

this is related to the preinstall script here:

cache-control/package.json

Line 30 in 49fda9c

"preinstall": "npx only-allow pnpm",

Some similar issues on different projects:
ethereum-optimism/optimism#9078
Sphereon-Opensource/PEX#157

This also could be related to some quirks in the way yarn 2+ run lifecycle scripts: https://yarnpkg.com/advanced/lifecycle-scripts#postinstall

Thoughts on removing this, or using corepack + the packageManager field to encourage contributors to use the correct package manager? Happy to send a PR if either are acceptable.

Directives with age value of 0 are omitted in format string

A max-age=0 indicates the cache to revalidate the resource every time. The following snippet should correctly format the header as 'max-age=0, public'

const { format } = require('@tusbar/cache-control')
format({maxAge: 0, public: true})
// output 'public'

Implement valueOf to compare CacheControl objects

It would be really helpful if the CacheControl object implemented a custom valueOf in order to compare CacheControl objects.

Use-case: I'm making a bunch of HTTP requests to various 3rd party servers and combining them into a single response. These requests have various Cache-Control headers, but I'd like my API to respond with the most restrive (i.e. least cachable) of the lot.

For instance, if I have a set like this:

max-age: 600, public
max-age: 300, public

I'd need the second of the two. But if I have a set like this:

private
max-age: 600, public
max-age: 300, public

I would need the first one.

I realize it might be difficult to translate the Cache-Control into a number, but I think it's ok if some options produce the same number (i.e. private could be -1 and immutable could be 100000000 or something). Or perhaps different options have different weights?

Dart Port

Thanks for the awesome package!

Ported to dart: https://github.com/rodydavis/cache-control-dart

All tests pass!

Add references to RFC

https://tools.ietf.org/html/rfc7234

Support header lists

for no-cache and private

Add tests

add stale-while-revalidate directive

Although not part of the core HTTP caching standard, there is already good browser support
https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#Browser_compatibility

immutable is also part of this which is already supported by this module.

More info at MDN: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control

Missing `stale-if-error`

Hi, thanks for this great lib!

I noticed that it's missing stale-if-error, documented here: https://tools.ietf.org/html/rfc5861#section-4