Slightly expand upgrade guide

This commit is contained in:
Timothy Gu 2016-12-14 13:51:43 -08:00
parent 29e9f5eef6
commit 01bf40d5a4
1 changed files with 26 additions and 13 deletions

View File

@ -1,13 +1,13 @@
# Upgrade to node-fetch v2
node-fetch v2 brings about many changes that increase the compliance of
WHATWG's Fetch Standard. 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.
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.
## `.text()` no longer tries to detect encoding
Currently, `response.text()` attempts to guess the text encoding of the input
In v1, `response.text()` attempts to guess the text encoding of the input
material and decode it for the user. However, it runs counter to the Fetch
Standard which demands `.text()` to always use UTF-8.
@ -17,22 +17,29 @@ In "response" to that, we have changed `.text()` to use UTF-8. A new function
## Internal methods hidden
Currently, 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, and may break your app.
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.
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
The `Headers` class has gotten a lot of updates to make it spec-compliant.
The main goal we have for the `Headers` class in v2 is to make it completely
spec-compliant. However, due to changes in the Fetch Standard itself, total
spec compliance would mean incompatibility with all current major browser
implementations.
Therefore, in v2, only a limited set of changes was applied to preserve
compatibility with browsers by default. See [#181] for more information on why
a feature is enabled or disabled.
```js
//////////////////////////////////////////////////////////////////////////////
// If you are using an object as the initializer, all arrays will be reduced
// to a string.
// If you are using an object as the initializer, all values will be
// stringified. For arrays, the members will be joined with a comma.
const headers = new Headers({
'Abc': 'string',
'Multi': [ 'header1', 'header2' ]
@ -78,5 +85,11 @@ new Headers({ 'Héy': 'ok' }); // now throws
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
maintain. Therefore, we have dropped official support for v0.10 (it may still
work but don't expect them to do so).
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