{"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,"search_vec":"'2.2.0':29 'back':99 'browser':117 'built':78 'built-in':77 'cach':2,7,20,65,89,120,127 'cache-control':1,19,88,126 'cache-control-pars':6 'capabl':84 'case':58 'case-insensit':57 'common':63 'comprehens':76 'consum':109 'control':3,8,21,90,128 'convert':87,97 'current':25 'definit':81 'depend':74 'design':50 'differenti':69 'direct':23 'enhanc':34 'environ':118 'fault':54 'fault-toler':53 'footprint':75 'function':36,44 'generat':111 'handl':62 'header':4,22,102,122,125 'http':18,64,112,121,124 'http-header':123 'includ':70 'insensit':59 'introduct':40 'javascript':94,119 'javascript/typescript':12 'key':68 'librari':48 'make':104 'node.js':115 'object':95,98 'pars':15,61 'parser':5,9,129 'regular':31 'respons':113 'robust':67 'scenario':66 'stabl':26 'string':91,103 'stringifi':17,43,130 'structur':93 'suitabl':106 'toler':55 'typescript':80,131 'updat':32 'util':13 'v2.0.0':46 'valid':101 'version':27 'zero':73 'zero-depend':72","created_at":"2026-04-21T17:58:49.294995+00:00","updated_at":"2026-04-21T17:58:49.294995+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/etienne-martin/cache-control-parser","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/cache-control-parser","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-20","install_tag":null}}