HTTP Cache-Control Header Parser and Formatter (ESM)

1.0.0 · active · verified Wed Apr 22

cache-control-esm is a JavaScript library specifically designed for parsing and formatting HTTP Cache-Control headers in strict adherence to RFC 7234. Currently at version 1.0.0, this package is a specialized fork of the `@tusbar/cache-control` library. Its primary differentiator is its explicit use of ECMAScript modules (`export default` and named exports), making it well-suited for modern bundlers and environments, especially within projects like `axios-cache-adapter`. Unlike other solutions that may bundle Express/Connect-like middleware or extensive interpretation logic, `cache-control-esm` maintains a narrow focus solely on the low-level parsing of header strings into a `CacheControl` object and formatting such objects back into valid HTTP header values. This focused approach ensures a lightweight and reliable tool for precise Cache-Control header manipulation without unnecessary overhead. Its release cadence is typically reactive to the needs of its consuming projects.

Common errors

```
TypeError: require is not a function
```
cause Attempting to import the ESM-only package using CommonJS `require()` syntax in a Node.js environment that expects ESM or where `package.json` does not specify `"type": "commonjs"`.

fix Change `const { parse } = require('@rascarlito/cache-control')` to `import { parse } from '@rascarlito/cache-control'` and ensure your Node.js environment is configured for ESM.
```
SyntaxError: Named export 'parse' not found. The requested module '@rascarlito/cache-control' does not provide an export named 'parse'
```
cause Attempting to use a default import `import parse from '@rascarlito/cache-control'` when `parse` is a named export.

fix Correct the import statement to use named imports: `import { parse } from '@rascarlito/cache-control'`.

Warnings

gotcha This package is a direct fork of the original `@tusbar/cache-control`. Ensure you are installing `@rascarlito/cache-control` if you intend to use the ESM-only version, as the original package might have different module export conventions.
Fix: Always explicitly specify `@rascarlito/cache-control` in your `package.json` and installation commands.
breaking This package is ESM-only and utilizes `export` statements. It is incompatible with CommonJS `require()` syntax directly in Node.js environments unless transpiled or run with `--experimental-modules` (prior to Node.js 12.0.0, or in contexts where ESM is not the default).
Fix: Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) or use a bundler that correctly handles ESM imports. Always use `import` statements.
gotcha The library focuses exclusively on parsing and formatting HTTP `Cache-Control` headers. It does not provide any higher-level logic for interpreting or acting upon the parsed directives (e.g., determining cache hit/miss, freshness, etc.).
Fix: Implement your own cache interpretation logic based on the `CacheControl` object properties, or integrate with a caching library that handles this. This package is a low-level utility.

Install

npm install cache-control-esm npm
yarn add cache-control-esm yarn
pnpm add cache-control-esm pnpm

Imports

parse
wrong:
```
const { parse } = require('@rascarlito/cache-control')
```
correct:
```
import { parse } from '@rascarlito/cache-control'
```
The package is ESM-only and exports named functions. CommonJS `require()` will not work.
format
wrong:
```
import format from '@rascarlito/cache-control'
```
correct:
```
import { format } from '@rascarlito/cache-control'
```
Both `parse` and `format` are named exports. There is no default export for these functions.
CacheControl
wrong:
```
const { CacheControl } = require('@rascarlito/cache-control')
```
correct:
```
import { CacheControl } from '@rascarlito/cache-control'
```
The `CacheControl` class is also a named export, primarily for type inference or direct instantiation.

Quickstart

Demonstrates setting a Cache-Control header using `format` and parsing one using `parse`.

import { format, parse } from '@rascarlito/cache-control';

// Simulate a response object
const res = {
  _headers: {},
  setHeader(name, value) {
    this._headers[name] = value;
  },
  getHeader(name) {
    return this._headers[name];
  }
};

// Set a Cache-Control header using the format function
res.setHeader('Cache-Control', format({
  public: true,
  immutable: true,
  maxAge: 31536000
}));

console.log('Set Cache-Control header:', res.getHeader('Cache-Control'));

// Parse a Cache-Control header from a string
const parsedHeader = parse('max-age=604800, public, no-transform');
console.log('Parsed Cache-Control object:', parsedHeader);

view raw JSON →