diff options
author | Florian Dold <florian.dold@gmail.com> | 2018-09-20 02:56:13 +0200 |
---|---|---|
committer | Florian Dold <florian.dold@gmail.com> | 2018-09-20 02:56:13 +0200 |
commit | bbff7403fbf46f9ad92240ac213df8d30ef31b64 (patch) | |
tree | c58400ec5124da1c7d56b01aea83309f80a56c3b /node_modules/whatwg-fetch/README.md | |
parent | 003fb34971cf63466184351b4db5f7c67df4f444 (diff) |
update packages
Diffstat (limited to 'node_modules/whatwg-fetch/README.md')
-rw-r--r-- | node_modules/whatwg-fetch/README.md | 282 |
1 files changed, 0 insertions, 282 deletions
diff --git a/node_modules/whatwg-fetch/README.md b/node_modules/whatwg-fetch/README.md deleted file mode 100644 index 328cb490e..000000000 --- a/node_modules/whatwg-fetch/README.md +++ /dev/null @@ -1,282 +0,0 @@ -# window.fetch polyfill - -The `fetch()` function is a Promise-based mechanism for programmatically making -web requests in the browser. This project is a polyfill that implements a subset -of the standard [Fetch specification][], enough to make `fetch` a viable -replacement for most uses of XMLHttpRequest in traditional web applications. - -This project adheres to the [Open Code of Conduct][]. By participating, you are -expected to uphold this code. - -## Table of Contents - -* [Read this first](#read-this-first) -* [Installation](#installation) -* [Usage](#usage) - * [HTML](#html) - * [JSON](#json) - * [Response metadata](#response-metadata) - * [Post form](#post-form) - * [Post JSON](#post-json) - * [File upload](#file-upload) - * [Caveats](#caveats) - * [Handling HTTP error statuses](#handling-http-error-statuses) - * [Sending cookies](#sending-cookies) - * [Receiving cookies](#receiving-cookies) - * [Obtaining the Response URL](#obtaining-the-response-url) -* [Browser Support](#browser-support) - -## Read this first - -* If you believe you found a bug with how `fetch` behaves in Chrome or Firefox, - please **avoid opening an issue in this repository**. This project is a - _polyfill_, and since Chrome and Firefox both implement the `window.fetch` - function natively, no code from this project actually takes any effect in - these browsers. See [Browser support](#browser-support) for detailed - information. - -* If you have trouble **making a request to another domain** (a different - subdomain or port number also constitutes as another domain), please - familiarize yourself with all the intricacies and limitations of [CORS][] - requests. Because CORS requires participation of the server by implementing - specific HTTP response headers, it is often nontrivial to set up or debug. - CORS is exclusively handled by the browser's internal mechanisms which this - polyfill cannot influence. - -* If you have trouble **maintaining the user's session** or [CSRF][] protection - through `fetch` requests, please ensure that you've read and understood the - [Sending cookies](#sending-cookies) section. - -* If this polyfill **doesn't work under Node.js environments**, that is expected, - because this project is meant for web browsers only. You should ensure that your - application doesn't try to package and run this on the server. - -* If you have an idea for a new feature of `fetch`, please understand that we - are only ever going to add features and APIs that are a part of the - [Fetch specification][]. You should **submit your feature requests** to the - [repository of the specification](https://github.com/whatwg/fetch/issues) - itself, rather than this repository. - -## Installation - -* `npm install whatwg-fetch --save`; or - -* `bower install fetch`. - -You will also need a Promise polyfill for [older browsers](http://caniuse.com/#feat=promises). -We recommend [taylorhakes/promise-polyfill](https://github.com/taylorhakes/promise-polyfill) -for its small size and Promises/A+ compatibility. - -For use with webpack, add this package in the `entry` configuration option -before your application entry point: - -```javascript -entry: ['whatwg-fetch', ...] -``` - -For Babel and ES2015+, make sure to import the file: - -```javascript -import 'whatwg-fetch' -``` - -## Usage - -For a more comprehensive API reference that this polyfill supports, refer to -https://github.github.io/fetch/. - -### HTML - -```javascript -fetch('/users.html') - .then(function(response) { - return response.text() - }).then(function(body) { - document.body.innerHTML = body - }) -``` - -### JSON - -```javascript -fetch('/users.json') - .then(function(response) { - return response.json() - }).then(function(json) { - console.log('parsed json', json) - }).catch(function(ex) { - console.log('parsing failed', ex) - }) -``` - -### Response metadata - -```javascript -fetch('/users.json').then(function(response) { - console.log(response.headers.get('Content-Type')) - console.log(response.headers.get('Date')) - console.log(response.status) - console.log(response.statusText) -}) -``` - -### Post form - -```javascript -var form = document.querySelector('form') - -fetch('/users', { - method: 'POST', - body: new FormData(form) -}) -``` - -### Post JSON - -```javascript -fetch('/users', { - method: 'POST', - headers: { - 'Content-Type': 'application/json' - }, - body: JSON.stringify({ - name: 'Hubot', - login: 'hubot', - }) -}) -``` - -### File upload - -```javascript -var input = document.querySelector('input[type="file"]') - -var data = new FormData() -data.append('file', input.files[0]) -data.append('user', 'hubot') - -fetch('/avatars', { - method: 'POST', - body: data -}) -``` - -### Caveats - -The `fetch` specification differs from `jQuery.ajax()` in mainly two ways that -bear keeping in mind: - -* The Promise returned from `fetch()` **won't reject on HTTP error status** - even if the response is an HTTP 404 or 500. Instead, it will resolve normally, - and it will only reject on network failure or if anything prevented the - request from completing. - -* By default, `fetch` **won't send or receive any cookies** from the server, - resulting in unauthenticated requests if the site relies on maintaining a user - session. See [Sending cookies](#sending-cookies) for how to opt into cookie - handling. - -#### Handling HTTP error statuses - -To have `fetch` Promise reject on HTTP error statuses, i.e. on any non-2xx -status, define a custom response handler: - -```javascript -function checkStatus(response) { - if (response.status >= 200 && response.status < 300) { - return response - } else { - var error = new Error(response.statusText) - error.response = response - throw error - } -} - -function parseJSON(response) { - return response.json() -} - -fetch('/users') - .then(checkStatus) - .then(parseJSON) - .then(function(data) { - console.log('request succeeded with JSON response', data) - }).catch(function(error) { - console.log('request failed', error) - }) -``` - -#### Sending cookies - -To automatically send cookies for the current domain, the `credentials` option -must be provided: - -```javascript -fetch('/users', { - credentials: 'same-origin' -}) -``` - -The "same-origin" value makes `fetch` behave similarly to XMLHttpRequest with -regards to cookies. Otherwise, cookies won't get sent, resulting in these -requests not preserving the authentication session. - -For [CORS][] requests, use the "include" value to allow sending credentials to -other domains: - -```javascript -fetch('https://example.com:1234/users', { - credentials: 'include' -}) -``` - -#### Receiving cookies - -As with XMLHttpRequest, the `Set-Cookie` response header returned from the -server is a [forbidden header name][] and therefore can't be programmatically -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`. - -Bear in mind that the default behavior of `fetch` is to ignore the `Set-Cookie` -header completely. To opt into accepting cookies from the server, you must use -the `credentials` option. - -#### Obtaining the Response URL - -Due to limitations of XMLHttpRequest, the `response.url` value might not be -reliable after HTTP redirects on older browsers. - -The solution is to configure the server to set the response HTTP header -`X-Request-URL` to the current URL after any redirect that might have happened. -It should be safe to set it unconditionally. - -``` ruby -# Ruby on Rails controller example -response.headers['X-Request-URL'] = request.url -``` - -This server workaround is necessary if you need reliable `response.url` in -Firefox < 32, Chrome < 37, Safari, or IE. - -## Browser Support - -- Chrome -- Firefox -- Safari 6.1+ -- Internet Explorer 10+ - -Note: modern browsers such as Chrome, Firefox, and Microsoft Edge contain native -implementations of `window.fetch`, therefore the code from this polyfill doesn't -have any effect on those browsers. If you believe you've encountered an error -with how `window.fetch` is implemented in any of these browsers, you should file -an issue with that browser vendor instead of this project. - - - [fetch specification]: https://fetch.spec.whatwg.org - [open code of conduct]: http://todogroup.org/opencodeofconduct/#fetch/opensource@github.com - [cors]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS - "Cross-origin resource sharing" - [csrf]: https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)_Prevention_Cheat_Sheet - "Cross-site request forgery" - [forbidden header name]: https://developer.mozilla.org/en-US/docs/Glossary/Forbidden_header_name |