asher- / js-browser-headers

Compatibility Layer for the Headers class

browser-headers

Compatibility Layer for the Headers class

The Headers class defined in the fetch spec has been implemented slightly differently across browser vendors at the time of writing (Feb 2017).

This package intends to provide a wrapper for the Headers class to ensure a consistent API and provides headers parsing from CLRF-delimited strings.

This package is written in TypeScript, but is designed to be used just as easily by JavaScript projects.

Installation

via npm:

$ npm install browser-headers

Browser Support

This library is tested against Chrome, Safari, Firefox, Opera, Edge, IE 10 and IE 9.

API

import BrowserHeaders from 'browser-headers';

const headers = new BrowserHeaders({
  "content-type": "application/json",
  "my-header": ["value-one","value-two"]
});

headers.forEach((key, values) => {
  console.log(key, values);
});

// Output:
// "content-type", ["application/json"]
// "my-header", ["value-one","value-two"]

The BrowserHeaders class has the following methods:

constructor(init: Headers | {[key: string]: string|string[]} | Map<string,string|string[]> | string | BrowserHeaders, options: {splitValues: boolean}): string[]

init can be one of:

• An instance of Headers
• A CLRF-delimited string (e.g. key-a: one\r\nkey-b: two)
• An instance of BrowserHeaders
• An object consisting of string->(string|string[]) (e.g. {"key-a":["one","two"],"key-b":"three"})
• A Map<string, string|string[]>

The constructor takes an additional optional options parameter of { splitValues: boolean = false }, where splitValues defines whether the header values should be split by comma (,) into separate strings - this is useful to unify the .append functionality of Headers implementations (see the warning at the end of this README). splitValues should be used with caution and defaults to false because it might split what is actually a single logical value that contained a ,.

.get(key: string): string[]

Returns all of the values for that header key as an array

.forEach(callback: (key: string, values: string[]) => void): void

Invokes the provided callback with each key and it's associated values as an array

.set(key: string, values: string|string[]): void

Overwrites the key with the value(s) specified.

.append(key: string, values: string|string[]): void

Appends the value(s) to specified key.

.delete(key: string, value: string): void

If the value is specified: Removes the specified value from the key if it is present.

Otherwise: Removes all values for the key if it is present.

.has(key: string, value?: string): boolean

If the value is specified: Returns true if the key contains the corresponding value.

Otherwise: Returns true if the key has at least one value.

.appendFromString(str: string): void

Appends the headers defined in the provided CLRF-delimited string (e.g. key-a: one\r\nkey-b: two)

.toHeaders(): Headers

Returns an instance of the browser's Headers class. This will throw an exception if the current browser does not have the Headers class.

Warning about .append in native Headers

The .append function of the Headers class differs significantly between browsers.

Some browsers concatenate the values with ", " or just "," and others actually maintain the individual values such that they can return later return an array. There is a constructor option (see above: splitValues) that can be enabled to attempt to parse these concatenated strings back into individual values.

const headers = new Headers();
headers.append("key-A", "one");
headers.append("key-A", "two");
const keyA = headers.get("key-A"); // or .getAll depending on the browser 
console.log(typeof keyA);
console.log(keyA);

// Output in Edge 14:
// string
// one, two

// Output in Safari 10:
// string
// one,two

// Output in Chrome 56:
// object
// ["one", "two"]