{"id":15561,"library":"cache-control-parser","title":"Cache-Control Header Parser","description":"cache-control-parser is a JavaScript/TypeScript utility for parsing and stringifying HTTP `Cache-Control` header directives. Its current stable version is 2.2.0, with regular updates that enhance its functionality, such as the introduction of the `stringify` function in v2.0.0. The library is designed to be fault-tolerant and case-insensitive when parsing, handling common HTTP caching scenarios robustly. Key differentiators include its zero-dependency footprint, comprehensive built-in TypeScript definitions, and the capability to both convert `Cache-Control` strings into structured JavaScript objects and convert objects back into valid header strings, making it suitable for both consuming and generating HTTP responses in Node.js and browser environments.","status":"active","version":"2.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/etienne-martin/cache-control-parser","tags":["javascript","cache","http","headers","http-headers","cache-control","parser","stringify","typescript"],"install":[{"cmd":"npm install cache-control-parser","lang":"bash","label":"npm"},{"cmd":"yarn add cache-control-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add cache-control-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const parse = require('cache-control-parser').parse;","symbol":"parse","correct":"import { parse } from 'cache-control-parser';"},{"note":"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.","wrong":"const { stringify } = require('cache-control-parser');","symbol":"stringify","correct":"import { stringify } from 'cache-control-parser';"},{"note":"This is a TypeScript type definition for the parsed cache control object. It should be imported using `import type` to avoid bundling issues.","wrong":"import { CacheControl } from 'cache-control-parser';","symbol":"CacheControl","correct":"import type { CacheControl } from 'cache-control-parser';"}],"quickstart":{"code":"import { parse, stringify } from \"cache-control-parser\";\nimport type { CacheControl } from \"cache-control-parser\";\n\n// 1. Parse a cache-control header string into an object\nconst headerString = \"public, max-age=300, stale-while-revalidate=60, no-transform\";\nconst parsedDirectives: CacheControl = parse(headerString);\n\nconsole.log(\"Parsed directives:\", parsedDirectives);\n// Expected output: { public: true, 'max-age': 300, 'stale-while-revalidate': 60, 'no-transform': true }\n\n// 2. Access specific directives and apply fallback logic\nconst { \"max-age\": maxAge, \"stale-while-revalidate\": swr = maxAge ?? 0 } = parsedDirectives;\nconsole.log(`Max Age: ${maxAge || 'N/A'}s, SWR: ${swr}s`);\n\n// 3. Create an object of directives and stringify it back into a header string\nconst newDirectives: CacheControl = {\n  \"max-age\": 600,\n  \"s-maxage\": 120,\n  \"public\": true,\n  \"immutable\": true,\n  \"no-cache\": false // Directives with false values are omitted\n};\nconst newHeaderString = stringify(newDirectives);\n\nconsole.log(\"Stringified header:\", newHeaderString);\n// Expected output: max-age=600, s-maxage=120, public, immutable\n\n// Example of usage in a web framework (e.g., Next.js response)\n// import type { NextApiRequest, NextApiResponse } from \"next\";\n// export default (req: NextApiRequest, res: NextApiResponse) => {\n//   res.setHeader(\n//     \"Cache-Control\",\n//     stringify({\n//       \"max-age\": 300,\n//       \"stale-if-error\": 60\n//     })\n//   );\n//   res.send(\"API response\");\n// };","lang":"typescript","description":"This quickstart demonstrates parsing a Cache-Control header, accessing its directives, and then stringifying a new set of directives, including TypeScript type usage."},"warnings":[{"fix":"Upgrade to `cache-control-parser@^2.0.0` or higher to use the `stringify` function.","message":"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.","severity":"breaking","affected_versions":"<2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Update your package to `npm install cache-control-parser@latest` (or at least `^2.0.0`).","cause":"Attempting to use the `stringify` function on a version of `cache-control-parser` older than 2.0.0.","error":"TypeError: (0 , cache_control_parser_1.stringify) is not a function"},{"fix":"Use ESM import: `import { parse } from 'cache-control-parser';` instead of `const parse = require('cache-control-parser').parse;`.","cause":"Incorrect CommonJS `require` syntax for a library that may be ESM-first or provides named exports primarily through ESM.","error":"TypeError: Cannot read properties of undefined (reading 'parse')"}],"ecosystem":"npm"}