forked from projectmoon/tenebrous-dicebot
121 lines
4.6 KiB
Markdown
121 lines
4.6 KiB
Markdown
# browser-headers
|
|
> Compatibility Layer for the Headers class
|
|
|
|
[](https://travis-ci.org/improbable-eng/js-browser-headers)
|
|
|
|
[](https://www.npmjs.com/package/browser-headers)
|
|
[](LICENSE)
|
|
|
|
|
|
The [Headers](https://fetch.spec.whatwg.org/#headers-class) class defined in the [fetch spec](https://fetch.spec.whatwg.org/) 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:
|
|
|
|
```bash
|
|
$ npm install browser-headers
|
|
```
|
|
|
|
## Browser Support
|
|
This library is tested against Chrome, Safari, Firefox, Opera, Edge, IE 10 and IE 9.
|
|
|
|
## API
|
|
|
|
```js
|
|
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.
|
|
```js
|
|
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"]
|
|
```
|