Node.js Reference ยท Web APIs in Node.js
Node.js Headers class
Reference for the Headers class in Node.js: create, read, append, set and delete HTTP headers, iterate them, and handle multiple Set-Cookie values.
Headers is a collection of HTTP header names and values with case-insensitive lookup. It is a global class that fetch(), Request and Response use for their headers properties, and you can create your own to build the headers of an outgoing request.
Names are stored in lower case, and iteration is sorted by name. If a header occurs several times, get() joins the values with a comma and a space, which is the HTTP rule for repeated headers. The one exception is Set-Cookie, which can not be joined safely, so there is a separate method, getSetCookie(), that returns every cookie line.
const headers = new Headers({ 'Content-Type': 'text/plain' }); headers.append('Accept', 'text/html'); console.log(headers.get('content-type')); // text/plain
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
new Headers([init])
init is another Headers, an array of [name, value] pairs, or a plain object of strings.
| Method | Description |
|---|---|
append(name, value) |
Add a value. If the name exists, the new value is added to the existing ones. |
set(name, value) |
Replace every value of that name with this one. |
get(name) |
The values joined with ', ', or null when the header is absent. |
getSetCookie() |
An array with one string per Set-Cookie header (empty when there are none). |
has(name) |
true if the header exists. |
delete(name) |
Remove the header. Missing names are ignored. |
entries(), keys(), values(), forEach(cb), [Symbol.iterator]() |
Iterate sorted, lower-case names with combined values (one entry per cookie for Set-Cookie). |
Returns: append(), set(), delete() and forEach() return undefined; the others return the values described above.
Errors: TypeError for an invalid name (empty, containing spaces or characters outside the HTTP token set) or an invalid value (containing a newline or null byte), and when a pair array does not have exactly two items. Headers belonging to a Request or Response with a guard, such as an immutable response from fetch(), throw TypeError on writes.
Usage notes
- Names are case-insensitive, stored lower case. HTTP/2 requires lower case, and
Headersmatches that, so do not rely on the original capitalization of a name. - Values are trimmed of leading and trailing whitespace on
append()andset(). get()returnsnull, notundefined, when a header is missing, and a string (possibly empty) otherwise.- Use
getSetCookie()for cookies.get('set-cookie')joins cookies with commas, but cookie dates also contain commas, so the result cannot be split reliably. - Responses from
fetch()are read-only; to change a header, copy it withnew Headers(response.headers), or build a newResponse. - Plain objects are not
Headers.Object.fromEntries(headers)makes an object with lower-case keys;new Headers(obj)goes the other way. Repeated headers are joined when iterated, except cookies. - Node servers use another API. The
httpmodule'sreq.headersis a plain object of lower-case names, andres.setHeader()has its own rules; convert withnew Headers(req.headers)where values are strings (array values needappend()). getSetCookie()was added in Node 19.7 and 18.15.