2016-12-12 13:50:05 -08:00
|
|
|
# Upgrade to node-fetch v2
|
|
|
|
|
|
|
|
node-fetch v2 brings about many changes that increase the compliance of
|
2016-12-14 13:51:43 -08:00
|
|
|
WHATWG's [Fetch Standard][whatwg-fetch]. However, many of these changes meant
|
|
|
|
that apps written for node-fetch v1 needs to be updated to work with node-fetch
|
|
|
|
v2 and be conformant with the Fetch Standard.
|
2016-12-12 13:50:05 -08:00
|
|
|
|
|
|
|
## `.text()` no longer tries to detect encoding
|
|
|
|
|
2016-12-14 13:51:43 -08:00
|
|
|
In v1, `response.text()` attempts to guess the text encoding of the input
|
2016-12-12 13:50:05 -08:00
|
|
|
material and decode it for the user. However, it runs counter to the Fetch
|
|
|
|
Standard which demands `.text()` to always use UTF-8.
|
|
|
|
|
|
|
|
In "response" to that, we have changed `.text()` to use UTF-8. A new function
|
|
|
|
**`response.textConverted()`** is created that maintains the behavior of
|
|
|
|
`.text()` last year.
|
|
|
|
|
|
|
|
## Internal methods hidden
|
|
|
|
|
2016-12-14 13:51:43 -08:00
|
|
|
In v1, the user can access internal methods such as `_clone()`, `_decode()`,
|
|
|
|
and `_convert()` on the `response` object. While these methods should never
|
|
|
|
have been used, node-fetch v2 makes these functions completely inaccessible.
|
|
|
|
If your app makes use of these functions, it may break when upgrading to v2.
|
2016-12-12 13:50:05 -08:00
|
|
|
|
|
|
|
If you have a use case that requires these methods to be available, feel free
|
|
|
|
to file an issue and we will be happy to help you solve the problem.
|
|
|
|
|
|
|
|
## Headers
|
|
|
|
|
2016-12-14 13:51:43 -08:00
|
|
|
The main goal we have for the `Headers` class in v2 is to make it completely
|
2017-01-23 07:54:28 -08:00
|
|
|
spec-compliant.
|
2016-12-12 13:50:05 -08:00
|
|
|
|
|
|
|
```js
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
2017-01-23 07:54:28 -08:00
|
|
|
// `get()` now returns **all** headers, joined by a comma, instead of only the
|
|
|
|
// first one. Its original behavior can be emulated using
|
|
|
|
// `get().split(',')[0]`.
|
|
|
|
|
2016-12-12 13:50:05 -08:00
|
|
|
const headers = new Headers({
|
|
|
|
'Abc': 'string',
|
|
|
|
'Multi': [ 'header1', 'header2' ]
|
|
|
|
});
|
|
|
|
|
|
|
|
// before after
|
2017-01-23 07:54:28 -08:00
|
|
|
headers.get('Abc') => headers.get('Abc') =>
|
|
|
|
'string' 'string'
|
2016-12-12 13:50:05 -08:00
|
|
|
headers.get('Multi') => headers.get('Multi') =>
|
|
|
|
'header1'; 'header1,header2';
|
2017-01-23 07:54:28 -08:00
|
|
|
headers.get('Multi').split(',')[0] =>
|
|
|
|
'header1';
|
|
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
// `getAll()` is removed. Its behavior in v1 can be emulated with
|
|
|
|
// `get().split(',')`.
|
|
|
|
|
|
|
|
const headers = new Headers({
|
|
|
|
'Abc': 'string',
|
|
|
|
'Multi': [ 'header1', 'header2' ]
|
|
|
|
});
|
|
|
|
|
|
|
|
// before after
|
2016-12-12 13:50:05 -08:00
|
|
|
headers.getAll('Multi') => headers.getAll('Multi') =>
|
2017-01-23 07:54:28 -08:00
|
|
|
[ 'header1', 'header2' ]; throws ReferenceError
|
|
|
|
headers.get('Multi').split(',') =>
|
|
|
|
[ 'header1', 'header2' ];
|
2016-12-12 13:50:05 -08:00
|
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
// All method parameters are now stringified.
|
|
|
|
const headers = new Headers();
|
|
|
|
headers.set('null-header', null);
|
|
|
|
headers.set('undefined', undefined);
|
|
|
|
|
|
|
|
// before after
|
|
|
|
headers.get('null-header') headers.get('null-header')
|
|
|
|
=> null => 'null'
|
|
|
|
headers.get(undefined) headers.get(undefined)
|
|
|
|
=> throws => 'undefined'
|
|
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
// Invalid HTTP header names and values are now rejected outright.
|
|
|
|
const headers = new Headers();
|
|
|
|
headers.set('Héy', 'ok'); // now throws
|
|
|
|
headers.get('Héy'); // now throws
|
|
|
|
new Headers({ 'Héy': 'ok' }); // now throws
|
|
|
|
```
|
|
|
|
|
|
|
|
## 0.10.x support dropped
|
|
|
|
|
|
|
|
If you are still using Node.js v0.10, upgrade ASAP. Not only has Node.js
|
|
|
|
dropped support for that release branch, it has become too much work for us to
|
2016-12-14 13:51:43 -08:00
|
|
|
maintain. Therefore, we have dropped official support for v0.10.
|
|
|
|
|
|
|
|
That being said, node-fetch may still work with v0.10, but as we are not
|
|
|
|
actively trying to support that version, it is in the user's best interest to
|
|
|
|
upgrade.
|
|
|
|
|
|
|
|
[whatwg-fetch]: https://fetch.spec.whatwg.org/
|
|
|
|
[#181]: https://github.com/bitinn/node-fetch/issues/181
|