Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document more common pitfalls in the README #734

Merged
merged 2 commits into from Nov 13, 2019
Merged

Document more common pitfalls in the README #734

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9a0bce2
Document more caveats
mislav Oct 31, 2019
1364c85
Fix ToC
mislav Oct 31, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
29 changes: 20 additions & 9 deletions README.md
View file
Open in desktop
Expand Up @@ -21,6 +21,7 @@ replacement for most uses of XMLHttpRequest in traditional web applications.
* [Handling HTTP error statuses](#handling-http-error-statuses)
* [Sending cookies](#sending-cookies)
* [Receiving cookies](#receiving-cookies)
* [Redirect modes](#redirect-modes)
* [Obtaining the Response URL](#obtaining-the-response-url)
* [Aborting requests](#aborting-requests)
* [Browser Support](#browser-support)
Expand Down Expand Up @@ -188,6 +189,10 @@ fetch('/avatars', {
cookies, always supply the `credentials: 'same-origin'` option instead of
relying on the default. See [Sending cookies](#sending-cookies).

* Not all Fetch standard options are supported in this polyfill. For instance,
[`redirect`](#redirect-modes) and
[`cache`](https://github.github.io/fetch/#caveats) directives are ignored.

#### Handling HTTP error statuses

To have `fetch` Promise reject on HTTP error statuses, i.e. on any non-2xx
Expand Down Expand Up @@ -229,15 +234,6 @@ fetch('https://example.com:1234/users', {
})
```

To disable sending or receiving cookies for requests to any domain, including
the current one, use the "omit" value:

```javascript
fetch('/users', {
credentials: 'omit'
})
```

The default value for `credentials` is "same-origin".

The default for `credentials` wasn't always the same, though. The following
Expand All @@ -258,6 +254,12 @@ fetch('/users', {
})
```

Note: due to [limitations of
XMLHttpRequest](https://github.com/github/fetch/pull/56#issuecomment-68835992),
using `credentials: 'omit'` is not respected for same domains in browsers where
this polyfill is active. Cookies will always be sent to same domains in older
browsers.

#### Receiving cookies

As with XMLHttpRequest, the `Set-Cookie` response header returned from the
Expand All @@ -266,6 +268,15 @@ read with `response.headers.get()`. Instead, it's the browser's responsibility
to handle new cookies being set (if applicable to the current URL). Unless they
are HTTP-only, new cookies will be available through `document.cookie`.

#### Redirect modes

The Fetch specification defines these values for [the `redirect`
option](https://fetch.spec.whatwg.org/#concept-request-redirect-mode): "follow"
(the default), "error", and "manual".

Due to limitations of XMLHttpRequest, only the "follow" mode is available in
browsers where this polyfill is active.

#### Obtaining the Response URL

Due to limitations of XMLHttpRequest, the `response.url` value might not be
Expand Down