Registry / http-networking / cache-control-parser

cache-control-parser

library2.2.0jsnpmunverified

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.

http-networking serialization

npm install cache-control-parser

github ↗package ↗

INSTALL

IMPORT

SIG · CACHE-CONTROL-PARS

cache-control-parser

http-networkingjavascriptv2.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

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

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

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

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

✗ const { stringify } = require('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

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

✗ import { 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.

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"); // };

Debug

Known issues

breakingThe `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.

affects: <2.0.0

gotchaThis 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.

affects: >=1.0.0

gotchaDirectives 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).

affects: >=2.0.0

Errors

Common errors & fixes

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

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')

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;`.

Upgrade

Version history

2.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/etienne-martin/cache-control-parser ↗

packagehttps://www.npmjs.com/package/cache-control-parser ↗