Cache-Control Header Parser

Common errors

• TypeError: (0 , cache_control_parser_1.stringify) is not a function

  cause Attempting to use the `stringify` function on a version of `cache-control-parser` older than 2.0.0.
  fix Update your package to `npm install cache-control-parser@latest` (or at least `^2.0.0`).

• TypeError: Cannot read properties of undefined (reading 'parse')

  cause Incorrect CommonJS `require` syntax for a library that may be ESM-first or provides named exports primarily through ESM.
  fix Use ESM import: `import { parse } from 'cache-control-parser';` instead of `const parse = require('cache-control-parser').parse;`.

Warnings

• breaking The `stringify` function was introduced in version 2.0.0. Projects on older major versions (1.x) will not have this function available, leading to runtime errors if called.
  Fix: Upgrade to `cache-control-parser@^2.0.0` or higher to use the `stringify` function.
• gotcha This package is primarily designed for ESM usage. While some bundlers or transpilers may handle CommonJS `require()` syntax, direct `require()` calls in pure Node.js CommonJS environments might lead to import errors for certain Node.js versions or configurations, particularly with named exports.
  Fix: Prefer `import { parse, stringify } from 'cache-control-parser';` for modern JavaScript environments. If strictly using CommonJS, ensure your setup correctly transpiles or handles ESM imports.
• gotcha Directives with a boolean value of `false` (e.g., `'no-cache': false`) will be omitted from the output when using the `stringify` function. Only `true` boolean directives are included, and `number` directives are included with their value.
  Fix: Understand that explicitly setting a boolean directive to `false` will result in its absence from the stringified header, effectively turning it 'off' rather than outputting `no-cache=false` (which is not a valid HTTP header pattern).

Install

• npm install cache-control-parser npm
• yarn add cache-control-parser yarn
• pnpm add cache-control-parser pnpm

Imports

• parse
  wrong:

  const parse = require('cache-control-parser').parse;

  correct:

  import { parse } from 'cache-control-parser';

  The `parse` function extracts directives from a Cache-Control header string. While CJS `require` might work via transpilation or dual packaging, direct ESM import is preferred.
• stringify
  wrong:

  const { stringify } = require('cache-control-parser');

  correct:

  import { stringify } from 'cache-control-parser';

  The `stringify` function was introduced in v2.0.0 to convert a directives object back into a Cache-Control header string. Ensure you are using version 2.0.0 or higher.
• CacheControl
  wrong:

  import { CacheControl } from 'cache-control-parser';

  correct:

  import type { CacheControl } from 'cache-control-parser';

  This is a TypeScript type definition for the parsed cache control object. It should be imported using `import type` to avoid bundling issues.

Quickstart

This quickstart demonstrates parsing a Cache-Control header, accessing its directives, and then stringifying a new set of directives, including TypeScript type usage.

import { parse, stringify } from "cache-control-parser";
import type { CacheControl } from "cache-control-parser";

// 1. Parse a cache-control header string into an object
const headerString = "public, max-age=300, stale-while-revalidate=60, no-transform";
const parsedDirectives: CacheControl = parse(headerString);

console.log("Parsed directives:", parsedDirectives);
// Expected output: { public: true, 'max-age': 300, 'stale-while-revalidate': 60, 'no-transform': true }

// 2. Access specific directives and apply fallback logic
const { "max-age": maxAge, "stale-while-revalidate": swr = maxAge ?? 0 } = parsedDirectives;
console.log(`Max Age: ${maxAge || 'N/A'}s, SWR: ${swr}s`);

// 3. Create an object of directives and stringify it back into a header string
const newDirectives: CacheControl = {
  "max-age": 600,
  "s-maxage": 120,
  "public": true,
  "immutable": true,
  "no-cache": false // Directives with false values are omitted
};
const newHeaderString = stringify(newDirectives);

console.log("Stringified header:", newHeaderString);
// Expected output: max-age=600, s-maxage=120, public, immutable

// Example of usage in a web framework (e.g., Next.js response)
// import type { NextApiRequest, NextApiResponse } from "next";
// export default (req: NextApiRequest, res: NextApiResponse) => {
//   res.setHeader(
//     "Cache-Control",
//     stringify({
//       "max-age": 300,
//       "stale-if-error": 60
//     })
//   );
//   res.send("API response");
// };