RezoHeaders

RezoHeaders provides property-style access via a Proxy, convenience methods for common headers, ordered serialization for browser fingerprint matching, and proper set-cookie handling.

import { RezoHeaders } from 'rezo';

Creating Headers

RezoHeaders accepts the same initializers as native Headers, plus Node.js OutgoingHttpHeaders (which can have array values) and other RezoHeaders instances:

// From an object
const headers = new RezoHeaders({
  'content-type': 'application/json',
  'authorization': 'Bearer token123',
});

// From entries array
const headers = new RezoHeaders([
  ['content-type', 'application/json'],
  ['accept', 'text/html'],
]);

// From native Headers
const native = new Headers({ 'x-custom': 'value' });
const headers = new RezoHeaders(native);

// From Node.js OutgoingHttpHeaders (supports array values)
const headers = new RezoHeaders({
  'set-cookie': ['a=1', 'b=2'],   // Arrays are expanded via append()
  'content-type': 'text/html',
});

// Copy from another RezoHeaders
const copy = new RezoHeaders(existingHeaders);

Proxy-Based Property Access

The constructor returns a Proxy that lets you read and write headers as object properties:

const headers = new RezoHeaders();

// Set headers via property assignment
headers['content-type'] = 'application/json';
headers['x-request-id'] = 'abc-123';

// Read headers via property access
console.log(headers['content-type']);  // 'application/json'
console.log(headers['x-request-id']); // 'abc-123'

// delete also works
delete headers['x-request-id'];

// 'in' operator checks for header existence
if ('authorization' in headers) {
  console.log('Auth header present');
}

All standard Headers methods (get, set, has, delete, append, forEach, entries, keys, values) work normally alongside property access. Method calls always bind to the real Headers target, so native brand checks pass.

Set-Cookie Handling

set-cookie headers require special treatment because they must not be folded into a single comma-separated value. RezoHeaders provides two methods:

getSetCookie()

Returns all Set-Cookie values as an array. Uses the native Headers.getSetCookie() where available (Node.js 20+), with a fallback that splits on commas:

const headers = new RezoHeaders({
  'set-cookie': ['session=abc; Path=/', 'theme=dark; Max-Age=3600'],
});

headers.getSetCookie();
// ['session=abc; Path=/', 'theme=dark; Max-Age=3600']

getAll(name)

Works like getSetCookie() but accepts any header name. Primarily used for set-cookie:

headers.getAll('set-cookie');
// ['session=abc; Path=/', 'theme=dark; Max-Age=3600']

Ordered Header Output

For stealth and browser fingerprinting, header order matters. Real browsers send headers in a specific order that anti-bot systems check. toOrderedObject() lets you control this:

const headers = new RezoHeaders({
  'accept': 'text/html',
  'user-agent': 'Mozilla/5.0...',
  'accept-language': 'en-US',
  'accept-encoding': 'gzip, br',
  'connection': 'keep-alive',
  'sec-fetch-mode': 'navigate',
});

// Chrome sends headers in this order:
const ordered = headers.toOrderedObject([
  'host',
  'connection',
  'sec-ch-ua',
  'sec-ch-ua-mobile',
  'sec-ch-ua-platform',
  'upgrade-insecure-requests',
  'user-agent',
  'accept',
  'sec-fetch-site',
  'sec-fetch-mode',
  'sec-fetch-user',
  'sec-fetch-dest',
  'accept-encoding',
  'accept-language',
]);

// Keys in `order` come first (in that order),
// remaining keys are appended at the end

This is used internally by the stealth module to match browser header fingerprints.

Conversion Methods

toObject(omit?)

Convert to a plain object. Optionally omit specific headers. Uses a null-prototype object to prevent prototype pollution:

const headers = new RezoHeaders({
  'content-type': 'application/json',
  'authorization': 'Bearer secret',
  'set-cookie': ['a=1', 'b=2'],
});

// All headers
headers.toObject();
// { 'content-type': 'application/json', 'authorization': 'Bearer secret', 'set-cookie': ['a=1', 'b=2'] }

// Omit sensitive headers
headers.toObject('authorization');
// { 'content-type': 'application/json', 'set-cookie': ['a=1', 'b=2'] }

// Omit multiple headers
headers.toObject(['authorization', 'set-cookie']);
// { 'content-type': 'application/json' }

set-cookie values are always returned as an array when multiple values exist.

toString()

Serialize as a multi-line string in key: value format:

headers.toString();
// "content-type: application/json
authorization: Bearer token"

toNative()

Create a new native Headers instance:

const native = headers.toNative();
// Returns a standard Headers object

toRaw()

Returns an array of [key, value] tuples:

headers.toRaw();
// [['content-type', 'application/json'], ['accept', 'text/html']]

toArray()

Returns an array of { key, value } objects:

headers.toArray();
// [{ key: 'content-type', value: 'application/json' }, ...]

toEntries()

Returns entries as [key, value][] (like Object.entries):

headers.toEntries();
// [['content-type', 'application/json'], ['accept', 'text/html']]

Convenience Methods

Chainable setters for common headers:

const headers = new RezoHeaders()
  .setContentType('application/json')
  .setAuthorization('Bearer my-token')
  .setUserAgent('MyApp/1.0');

Getters return string | undefined:

headers.getContentType();  // 'application/json'
headers.getUserAgent();    // 'MyApp/1.0'

Utility Properties

headers.size;        // Number of headers (counts via forEach)
headers.getKeys();   // ['content-type', 'accept', ...]
headers.getValues(); // ['application/json', 'text/html', ...]

HTTP/2 Pseudo-Headers

HTTP/2 responses include pseudo-headers (:status, :path, :authority) and may contain Symbol keys at runtime. The HTTP/2 adapter strips these internally before building the RezoResponse.headers — so by the time you read response.headers, the RezoHeaders instance only contains regular headers. You don’t need to do anything special on the consumer side.

Custom Inspect

RezoHeaders implements Symbol.for('nodejs.util.inspect.custom') for clean output in console.log:

console.log(headers);
// RezoHeaders { 'content-type': 'application/json', 'accept': 'text/html' }

Type Safety

RezoHeaders is typed against RezoHttpHeaders, which defines all known HTTP header names. The set(), get(), has(), and append() methods accept both typed header names and arbitrary strings:

headers.set('content-type', 'text/html');  // Typed header name
headers.set('x-custom', 'value');          // Arbitrary string