HarshvardhanCn01/Voice-Assistant
0
1node-fetch2==========3 4[![npm version][npm-image]][npm-url]5[![build status][travis-image]][travis-url]6[![coverage status][codecov-image]][codecov-url]7[![install size][install-size-image]][install-size-url]8[![Discord][discord-image]][discord-url]9 10A light-weight module that brings `window.fetch` to Node.js11 12(We are looking for [v2 maintainers and collaborators](https://github.com/bitinn/node-fetch/issues/567))13 14[![Backers][opencollective-image]][opencollective-url]15 16<!-- TOC -->17 18- [Motivation](#motivation)19- [Features](#features)20- [Difference from client-side fetch](#difference-from-client-side-fetch)21- [Installation](#installation)22- [Loading and configuring the module](#loading-and-configuring-the-module)23- [Common Usage](#common-usage)24 - [Plain text or HTML](#plain-text-or-html)25 - [JSON](#json)26 - [Simple Post](#simple-post)27 - [Post with JSON](#post-with-json)28 - [Post with form parameters](#post-with-form-parameters)29 - [Handling exceptions](#handling-exceptions)30 - [Handling client and server errors](#handling-client-and-server-errors)31- [Advanced Usage](#advanced-usage)32 - [Streams](#streams)33 - [Buffer](#buffer)34 - [Accessing Headers and other Meta data](#accessing-headers-and-other-meta-data)35 - [Extract Set-Cookie Header](#extract-set-cookie-header)36 - [Post data using a file stream](#post-data-using-a-file-stream)37 - [Post with form-data (detect multipart)](#post-with-form-data-detect-multipart)38 - [Request cancellation with AbortSignal](#request-cancellation-with-abortsignal)39- [API](#api)40 - [fetch(url[, options])](#fetchurl-options)41 - [Options](#options)42 - [Class: Request](#class-request)43 - [Class: Response](#class-response)44 - [Class: Headers](#class-headers)45 - [Interface: Body](#interface-body)46 - [Class: FetchError](#class-fetcherror)47- [License](#license)48- [Acknowledgement](#acknowledgement)49 50<!-- /TOC -->51 52## Motivation53 54Instead of implementing `XMLHttpRequest` in Node.js to run browser-specific [Fetch polyfill](https://github.com/github/fetch), why not go from native `http` to `fetch` API directly? Hence, `node-fetch`, minimal code for a `window.fetch` compatible API on Node.js runtime.55 56See Matt Andrews' [isomorphic-fetch](https://github.com/matthew-andrews/isomorphic-fetch) or Leonardo Quixada's [cross-fetch](https://github.com/lquixada/cross-fetch) for isomorphic usage (exports `node-fetch` for server-side, `whatwg-fetch` for client-side).57 58## Features59 60- Stay consistent with `window.fetch` API.61- Make conscious trade-off when following [WHATWG fetch spec][whatwg-fetch] and [stream spec](https://streams.spec.whatwg.org/) implementation details, document known differences.62- Use native promise but allow substituting it with [insert your favorite promise library].63- Use native Node streams for body on both request and response.64- Decode content encoding (gzip/deflate) properly and convert string output (such as `res.text()` and `res.json()`) to UTF-8 automatically.65- Useful extensions such as timeout, redirect limit, response size limit, [explicit errors](ERROR-HANDLING.md) for troubleshooting.66 67## Difference from client-side fetch68 69- See [Known Differences](LIMITS.md) for details.70- If you happen to use a missing feature that `window.fetch` offers, feel free to open an issue.71- Pull requests are welcomed too!72 73## Installation74 75Current stable release (`2.x`)76 77```sh78$ npm install node-fetch79```80 81## Loading and configuring the module82We suggest you load the module via `require` until the stabilization of ES modules in node:83```js84const fetch = require('node-fetch');85```86 87If you are using a Promise library other than native, set it through `fetch.Promise`:88```js89const Bluebird = require('bluebird');90 91fetch.Promise = Bluebird;92```93 94## Common Usage95 96NOTE: The documentation below is up-to-date with `2.x` releases; see the [`1.x` readme](https://github.com/bitinn/node-fetch/blob/1.x/README.md), [changelog](https://github.com/bitinn/node-fetch/blob/1.x/CHANGELOG.md) and [2.x upgrade guide](UPGRADE-GUIDE.md) for the differences.97 98#### Plain text or HTML99```js100fetch('https://github.com/')101 .then(res => res.text())102 .then(body => console.log(body));103```104 105#### JSON106 107```js108 109fetch('https://api.github.com/users/github')110 .then(res => res.json())111 .then(json => console.log(json));112```113 114#### Simple Post115```js116fetch('https://httpbin.org/post', { method: 'POST', body: 'a=1' })117 .then(res => res.json()) // expecting a json response118 .then(json => console.log(json));119```120 121#### Post with JSON122 123```js124const body = { a: 1 };125 126fetch('https://httpbin.org/post', {127 method: 'post',128 body: JSON.stringify(body),129 headers: { 'Content-Type': 'application/json' },130 })131 .then(res => res.json())132 .then(json => console.log(json));133```134 135#### Post with form parameters136`URLSearchParams` is available in Node.js as of v7.5.0. See [official documentation](https://nodejs.org/api/url.html#url_class_urlsearchparams) for more usage methods.137 138NOTE: The `Content-Type` header is only set automatically to `x-www-form-urlencoded` when an instance of `URLSearchParams` is given as such:139 140```js141const { URLSearchParams } = require('url');142 143const params = new URLSearchParams();144params.append('a', 1);145 146fetch('https://httpbin.org/post', { method: 'POST', body: params })147 .then(res => res.json())148 .then(json => console.log(json));149```150 151#### Handling exceptions152NOTE: 3xx-5xx responses are *NOT* exceptions and should be handled in `then()`; see the next section for more information.153 154Adding a catch to the fetch promise chain will catch *all* exceptions, such as errors originating from node core libraries, network errors and operational errors, which are instances of FetchError. See the [error handling document](ERROR-HANDLING.md) for more details.155 156```js157fetch('https://domain.invalid/')158 .catch(err => console.error(err));159```160 161#### Handling client and server errors162It is common to create a helper function to check that the response contains no client (4xx) or server (5xx) error responses:163 164```js165function checkStatus(res) {166 if (res.ok) { // res.status >= 200 && res.status < 300167 return res;168 } else {169 throw MyCustomError(res.statusText);170 }171}172 173fetch('https://httpbin.org/status/400')174 .then(checkStatus)175 .then(res => console.log('will not get here...'))176```177 178## Advanced Usage179 180#### Streams181The "Node.js way" is to use streams when possible:182 183```js184fetch('https://assets-cdn.github.com/images/modules/logos_page/Octocat.png')185 .then(res => {186 const dest = fs.createWriteStream('./octocat.png');187 res.body.pipe(dest);188 });189```190 191In Node.js 14 you can also use async iterators to read `body`; however, be careful to catch192errors -- the longer a response runs, the more likely it is to encounter an error.193 194```js195const fetch = require('node-fetch');196const response = await fetch('https://httpbin.org/stream/3');197try {198 for await (const chunk of response.body) {199 console.dir(JSON.parse(chunk.toString()));200 }201} catch (err) {202 console.error(err.stack);203}204```205 206In Node.js 12 you can also use async iterators to read `body`; however, async iterators with streams207did not mature until Node.js 14, so you need to do some extra work to ensure you handle errors208directly from the stream and wait on it response to fully close.209 210```js211const fetch = require('node-fetch');212const read = async body => {213 let error;214 body.on('error', err => {215 error = err;216 });217 for await (const chunk of body) {218 console.dir(JSON.parse(chunk.toString()));219 }220 return new Promise((resolve, reject) => {221 body.on('close', () => {222 error ? reject(error) : resolve();223 });224 });225};226try {227 const response = await fetch('https://httpbin.org/stream/3');228 await read(response.body);229} catch (err) {230 console.error(err.stack);231}232```233 234#### Buffer235If you prefer to cache binary data in full, use buffer(). (NOTE: `buffer()` is a `node-fetch`-only API)236 237```js238const fileType = require('file-type');239 240fetch('https://assets-cdn.github.com/images/modules/logos_page/Octocat.png')241 .then(res => res.buffer())242 .then(buffer => fileType(buffer))243 .then(type => { /* ... */ });244```245 246#### Accessing Headers and other Meta data247```js248fetch('https://github.com/')249 .then(res => {250 console.log(res.ok);251 console.log(res.status);252 console.log(res.statusText);253 console.log(res.headers.raw());254 console.log(res.headers.get('content-type'));255 });256```257 258#### Extract Set-Cookie Header259 260Unlike browsers, you can access raw `Set-Cookie` headers manually using `Headers.raw()`. This is a `node-fetch` only API.261 262```js263fetch(url).then(res => {264 // returns an array of values, instead of a string of comma-separated values265 console.log(res.headers.raw()['set-cookie']);266});267```268 269#### Post data using a file stream270 271```js272const { createReadStream } = require('fs');273 274const stream = createReadStream('input.txt');275 276fetch('https://httpbin.org/post', { method: 'POST', body: stream })277 .then(res => res.json())278 .then(json => console.log(json));279```280 281#### Post with form-data (detect multipart)282 283```js284const FormData = require('form-data');285 286const form = new FormData();287form.append('a', 1);288 289fetch('https://httpbin.org/post', { method: 'POST', body: form })290 .then(res => res.json())291 .then(json => console.log(json));292 293// OR, using custom headers294// NOTE: getHeaders() is non-standard API295 296const form = new FormData();297form.append('a', 1);298 299const options = {300 method: 'POST',301 body: form,302 headers: form.getHeaders()303}304 305fetch('https://httpbin.org/post', options)306 .then(res => res.json())307 .then(json => console.log(json));308```309 310#### Request cancellation with AbortSignal311 312> NOTE: You may cancel streamed requests only on Node >= v8.0.0313 314You may cancel requests with `AbortController`. A suggested implementation is [`abort-controller`](https://www.npmjs.com/package/abort-controller).315 316An example of timing out a request after 150ms could be achieved as the following:317 318```js319import AbortController from 'abort-controller';320 321const controller = new AbortController();322const timeout = setTimeout(323 () => { controller.abort(); },324 150,325);326 327fetch(url, { signal: controller.signal })328 .then(res => res.json())329 .then(330 data => {331 useData(data)332 },333 err => {334 if (err.name === 'AbortError') {335 // request was aborted336 }337 },338 )339 .finally(() => {340 clearTimeout(timeout);341 });342```343 344See [test cases](https://github.com/bitinn/node-fetch/blob/master/test/test.js) for more examples.345 346 347## API348 349### fetch(url[, options])350 351- `url` A string representing the URL for fetching352- `options` [Options](#fetch-options) for the HTTP(S) request353- Returns: <code>Promise<[Response](#class-response)></code>354 355Perform an HTTP(S) fetch.356 357`url` should be an absolute url, such as `https://example.com/`. A path-relative URL (`/file/under/root`) or protocol-relative URL (`//can-be-http-or-https.com/`) will result in a rejected `Promise`.358 359<a id="fetch-options"></a>360### Options361 362The default values are shown after each option key.363 364```js365{366 // These properties are part of the Fetch Standard367 method: 'GET',368 headers: {}, // request headers. format is the identical to that accepted by the Headers constructor (see below)369 body: null, // request body. can be null, a string, a Buffer, a Blob, or a Node.js Readable stream370 redirect: 'follow', // set to `manual` to extract redirect headers, `error` to reject redirect371 signal: null, // pass an instance of AbortSignal to optionally abort requests372 373 // The following properties are node-fetch extensions374 follow: 20, // maximum redirect count. 0 to not follow redirect375 timeout: 0, // req/res timeout in ms, it resets on redirect. 0 to disable (OS limit applies). Signal is recommended instead.376 compress: true, // support gzip/deflate content encoding. false to disable377 size: 0, // maximum response body size in bytes. 0 to disable378 agent: null // http(s).Agent instance or function that returns an instance (see below)379}380```381 382##### Default Headers383 384If no values are set, the following request headers will be sent automatically:385 386Header | Value387------------------- | --------------------------------------------------------388`Accept-Encoding` | `gzip,deflate` _(when `options.compress === true`)_389`Accept` | `*/*`390`Content-Length` | _(automatically calculated, if possible)_391`Transfer-Encoding` | `chunked` _(when `req.body` is a stream)_392`User-Agent` | `node-fetch/1.0 (+https://github.com/bitinn/node-fetch)`393 394Note: when `body` is a `Stream`, `Content-Length` is not set automatically.395 396##### Custom Agent397 398The `agent` option allows you to specify networking related options which are out of the scope of Fetch, including and not limited to the following:399 400- Support self-signed certificate401- Use only IPv4 or IPv6402- Custom DNS Lookup403 404See [`http.Agent`](https://nodejs.org/api/http.html#http_new_agent_options) for more information.405 406If no agent is specified, the default agent provided by Node.js is used. Note that [this changed in Node.js 19](https://github.com/nodejs/node/blob/4267b92604ad78584244488e7f7508a690cb80d0/lib/_http_agent.js#L564) to have `keepalive` true by default. If you wish to enable `keepalive` in an earlier version of Node.js, you can override the agent as per the following code sample. 407 408In addition, the `agent` option accepts a function that returns `http`(s)`.Agent` instance given current [URL](https://nodejs.org/api/url.html), this is useful during a redirection chain across HTTP and HTTPS protocol.409 410```js411const httpAgent = new http.Agent({412 keepAlive: true413});414const httpsAgent = new https.Agent({415 keepAlive: true416});417 418const options = {419 agent: function (_parsedURL) {420 if (_parsedURL.protocol == 'http:') {421 return httpAgent;422 } else {423 return httpsAgent;424 }425 }426}427```428 429<a id="class-request"></a>430### Class: Request431 432An HTTP(S) request containing information about URL, method, headers, and the body. This class implements the [Body](#iface-body) interface.433 434Due to the nature of Node.js, the following properties are not implemented at this moment:435 436- `type`437- `destination`438- `referrer`439- `referrerPolicy`440- `mode`441- `credentials`442- `cache`443- `integrity`444- `keepalive`445 446The following node-fetch extension properties are provided:447 448- `follow`449- `compress`450- `counter`451- `agent`452 453See [options](#fetch-options) for exact meaning of these extensions.454 455#### new Request(input[, options])456 457<small>*(spec-compliant)*</small>458 459- `input` A string representing a URL, or another `Request` (which will be cloned)460- `options` [Options][#fetch-options] for the HTTP(S) request461 462Constructs a new `Request` object. The constructor is identical to that in the [browser](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request).463 464In most cases, directly `fetch(url, options)` is simpler than creating a `Request` object.465 466<a id="class-response"></a>467### Class: Response468 469An HTTP(S) response. This class implements the [Body](#iface-body) interface.470 471The following properties are not implemented in node-fetch at this moment:472 473- `Response.error()`474- `Response.redirect()`475- `type`476- `trailer`477 478#### new Response([body[, options]])479 480<small>*(spec-compliant)*</small>481 482- `body` A `String` or [`Readable` stream][node-readable]483- `options` A [`ResponseInit`][response-init] options dictionary484 485Constructs a new `Response` object. The constructor is identical to that in the [browser](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response).486 487Because Node.js does not implement service workers (for which this class was designed), one rarely has to construct a `Response` directly.488 489#### response.ok490 491<small>*(spec-compliant)*</small>492 493Convenience property representing if the request ended normally. Will evaluate to true if the response status was greater than or equal to 200 but smaller than 300.494 495#### response.redirected496 497<small>*(spec-compliant)*</small>498 499Convenience property representing if the request has been redirected at least once. Will evaluate to true if the internal redirect counter is greater than 0.500 501<a id="class-headers"></a>502### Class: Headers503 504This class allows manipulating and iterating over a set of HTTP headers. All methods specified in the [Fetch Standard][whatwg-fetch] are implemented.505 506#### new Headers([init])507 508<small>*(spec-compliant)*</small>509 510- `init` Optional argument to pre-fill the `Headers` object511 512Construct a new `Headers` object. `init` can be either `null`, a `Headers` object, an key-value map object or any iterable object.513 514```js515// Example adapted from https://fetch.spec.whatwg.org/#example-headers-class516 517const meta = {518 'Content-Type': 'text/xml',519 'Breaking-Bad': '<3'520};521const headers = new Headers(meta);522 523// The above is equivalent to524const meta = [525 [ 'Content-Type', 'text/xml' ],526 [ 'Breaking-Bad', '<3' ]527];528const headers = new Headers(meta);529 530// You can in fact use any iterable objects, like a Map or even another Headers531const meta = new Map();532meta.set('Content-Type', 'text/xml');533meta.set('Breaking-Bad', '<3');534const headers = new Headers(meta);535const copyOfHeaders = new Headers(headers);536```537 538<a id="iface-body"></a>539### Interface: Body540 541`Body` is an abstract interface with methods that are applicable to both `Request` and `Response` classes.542 543The following methods are not yet implemented in node-fetch at this moment:544 545- `formData()`546 547#### body.body548 549<small>*(deviation from spec)*</small>550 551* Node.js [`Readable` stream][node-readable]552 553Data are encapsulated in the `Body` object. Note that while the [Fetch Standard][whatwg-fetch] requires the property to always be a WHATWG `ReadableStream`, in node-fetch it is a Node.js [`Readable` stream][node-readable].554 555#### body.bodyUsed556 557<small>*(spec-compliant)*</small>558 559* `Boolean`560 561A boolean property for if this body has been consumed. Per the specs, a consumed body cannot be used again.562 563#### body.arrayBuffer()564#### body.blob()565#### body.json()566#### body.text()567 568<small>*(spec-compliant)*</small>569 570* Returns: <code>Promise</code>571 572Consume the body and return a promise that will resolve to one of these formats.573 574#### body.buffer()575 576<small>*(node-fetch extension)*</small>577 578* Returns: <code>Promise<Buffer></code>579 580Consume the body and return a promise that will resolve to a Buffer.581 582#### body.textConverted()583 584<small>*(node-fetch extension)*</small>585 586* Returns: <code>Promise<String></code>587 588Identical to `body.text()`, except instead of always converting to UTF-8, encoding sniffing will be performed and text converted to UTF-8 if possible.589 590(This API requires an optional dependency of the npm package [encoding](https://www.npmjs.com/package/encoding), which you need to install manually. `webpack` users may see [a warning message](https://github.com/bitinn/node-fetch/issues/412#issuecomment-379007792) due to this optional dependency.)591 592<a id="class-fetcherror"></a>593### Class: FetchError594 595<small>*(node-fetch extension)*</small>596 597An operational error in the fetching process. See [ERROR-HANDLING.md][] for more info.598 599<a id="class-aborterror"></a>600### Class: AbortError601 602<small>*(node-fetch extension)*</small>603 604An Error thrown when the request is aborted in response to an `AbortSignal`'s `abort` event. It has a `name` property of `AbortError`. See [ERROR-HANDLING.MD][] for more info.605 606## Acknowledgement607 608Thanks to [github/fetch](https://github.com/github/fetch) for providing a solid implementation reference.609 610`node-fetch` v1 was maintained by [@bitinn](https://github.com/bitinn); v2 was maintained by [@TimothyGu](https://github.com/timothygu), [@bitinn](https://github.com/bitinn) and [@jimmywarting](https://github.com/jimmywarting); v2 readme is written by [@jkantr](https://github.com/jkantr).611 612## License613 614MIT615 616[npm-image]: https://flat.badgen.net/npm/v/node-fetch617[npm-url]: https://www.npmjs.com/package/node-fetch618[travis-image]: https://flat.badgen.net/travis/bitinn/node-fetch619[travis-url]: https://travis-ci.org/bitinn/node-fetch620[codecov-image]: https://flat.badgen.net/codecov/c/github/bitinn/node-fetch/master621[codecov-url]: https://codecov.io/gh/bitinn/node-fetch622[install-size-image]: https://flat.badgen.net/packagephobia/install/node-fetch623[install-size-url]: https://packagephobia.now.sh/result?p=node-fetch624[discord-image]: https://img.shields.io/discord/619915844268326952?color=%237289DA&label=Discord&style=flat-square625[discord-url]: https://discord.gg/Zxbndcm626[opencollective-image]: https://opencollective.com/node-fetch/backers.svg627[opencollective-url]: https://opencollective.com/node-fetch628[whatwg-fetch]: https://fetch.spec.whatwg.org/629[response-init]: https://fetch.spec.whatwg.org/#responseinit630[node-readable]: https://nodejs.org/api/stream.html#stream_readable_streams631[mdn-headers]: https://developer.mozilla.org/en-US/docs/Web/API/Headers632[LIMITS.md]: https://github.com/bitinn/node-fetch/blob/master/LIMITS.md633[ERROR-HANDLING.md]: https://github.com/bitinn/node-fetch/blob/master/ERROR-HANDLING.md634[UPGRADE-GUIDE.md]: https://github.com/bitinn/node-fetch/blob/master/UPGRADE-GUIDE.md635