mirror of
https://github.com/tenrok/axios.git
synced 2026-05-15 11:59:42 +03:00
chore(docs): added AxiosHeaders docs; (#5932)
This commit is contained in:
Dmitriy Mozgovoy
@@ -66,6 +66,7 @@
|
||||
- [HTML Form Posting](#-html-form-posting-browser)
|
||||
- [🆕 Progress capturing](#-progress-capturing)
|
||||
- [🆕 Rate limiting](#-progress-capturing)
|
||||
- [🆕 AxiosHeaders](#-axiosheaders)
|
||||
- [Semver](#semver)
|
||||
- [Promises](#promises)
|
||||
- [TypeScript](#typescript)
|
||||
@@ -1291,6 +1292,260 @@ const {data} = await axios.post(LOCAL_SERVER_URL, myBuffer, {
|
||||
});
|
||||
```
|
||||
|
||||
## 🆕 AxiosHeaders
|
||||
|
||||
Axios has its own `AxiosHeaders` class to manipulate headers using a Map-like API that guarantees caseless work.
|
||||
Although HTTP is case-insensitive in headers, Axios will retain the case of the original header for stylistic reasons
|
||||
and for a workaround when servers mistakenly consider the header's case.
|
||||
The old approach of directly manipulating headers object is still available, but deprecated and not recommended for future usage.
|
||||
|
||||
### Working with headers
|
||||
|
||||
An AxiosHeaders object instance can contain different types of internal values. that control setting and merging logic.
|
||||
The final headers object with string values is obtained by Axios by calling the `toJSON` method.
|
||||
|
||||
> Note: By JSON here we mean an object consisting only of string values intended to be sent over the network.
|
||||
|
||||
The header value can be one of the following types:
|
||||
- `string` - normal string value that will be sent to the server
|
||||
- `null` - skip header when rendering to JSON
|
||||
- `false` - skip header when rendering to JSON, additionally indicates that `set` method must be called with `rewrite` option set to `true`
|
||||
to overwrite this value (Axios uses this internally to allow users to opt out of installing certain headers like `User-Agent` or `Content-Type`)
|
||||
- `undefined` - value is not set
|
||||
|
||||
> Note: The header value is considered set if it is not equal to undefined.
|
||||
|
||||
The headers object is always initialized inside interceptors and transformers:
|
||||
|
||||
```ts
|
||||
axios.interceptors.request.use((request: InternalAxiosRequestConfig) => {
|
||||
request.headers.set('My-header', 'value');
|
||||
|
||||
request.headers.set({
|
||||
"My-set-header1": "my-set-value1",
|
||||
"My-set-header2": "my-set-value2"
|
||||
});
|
||||
|
||||
request.headers.set('User-Agent', false); // disable subsequent setting the header by Axios
|
||||
|
||||
request.headers.setContentType('text/plain');
|
||||
|
||||
request.headers['My-set-header2'] = 'newValue' // direct access is deprecated
|
||||
|
||||
return request;
|
||||
}
|
||||
);
|
||||
````
|
||||
|
||||
You can iterate over an `AxiosHeaders` instance using a `for...of` statement:
|
||||
|
||||
````js
|
||||
const headers = new AxiosHeaders({
|
||||
foo: '1',
|
||||
bar: '2',
|
||||
baz: '3'
|
||||
});
|
||||
|
||||
for(const [header, value] of headers) {
|
||||
console.log(header, value);
|
||||
}
|
||||
|
||||
// foo 1
|
||||
// bar 2
|
||||
// baz 3
|
||||
````
|
||||
|
||||
### new AxiosHeaders(headers?)
|
||||
|
||||
Constructs a new `AxiosHeaders` instance.
|
||||
|
||||
```
|
||||
constructor(headers?: RawAxiosHeaders | AxiosHeaders | string);
|
||||
```
|
||||
|
||||
If the headers object is a string, it will be parsed as RAW HTTP headers.
|
||||
|
||||
````js
|
||||
const headers = new AxiosHeaders(`
|
||||
Host: www.bing.com
|
||||
User-Agent: curl/7.54.0
|
||||
Accept: */*`);
|
||||
|
||||
console.log(headers);
|
||||
|
||||
// Object [AxiosHeaders] {
|
||||
// host: 'www.bing.com',
|
||||
// 'user-agent': 'curl/7.54.0',
|
||||
// accept: '*/*'
|
||||
// }
|
||||
````
|
||||
|
||||
### AxiosHeaders#set
|
||||
|
||||
```ts
|
||||
set(headerName, value: Axios, rewrite?: boolean);
|
||||
set(headerName, value, rewrite?: (this: AxiosHeaders, value: string, name: string, headers: RawAxiosHeaders) => boolean);
|
||||
set(headers?: RawAxiosHeaders | AxiosHeaders | string, rewrite?: boolean);
|
||||
```
|
||||
|
||||
The `rewrite` argument controls the overwriting behavior:
|
||||
- `false` - do not overwrite if header's value is set (is not `undefined`)
|
||||
- `undefined` (default) - overwrite the header unless its value is set to `false`
|
||||
- `true` - rewrite anyway
|
||||
|
||||
The option can also accept a user-defined function that determines whether the value should be overwritten or not.
|
||||
|
||||
Returns `this`.
|
||||
|
||||
### AxiosHeaders#get(header)
|
||||
|
||||
```
|
||||
get(headerName: string, matcher?: true | AxiosHeaderMatcher): AxiosHeaderValue;
|
||||
get(headerName: string, parser: RegExp): RegExpExecArray | null;
|
||||
````
|
||||
|
||||
Returns the internal value of the header. It can take an extra argument to parse the header's value with `RegExp.exec`,
|
||||
matcher function or internal key-value parser.
|
||||
|
||||
```ts
|
||||
const headers = new AxiosHeaders({
|
||||
'Content-Type': 'multipart/form-data; boundary=Asrf456BGe4h'
|
||||
});
|
||||
|
||||
console.log(headers.get('Content-Type'));
|
||||
// multipart/form-data; boundary=Asrf456BGe4h
|
||||
|
||||
console.log(headers.get('Content-Type', true)); // parse key-value pairs from a string separated with \s,;= delimiters:
|
||||
// [Object: null prototype] {
|
||||
// 'multipart/form-data': undefined,
|
||||
// boundary: 'Asrf456BGe4h'
|
||||
// }
|
||||
|
||||
|
||||
console.log(headers.get('Content-Type', (value, name, headers) => {
|
||||
return String(value).replace(/a/g, 'ZZZ');
|
||||
}));
|
||||
// multipZZZrt/form-dZZZtZZZ; boundZZZry=Asrf456BGe4h
|
||||
|
||||
console.log(headers.get('Content-Type', /boundary=(\w+)/)?.[0]);
|
||||
// boundary=Asrf456BGe4h
|
||||
|
||||
```
|
||||
|
||||
Returns the value of the header.
|
||||
|
||||
### AxiosHeaders#has(header, matcher?)
|
||||
|
||||
```
|
||||
has(header: string, matcher?: AxiosHeaderMatcher): boolean;
|
||||
```
|
||||
|
||||
Returns `true` if the header is set (has no `undefined` value).
|
||||
|
||||
### AxiosHeaders#delete(header, matcher?)
|
||||
|
||||
```
|
||||
delete(header: string | string[], matcher?: AxiosHeaderMatcher): boolean;
|
||||
```
|
||||
|
||||
Returns `true` if at least one header has been removed.
|
||||
|
||||
### AxiosHeaders#clear(matcher?)
|
||||
|
||||
```
|
||||
clear(matcher?: AxiosHeaderMatcher): boolean;
|
||||
```
|
||||
|
||||
Removes all headers.
|
||||
Unlike the `delete` method matcher, this optional matcher will be used to match against the header name rather than the value.
|
||||
|
||||
```ts
|
||||
const headers = new AxiosHeaders({
|
||||
'foo': '1',
|
||||
'x-foo': '2',
|
||||
'x-bar': '3',
|
||||
});
|
||||
|
||||
console.log(headers.clear(/^x-/)); // true
|
||||
|
||||
console.log(headers.toJSON()); // [Object: null prototype] { foo: '1' }
|
||||
```
|
||||
|
||||
Returns `true` if at least one header has been cleared.
|
||||
|
||||
### AxiosHeaders#normalize(format);
|
||||
|
||||
If the headers object was changed directly, it can have duplicates with the same name but in different cases.
|
||||
This method normalizes the headers object by combining duplicate keys into one.
|
||||
Axios uses this method internally after calling each interceptor.
|
||||
Set `format` to true for converting headers name to lowercase and capitalize the initial letters (`cOntEnt-type` => `Content-Type`)
|
||||
|
||||
```js
|
||||
const headers = new AxiosHeaders({
|
||||
'foo': '1',
|
||||
});
|
||||
|
||||
headers.Foo = '2';
|
||||
headers.FOO = '3';
|
||||
|
||||
console.log(headers.toJSON()); // [Object: null prototype] { foo: '1', Foo: '2', FOO: '3' }
|
||||
console.log(headers.normalize().toJSON()); // [Object: null prototype] { foo: '3' }
|
||||
console.log(headers.normalize(true).toJSON()); // [Object: null prototype] { Foo: '3' }
|
||||
```
|
||||
|
||||
Returns `this`.
|
||||
|
||||
### AxiosHeaders#concat(...targets)
|
||||
|
||||
```
|
||||
concat(...targets: Array<AxiosHeaders | RawAxiosHeaders | string | undefined | null>): AxiosHeaders;
|
||||
```
|
||||
|
||||
Merges the instance with targets into a new `AxiosHeaders` instance. If the target is a string, it will be parsed as RAW HTTP headers.
|
||||
|
||||
Returns a new `AxiosHeaders` instance.
|
||||
|
||||
### AxiosHeaders#toJSON(asStrings?)
|
||||
|
||||
````
|
||||
toJSON(asStrings?: boolean): RawAxiosHeaders;
|
||||
````
|
||||
|
||||
Resolve all internal headers values into a new null prototype object.
|
||||
Set `asStrings` to true to resolve arrays as a string containing all elements, separated by commas.
|
||||
|
||||
### AxiosHeaders.from(thing?)
|
||||
|
||||
````
|
||||
from(thing?: AxiosHeaders | RawAxiosHeaders | string): AxiosHeaders;
|
||||
````
|
||||
|
||||
Returns a new `AxiosHeaders` instance created from the raw headers passed in,
|
||||
or simply returns the given headers object if it's an `AxiosHeaders` instance.
|
||||
|
||||
### AxiosHeaders.concat(...targets)
|
||||
|
||||
````
|
||||
concat(...targets: Array<AxiosHeaders | RawAxiosHeaders | string | undefined | null>): AxiosHeaders;
|
||||
````
|
||||
|
||||
Returns a new `AxiosHeaders` instance created by merging the target objects.
|
||||
|
||||
### Shortcuts
|
||||
|
||||
The following shortcuts are available:
|
||||
|
||||
- `setContentType`, `getContentType`, `hasContentType`
|
||||
|
||||
- `setContentLength`, `getContentLength`, `hasContentLength`
|
||||
|
||||
- `setAccept`, `getAccept`, `hasAccept`
|
||||
|
||||
- `setUserAgent`, `getUserAgent`, `hasUserAgent`
|
||||
|
||||
- `setContentEncoding`, `getContentEncoding`, `hasContentEncoding`
|
||||
|
||||
|
||||
## Semver
|
||||
|
||||
Until axios reaches a `1.0` release, breaking changes will be released with a new minor version. For example `0.5.1`, and `0.5.4` will have the same API, but `0.6.0` will have breaking changes.
|
||||
|
||||
Reference in New Issue
Block a user