headers

Tired of manually parsing and stringifying HTTP header values in JavaScript? headers supercharges the standard Headers interface, providing a robust toolkit for effortless and type-safe header manipulation.

HTTP headers are packed with critical information—from content negotiation and caching directives to authentication tokens and file metadata. While the native Headers API provides a basic string-based interface, it leaves the complexities of parsing specific header formats (like Accept, Content-Type, or Set-Cookie) entirely up to you.

headers solves this by offering:

• Type-Safe Accessors: Interact with complex header values (e.g., media types, quality factors, cookie attributes) through strongly-typed properties and methods, eliminating guesswork and manual parsing.
• Automatic Parsing & Stringification: The library intelligently handles the parsing of raw header strings into structured objects and stringifies your structured data back into spec-compliant header values.
• Fluent Interface: Enjoy a more expressive and developer-friendly API for reading and writing header information.
• Drop-in Enhancement: As a subclass of the standard Headers object, it can be used anywhere a Headers object is expected, providing progressive enhancement to your existing code.
• Individual Header Utilities: For fine-grained control, use standalone utility classes for specific headers, perfect for scenarios outside of a full Headers object.

Unlock a more powerful and elegant way to work with HTTP headers in your JavaScript and TypeScript projects!

Installation

1npm install @mjackson/headers

Overview

The following should give you a sense of what kinds of things you can do with this library:

1import Headers from '@mjackson/headers';
2
3let headers = new Headers();
4
5// Accept
6headers.accept = 'text/html, text/*;q=0.9';
7
8headers.accept.mediaTypes; // [ 'text/html', 'text/*' ]
9Object.fromEntries(headers.accept.entries()); // { 'text/html': 1, 'text/*': 0.9 }
10
11headers.accept.accepts('text/html'); // true
12headers.accept.accepts('text/plain'); // true
13headers.accept.accepts('image/jpeg'); // false
14
15headers.accept.getPreferred(['text/plain', 'text/html']); // 'text/html'
16
17headers.accept.set('text/plain', 0.9);
18headers.accept.set('text/*', 0.8);
19
20headers.get('Accept'); // 'text/html,text/plain;q=0.9,text/*;q=0.8'
21
22// Accept-Encoding
23headers.acceptEncoding = 'gzip, deflate;q=0.8';
24
25headers.acceptEncoding.encodings; // [ 'gzip', 'deflate' ]
26Object.fromEntries(headers.acceptEncoding.entries()); // { 'gzip': 1, 'deflate': 0.8 }
27
28headers.acceptEncoding.accepts('gzip'); // true
29headers.acceptEncoding.accepts('br'); // false
30
31headers.acceptEncoding.getPreferred(['gzip', 'deflate']); // 'gzip'
32
33// Accept-Language
34headers.acceptLanguage = 'en-US, en;q=0.9';
35
36headers.acceptLanguage.languages; // [ 'en-us', 'en' ]
37Object.fromEntries(headers.acceptLanguage.entries()); // { 'en-us': 1, en: 0.9 }
38
39headers.acceptLanguage.accepts('en'); // true
40headers.acceptLanguage.accepts('ja'); // false
41
42headers.acceptLanguage.getPreferred(['en-US', 'en-GB']); // 'en-US'
43headers.acceptLanguage.getPreferred(['en', 'fr']); // 'en'
44
45// Accept-Ranges
46headers.acceptRanges = 'bytes';
47
48// Connection
49headers.connection = 'close';
50
51// Content-Type
52headers.contentType = 'application/json; charset=utf-8';
53
54headers.contentType.mediaType; // "application/json"
55headers.contentType.charset; // "utf-8"
56
57headers.contentType.charset = 'iso-8859-1';
58
59headers.get('Content-Type'); // "application/json; charset=iso-8859-1"
60
61// Content-Disposition
62headers.contentDisposition =
63  'attachment; filename="example.pdf"; filename*=UTF-8\'\'%E4%BE%8B%E5%AD%90.pdf';
64
65headers.contentDisposition.type; // 'attachment'
66headers.contentDisposition.filename; // 'example.pdf'
67headers.contentDisposition.filenameSplat; // 'UTF-8\'\'%E4%BE%8B%E5%AD%90.pdf'
68headers.contentDisposition.preferredFilename; // '例子.pdf'
69
70// Cookie
71headers.cookie = 'session_id=abc123; user_id=12345';
72
73headers.cookie.get('session_id'); // 'abc123'
74headers.cookie.get('user_id'); // '12345'
75
76headers.cookie.set('theme', 'dark');
77headers.get('Cookie'); // 'session_id=abc123; user_id=12345; theme=dark'
78
79// Host
80headers.host = 'example.com';
81
82// If-None-Match
83headers.ifNoneMatch = ['67ab43', '54ed21'];
84headers.get('If-None-Match'); // '"67ab43", "54ed21"'
85
86// Last-Modified
87headers.lastModified = new Date();
88// or headers.lastModified = new Date().getTime();
89headers.get('Last-Modified'); // 'Fri, 20 Dec 2024 08:08:05 GMT'
90
91// Location
92headers.location = 'https://example.com';
93
94// Referer
95headers.referer = 'https://example.com/';
96
97// Set-Cookie
98headers.setCookie = ['session_id=abc123; Path=/; HttpOnly'];
99
100headers.setCookie[0].name; // 'session_id'
101headers.setCookie[0].value; // 'abc123'
102headers.setCookie[0].path; // '/'
103headers.setCookie[0].httpOnly; // true
104
105// Modifying Set-Cookie attributes
106headers.setCookie[0].maxAge = 3600;
107headers.setCookie[0].secure = true;
108
109headers.get('Set-Cookie'); // 'session_id=abc123; Path=/; HttpOnly; Max-Age=3600; Secure'
110
111// Setting multiple cookies is easy, it's just an array
112headers.setCookie.push('user_id=12345; Path=/api; Secure');
113// or headers.setCookie = [...headers.setCookie, '...']
114
115// Accessing multiple Set-Cookie headers
116for (let cookie of headers.getSetCookie()) {
117  console.log(cookie);
118}
119// session_id=abc123; Path=/; HttpOnly; Max-Age=3600; Secure
120// user_id=12345; Path=/api; Secure

Headers can be initialized with an object config:

1let headers = new Headers({
2  contentType: {
3    mediaType: 'text/html',
4    charset: 'utf-8',
5  },
6  setCookie: [
7    { name: 'session', value: 'abc', path: '/' },
8    { name: 'theme', value: 'dark', expires: new Date('2021-12-31T23:59:59Z') },
9  ],
10});
11
12console.log(`${headers}`);
13// Content-Type: text/html; charset=utf-8
14// Set-Cookie: session=abc; Path=/
15// Set-Cookie: theme=dark; Expires=Fri, 31 Dec 2021 23:59:59 GMT

Headers works just like DOM's Headers (it's a subclass) so you can use them anywhere you need a Headers.

1import Headers from '@mjackson/headers';
2
3// Use in a fetch()
4let response = await fetch('https://example.com', {
5  headers: new Headers(),
6});
7
8// Convert from DOM Headers
9let headers = new Headers(response.headers);
10
11headers.set('Content-Type', 'text/html');
12headers.get('Content-Type'); // "text/html"

If you're familiar with using DOM Headers, everything works as you'd expect.

Headers are iterable:

1let headers = new Headers({
2  'Content-Type': 'application/json',
3  'X-API-Key': 'secret-key',
4  'Accept-Language': 'en-US,en;q=0.9',
5});
6
7for (let [name, value] of headers) {
8  console.log(`${name}: ${value}`);
9}
10// Content-Type: application/json
11// X-Api-Key: secret-key
12// Accept-Language: en-US,en;q=0.9

If you're assembling HTTP messages, you can easily convert to a multiline string suitable for using as a Request/Response header block:

1let headers = new Headers({
2  'Content-Type': 'application/json',
3  'Accept-Language': 'en-US,en;q=0.9',
4});
5
6console.log(`${headers}`);
7// Content-Type: application/json
8// Accept-Language: en-US,en;q=0.9

Individual Header Utility Classes

In addition to the high-level Headers API, headers also provides a rich set of primitives you can use to work with just about any complex HTTP header value. Each header class includes a spec-compliant parser (the constructor), stringifier (toString), and getters/setters for all relevant attributes. Classes for headers that contain a list of fields, like Cookie, are iterable.

If you need support for a header that isn't listed here, please send a PR! The goal is to have first-class support for all common HTTP headers.

Accept

1import { Accept } from '@mjackson/headers';
2
3let header = new Accept('text/html;text/*;q=0.9');
4
5header.has('text/html'); // true
6header.has('text/plain'); // false
7
8header.accepts('text/html'); // true
9header.accepts('text/plain'); // true
10header.accepts('text/*'); // true
11header.accepts('image/jpeg'); // false
12
13header.getPreferred(['text/html', 'text/plain']); // 'text/html'
14
15for (let [mediaType, quality] of header) {
16  // ...
17}
18
19// Alternative init styles
20let header = new Accept({ 'text/html': 1, 'text/*': 0.9 });
21let header = new Accept(['text/html', ['text/*', 0.9]]);

Accept-Encoding

1import { AcceptEncoding } from '@mjackson/headers';
2
3let header = new AcceptEncoding('gzip,deflate;q=0.9');
4
5header.has('gzip'); // true
6header.has('br'); // false
7
8header.accepts('gzip'); // true
9header.accepts('deflate'); // true
10header.accepts('identity'); // true
11header.accepts('br'); // true
12
13header.getPreferred(['gzip', 'deflate']); // 'gzip'
14
15for (let [encoding, weight] of header) {
16  // ...
17}
18
19// Alternative init styles
20let header = new AcceptEncoding({ gzip: 1, deflate: 0.9 });
21let header = new AcceptEncoding(['gzip', ['deflate', 0.9]]);

Accept-Language

1import { AcceptLanguage } from '@mjackson/headers';
2
3let header = new AcceptLanguage('en-US,en;q=0.9');
4
5header.has('en-US'); // true
6header.has('en-GB'); // false
7
8header.accepts('en-US'); // true
9header.accepts('en-GB'); // true
10header.accepts('en'); // true
11header.accepts('fr'); // true
12
13header.getPreferred(['en-US', 'en-GB']); // 'en-US'
14header.getPreferred(['en', 'fr']); // 'en'
15
16for (let [language, quality] of header) {
17  // ...
18}
19
20// Alternative init styles
21let header = new AcceptLanguage({ 'en-US': 1, en: 0.9 });
22let header = new AcceptLanguage(['en-US', ['en', 0.9]]);

Cache-Control

1import { CacheControl } from '@mjackson/headers';
2
3let header = new CacheControl('public, max-age=3600, s-maxage=3600');
4header.public; // true
5header.maxAge; // 3600
6header.sMaxage; // 3600
7
8// Alternative init style
9let header = new CacheControl({ public: true, maxAge: 3600 });
10
11// Full set of supported properties
12header.public; // true/false
13header.private; // true/false
14header.noCache; // true/false
15header.noStore; // true/false
16header.noTransform; // true/false
17header.mustRevalidate; // true/false
18header.proxyRevalidate; // true/false
19header.maxAge; // number
20header.sMaxage; // number
21header.minFresh; // number
22header.maxStale; // number
23header.onlyIfCached; // true/false
24header.immutable; // true/false
25header.staleWhileRevalidate; // number
26header.staleIfError; // number

Content-Disposition

1import { ContentDisposition } from '@mjackson/headers';
2
3let header = new ContentDisposition('attachment; name=file1; filename=file1.txt');
4header.type; // "attachment"
5header.name; // "file1"
6header.filename; // "file1.txt"
7header.preferredFilename; // "file1.txt"
8
9// Alternative init style
10let header = new ContentDisposition({
11  type: 'attachment',
12  name: 'file1',
13  filename: 'file1.txt',
14});

Content-Type

1import { ContentType } from '@mjackson/headers';
2
3let header = new ContentType('text/html; charset=utf-8');
4header.mediaType; // "text/html"
5header.boundary; // undefined
6header.charset; // "utf-8"
7
8// Alternative init style
9let header = new ContentType({
10  mediaType: 'multipart/form-data',
11  boundary: '------WebKitFormBoundary12345',
12  charset: 'utf-8',
13});

Cookie

1import { Cookie } from '@mjackson/headers';
2
3let header = new Cookie('theme=dark; session_id=123');
4header.get('theme'); // "dark"
5header.set('theme', 'light');
6header.delete('theme');
7header.has('session_id'); // true
8
9// Iterate over cookie name/value pairs
10for (let [name, value] of header) {
11  // ...
12}
13
14// Alternative init styles
15let header = new Cookie({ theme: 'dark', session_id: '123' });
16let header = new Cookie([
17  ['theme', 'dark'],
18  ['session_id', '123'],
19]);

If-None-Match

1import { IfNoneMatch } from '@mjackson/headers';
2
3let header = new IfNoneMatch('"67ab43", "54ed21"');
4
5header.has('67ab43'); // true
6header.has('21ba69'); // false
7
8header.matches('"67ab43"'); // true
9
10// Alternative init style
11let header = new IfNoneMatch(['67ab43', '54ed21']);
12let header = new IfNoneMatch({
13  tags: ['67ab43', '54ed21'],
14});

Set-Cookie

1import { SetCookie } from '@mjackson/headers';
2
3let header = new SetCookie('session_id=abc; Domain=example.com; Path=/; Secure; HttpOnly');
4header.name; // "session_id"
5header.value; // "abc"
6header.domain; // "example.com"
7header.path; // "/"
8header.secure; // true
9header.httpOnly; // true
10header.sameSite; // undefined
11header.maxAge; // undefined
12header.expires; // undefined
13
14// Alternative init styles
15let header = new SetCookie({
16  name: 'session_id',
17  value: 'abc',
18  domain: 'example.com',
19  path: '/',
20  secure: true,
21  httpOnly: true,
22});

Related Packages

• fetch-proxy - Build HTTP proxy servers using the web fetch API
• node-fetch-server - Build HTTP servers on Node.js using the web fetch API

License

See LICENSE