cache-control

Returns pre-computed Cache-Control response header tuples. The directive string is built at factory time, so there is zero per-request overhead. Accepts either a raw directive string or structured options. Structured options are validated at construction time. Defaults to the security-safe DEFAULT_DIRECTIVES (private, no-cache).

Pipeline stage: Cross-cutting

Import

import {cacheControl} from '@centralping/ergo';
import {DEFAULT_DIRECTIVES} from '@centralping/ergo/http/cache-control';

Options

Pass directives as a raw string to bypass structured options and their validation.

Option	Type	Default	Description
`directives`	`string`	—	Raw directive string (overrides all below; unvalidated)
`public`	`boolean`	`false`	Add `public` (mutually exclusive with `private`)
`private`	`boolean`	`false`	Add `private` (mutually exclusive with `public`)
`noCache`	`boolean`	`false`	Add `no-cache`
`noStore`	`boolean`	`false`	Add `no-store` (cannot combine with freshness options)
`noTransform`	`boolean`	`false`	Add `no-transform`
`mustRevalidate`	`boolean`	`false`	Add `must-revalidate`
`proxyRevalidate`	`boolean`	`false`	Add `proxy-revalidate`
`immutable`	`boolean`	`false`	Add `immutable`
`maxAge`	`number`	—	`max-age` in seconds (non-negative integer; RFC 9111 §1.2.2)
`sMaxAge`	`number`	—	`s-maxage` in seconds (non-negative integer; RFC 9111 §1.2.2)
`staleWhileRevalidate`	`number`	—	`stale-while-revalidate` in seconds (non-negative integer; RFC 9111 §1.2.2)
`staleIfError`	`number`	—	`stale-if-error` in seconds (non-negative integer; RFC 9111 §1.2.2)

Return Value

Always returns response headers. With no structured options, the value is DEFAULT_DIRECTIVES:

{response: {headers: [['Cache-Control', 'private, no-cache']]}}

Error Responses

None. This middleware always injects headers (it does not return HTTP error statuses).

Construction-time errors

The factory throws TypeError when structured options are invalid (raw directives bypass these checks):

Condition	Error
`maxAge` / `sMaxAge` / `staleWhileRevalidate` / `staleIfError` provided but not a non-negative integer	`TypeError`: `cacheControl(): "{name}" option must be a non-negative integer`
`public` and `private` both truthy	`TypeError`: `cacheControl(): "public" and "private" are mutually exclusive`
`noStore` combined with any freshness option above	`TypeError`: `cacheControl(): "noStore" cannot be combined with freshness directives`

import {compose, cacheControl} from '@centralping/ergo';

// String shorthand
const pipeline = compose(
  cacheControl({directives: 'public, max-age=3600'}),
);

// Structured options
const pipeline = compose(
  cacheControl({
    private: true,
    maxAge: 0,
    mustRevalidate: true,
  }),
);

router.get('/static/:id', {
  cacheControl: {public: true, maxAge: 86400, immutable: true},
  execute: (req, res, acc) => ({
    response: {body: staticContent},
  }),
});

RFC References

API Reference

See the auto-generated cacheControl API docs.