# @tusbar/cache-control > Format and parse HTTP Cache-Control header Latest version **3.0.1** (published 2026-05-28) · MIT license · 0 weekly downloads ## Install ```sh npm install @tusbar/cache-control pnpm add @tusbar/cache-control yarn add @tusbar/cache-control bun add @tusbar/cache-control ``` ## Health **Score 70/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; has provenance; high maintenance score; high quality score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 3.0.1 | | Published | 2026-05-28 | | First published | 2018-01-12 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 0 | | Unpacked size | 52.6 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Provenance | attested (GitHub Actions) | | GitHub stars | 41 | | Author | Bertrand Marron | | Maintainers | tusbar | | Keywords | cache-control, http, rfc9111, rfc8246, rfc5861, rfc7234 | ## Links - npm: https://www.npmjs.com/package/@tusbar/cache-control - Repository: https://github.com/tusbar/cache-control - Homepage: https://github.com/tusbar/cache-control#readme - Issues: https://github.com/tusbar/cache-control/issues - npm.io page: https://npm.io/package/@tusbar/cache-control ## Alternatives - [memory-cache](https://npm.io/package/memory-cache.md) — 795.0K weekly downloads - [@httptoolkit/proxy-agent](https://npm.io/package/@httptoolkit/proxy-agent.md) — 11.2K weekly downloads - [express-cache-controller](https://npm.io/package/express-cache-controller.md) — 5.3K weekly downloads - [http-cache-middleware](https://npm.io/package/http-cache-middleware.md) — 4.5K weekly downloads - [cache2](https://npm.io/package/cache2.md) — 1.5K weekly downloads ## Recent versions - 3.0.1 (latest) — 2026-05-28 - 3.0.0 — 2026-02-17 - 2.0.0 — 2026-01-13 - 1.0.2 — 2024-06-12 - 1.0.1 — 2023-08-05 - 1.0.0 — 2023-08-05 - 0.6.1 — 2021-11-29 - 0.6.0 — 2021-06-28 - 0.5.0 — 2020-09-22 - 0.4.0 — 2020-02-06 - 0.3.2 — 2020-02-04 - 0.3.1 — 2019-01-21 - 0.3.0 — 2018-10-17 - 0.2.1 — 2018-01-16 - 0.2.0 — 2018-01-14 - … 2 more at https://npm.io/package/@tusbar/cache-control/versions ## README # cache-control [![npm version](https://img.shields.io/npm/v/@tusbar/cache-control)](https://www.npmjs.com/package/@tusbar/cache-control) [![codecov](https://codecov.io/gh/tusbar/cache-control/graph/badge.svg?token=O8MvGFz46p)](https://codecov.io/gh/tusbar/cache-control) [![XO code style](https://img.shields.io/badge/code_style-xo-cyan)](https://github.com/xojs/xo) Format and parse HTTP Cache-Control header. Supports all 16 [IANA-registered Cache-Control directives](https://www.iana.org/assignments/http-cache-directives/) as defined in: - [RFC 9111](https://httpwg.org/specs/rfc9111.html) — HTTP Caching - [RFC 8246](https://httpwg.org/specs/rfc8246.html) — HTTP Immutable Responses - [RFC 5861](https://httpwg.org/specs/rfc5861.html) — HTTP Cache-Control Extensions for Stale Content ## CI [![Tests](https://github.com/tusbar/cache-control/actions/workflows/tests.yml/badge.svg)](https://github.com/tusbar/cache-control/actions/workflows/tests.yml) [![Release](https://github.com/tusbar/cache-control/actions/workflows/release.yml/badge.svg)](https://github.com/tusbar/cache-control/actions/workflows/release.yml) ## Getting started ```bash $ npm install @tusbar/cache-control ``` ## API This library exposes a `CacheControl` class and two shortcut methods: `parse()` and `format()`. ### `parse(header)` ```js 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 ```js 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)` ```js 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 ```js 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](https://httpwg.org/specs/rfc9111.html#cache-request-directive.max-age) | | `maxStale` | `max-stale` | `boolean \| null` | [RFC 9111 §5.2.1.2](https://httpwg.org/specs/rfc9111.html#cache-request-directive.max-stale) | | `maxStaleDuration` | `max-stale` | `number \| null` | [RFC 9111 §5.2.1.2](https://httpwg.org/specs/rfc9111.html#cache-request-directive.max-stale) | | `minFresh` | `min-fresh` | `number \| null` | [RFC 9111 §5.2.1.3](https://httpwg.org/specs/rfc9111.html#cache-request-directive.min-fresh) | | `noCache` | `no-cache` | `boolean \| null` | [RFC 9111 §5.2.1.4](https://httpwg.org/specs/rfc9111.html#cache-request-directive.no-cache) | | `noStore` | `no-store` | `boolean \| null` | [RFC 9111 §5.2.1.5](https://httpwg.org/specs/rfc9111.html#cache-request-directive.no-store) | | `noTransform` | `no-transform` | `boolean \| null` | [RFC 9111 §5.2.1.6](https://httpwg.org/specs/rfc9111.html#cache-request-directive.no-transform) | | `onlyIfCached` | `only-if-cached` | `boolean \| null` | [RFC 9111 §5.2.1.7](https://httpwg.org/specs/rfc9111.html#cache-request-directive.only-if-cached) | | `staleIfError` | `stale-if-error` | `number \| null` | [RFC 5861 §4](https://httpwg.org/specs/rfc5861.html#stale-if-error) | ### Response directives | Property | Directive | Type | Reference | | ---------------------- | ------------------------ | ------------------ | ---------------------------------------------------------------------------------------------------- | | `maxAge` | `max-age` | `number \| null` | [RFC 9111 §5.2.2.1](https://httpwg.org/specs/rfc9111.html#cache-response-directive.max-age) | | `mustRevalidate` | `must-revalidate` | `boolean \| null` | [RFC 9111 §5.2.2.2](https://httpwg.org/specs/rfc9111.html#cache-response-directive.must-revalidate) | | `mustUnderstand` | `must-understand` | `boolean \| null` | [RFC 9111 §5.2.2.3](https://httpwg.org/specs/rfc9111.html#cache-response-directive.must-understand) | | `noCache` | `no-cache` | `boolean \| null` | [RFC 9111 §5.2.2.4](https://httpwg.org/specs/rfc9111.html#cache-response-directive.no-cache) | | `noCacheFields` | `no-cache` | `string[] \| null` | [RFC 9111 §5.2.2.4](https://httpwg.org/specs/rfc9111.html#cache-response-directive.no-cache) | | `noStore` | `no-store` | `boolean \| null` | [RFC 9111 §5.2.2.5](https://httpwg.org/specs/rfc9111.html#cache-response-directive.no-store) | | `noTransform` | `no-transform` | `boolean \| null` | [RFC 9111 §5.2.2.6](https://httpwg.org/specs/rfc9111.html#cache-response-directive.no-transform) | | `private` | `private` | `boolean \| null` | [RFC 9111 §5.2.2.7](https://httpwg.org/specs/rfc9111.html#cache-response-directive.private) | | `privateFields` | `private` | `string[] \| null` | [RFC 9111 §5.2.2.7](https://httpwg.org/specs/rfc9111.html#cache-response-directive.private) | | `proxyRevalidate` | `proxy-revalidate` | `boolean \| null` | [RFC 9111 §5.2.2.8](https://httpwg.org/specs/rfc9111.html#cache-response-directive.proxy-revalidate) | | `public` | `public` | `boolean \| null` | [RFC 9111 §5.2.2.9](https://httpwg.org/specs/rfc9111.html#cache-response-directive.public) | | `sharedMaxAge` | `s-maxage` | `number \| null` | [RFC 9111 §5.2.2.10](https://httpwg.org/specs/rfc9111.html#cache-response-directive.s-maxage) | | `immutable` | `immutable` | `boolean \| null` | [RFC 8246](https://httpwg.org/specs/rfc8246.html) | | `staleWhileRevalidate` | `stale-while-revalidate` | `number \| null` | [RFC 5861 §3](https://httpwg.org/specs/rfc5861.html#stale-while-revalidate) | | `staleIfError` | `stale-if-error` | `number \| null` | [RFC 5861 §4](https://httpwg.org/specs/rfc5861.html#stale-if-error) | ### Qualified directives The `no-cache` and `private` response directives optionally accept a list of header field names: ```js // 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: ```js 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 ``` ╚⊙ ⊙╝ ╚═(███)═╝ ╚═(███)═╝ ╚═(███)═╝ ╚═(███)═╝ ╚═(███)═╝ ╚═(███)═╝ ``` --- _Source: https://npm.io/package/@tusbar/cache-control · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._