http-cache-control-kit

Parse and format HTTP Cache-Control headers with structured diagnostics.

http-cache-control-kit is a clean-room TypeScript utility for small browser, worker, CLI and server tooling. It has no runtime dependencies and does not use Node-only APIs.

Demo

Try the browser demo: packages.wasta-wocket.fr/http-cache-control-kit.

Package quality

• TypeScript types are generated from the source.
• ESM-only package with no runtime dependencies.
• Marked as side-effect free for bundlers.
• CI runs npm ci, typecheck, build, and test.
• Tested on Node.js 20 and 22 with GitHub Actions.
• Browser-friendly implementation with no Node-only APIs.

Install

npm install http-cache-control-kit

Quick Start

import {
  formatCacheControl,
  getCacheControlDeltaSeconds,
  parseCacheControl
} from "http-cache-control-kit";

const parsed = parseCacheControl("public, max-age=3600, stale-while-revalidate=30");

if (parsed.ok) {
  console.log(parsed.values.public); // true
  console.log(getCacheControlDeltaSeconds(parsed, "max-age")); // 3600
}

const header = formatCacheControl({
  public: true,
  "max-age": "3600",
  "stale-while-revalidate": "30"
});

Why This Package

Use this package when you need to inspect a Cache-Control header and explain what is wrong with it. The parser returns directives plus stable diagnostic codes for duplicate directives, missing delta-seconds values, invalid quoted strings and unknown directives.

It intentionally does not evaluate full HTTP cache semantics across Expires, Age, ETag, request method or request-vs-response context. For that broader job, use a full cache semantics library.

API

parseCacheControl(input, options?)

Returns a result object. Invalid input and invalid directives are reported in diagnostics instead of throwing.

const result = parseCacheControl('private="Authorization, Cookie", max-age=60');

result.values.private; // "Authorization, Cookie"
result.values["max-age"]; // "60"

The parser accepts both request and response directives. For example, max-stale is valid without a value in request headers, but if a value is provided it must be valid delta-seconds.

parseCacheControl("max-stale").values["max-stale"]; // true
getCacheControlDeltaSeconds(parseCacheControl("max-stale=120"), "max-stale"); // 120

formatCacheControl(values, options?)

Formats a directive map or parsed directive array back into a header string.

formatCacheControl({ "max-age": "60", private: "Authorization, Cookie" }, { sort: true });
// 'max-age=60, private="Authorization, Cookie"'

hasCacheControlDirective(result, directive)

Case-insensitive presence check against a parse result.

getCacheControlDeltaSeconds(result, directive)

Returns a numeric delta-seconds value when the directive exists and contains a non-negative integer.

Diagnostics

Diagnostic codes are stable strings for tests, UI hints and logs:

• empty-input
• expected-string
• empty-directive
• invalid-directive-name
• missing-value
• duplicate-directive
• invalid-quoted-string
• invalid-delta-seconds
• unknown-directive

Options

| Option | Default | Description | | --- | --- | --- | | allowUnknown | false | Keep unknown directives but report them as diagnostics unless enabled. | | allowDuplicates | false | Keep repeated directives instead of reporting and ignoring later values. | | sort | false | Sort formatted directives by name. | | quoteValues | "auto" | Quote formatted values automatically, always or never. |

Browser Compatibility

The core only uses strings, arrays, objects and regular expressions. It performs no I/O and has no dependency on fs, path, Buffer, process or network APIs.

License

MPL-2.0