github.com/jfrog/frogbot@v1.1.1-0.20231221090046-821a26f50338/action/node_modules/node-fetch/README.md (about)

     1  node-fetch
     2  ==========
     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  
    10  A light-weight module that brings `window.fetch` to Node.js
    11  
    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  ## Motivation
    53  
    54  Instead 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  
    56  See 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  ## Features
    59  
    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 fetch
    68  
    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  ## Installation
    74  
    75  Current stable release (`2.x`)
    76  
    77  ```sh
    78  $ npm install node-fetch
    79  ```
    80  
    81  ## Loading and configuring the module
    82  We suggest you load the module via `require` until the stabilization of ES modules in node:
    83  ```js
    84  const fetch = require('node-fetch');
    85  ```
    86  
    87  If you are using a Promise library other than native, set it through `fetch.Promise`:
    88  ```js
    89  const Bluebird = require('bluebird');
    90  
    91  fetch.Promise = Bluebird;
    92  ```
    93  
    94  ## Common Usage
    95  
    96  NOTE: 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 HTML
    99  ```js
   100  fetch('https://github.com/')
   101      .then(res => res.text())
   102      .then(body => console.log(body));
   103  ```
   104  
   105  #### JSON
   106  
   107  ```js
   108  
   109  fetch('https://api.github.com/users/github')
   110      .then(res => res.json())
   111      .then(json => console.log(json));
   112  ```
   113  
   114  #### Simple Post
   115  ```js
   116  fetch('https://httpbin.org/post', { method: 'POST', body: 'a=1' })
   117      .then(res => res.json()) // expecting a json response
   118      .then(json => console.log(json));
   119  ```
   120  
   121  #### Post with JSON
   122  
   123  ```js
   124  const body = { a: 1 };
   125  
   126  fetch('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 parameters
   136  `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  
   138  NOTE: The `Content-Type` header is only set automatically to `x-www-form-urlencoded` when an instance of `URLSearchParams` is given as such:
   139  
   140  ```js
   141  const { URLSearchParams } = require('url');
   142  
   143  const params = new URLSearchParams();
   144  params.append('a', 1);
   145  
   146  fetch('https://httpbin.org/post', { method: 'POST', body: params })
   147      .then(res => res.json())
   148      .then(json => console.log(json));
   149  ```
   150  
   151  #### Handling exceptions
   152  NOTE: 3xx-5xx responses are *NOT* exceptions and should be handled in `then()`; see the next section for more information.
   153  
   154  Adding 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  ```js
   157  fetch('https://domain.invalid/')
   158      .catch(err => console.error(err));
   159  ```
   160  
   161  #### Handling client and server errors
   162  It is common to create a helper function to check that the response contains no client (4xx) or server (5xx) error responses:
   163  
   164  ```js
   165  function checkStatus(res) {
   166      if (res.ok) { // res.status >= 200 && res.status < 300
   167          return res;
   168      } else {
   169          throw MyCustomError(res.statusText);
   170      }
   171  }
   172  
   173  fetch('https://httpbin.org/status/400')
   174      .then(checkStatus)
   175      .then(res => console.log('will not get here...'))
   176  ```
   177  
   178  ## Advanced Usage
   179  
   180  #### Streams
   181  The "Node.js way" is to use streams when possible:
   182  
   183  ```js
   184  fetch('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  
   191  #### Buffer
   192  If you prefer to cache binary data in full, use buffer(). (NOTE: `buffer()` is a `node-fetch`-only API)
   193  
   194  ```js
   195  const fileType = require('file-type');
   196  
   197  fetch('https://assets-cdn.github.com/images/modules/logos_page/Octocat.png')
   198      .then(res => res.buffer())
   199      .then(buffer => fileType(buffer))
   200      .then(type => { /* ... */ });
   201  ```
   202  
   203  #### Accessing Headers and other Meta data
   204  ```js
   205  fetch('https://github.com/')
   206      .then(res => {
   207          console.log(res.ok);
   208          console.log(res.status);
   209          console.log(res.statusText);
   210          console.log(res.headers.raw());
   211          console.log(res.headers.get('content-type'));
   212      });
   213  ```
   214  
   215  #### Extract Set-Cookie Header
   216  
   217  Unlike browsers, you can access raw `Set-Cookie` headers manually using `Headers.raw()`. This is a `node-fetch` only API.
   218  
   219  ```js
   220  fetch(url).then(res => {
   221      // returns an array of values, instead of a string of comma-separated values
   222      console.log(res.headers.raw()['set-cookie']);
   223  });
   224  ```
   225  
   226  #### Post data using a file stream
   227  
   228  ```js
   229  const { createReadStream } = require('fs');
   230  
   231  const stream = createReadStream('input.txt');
   232  
   233  fetch('https://httpbin.org/post', { method: 'POST', body: stream })
   234      .then(res => res.json())
   235      .then(json => console.log(json));
   236  ```
   237  
   238  #### Post with form-data (detect multipart)
   239  
   240  ```js
   241  const FormData = require('form-data');
   242  
   243  const form = new FormData();
   244  form.append('a', 1);
   245  
   246  fetch('https://httpbin.org/post', { method: 'POST', body: form })
   247      .then(res => res.json())
   248      .then(json => console.log(json));
   249  
   250  // OR, using custom headers
   251  // NOTE: getHeaders() is non-standard API
   252  
   253  const form = new FormData();
   254  form.append('a', 1);
   255  
   256  const options = {
   257      method: 'POST',
   258      body: form,
   259      headers: form.getHeaders()
   260  }
   261  
   262  fetch('https://httpbin.org/post', options)
   263      .then(res => res.json())
   264      .then(json => console.log(json));
   265  ```
   266  
   267  #### Request cancellation with AbortSignal
   268  
   269  > NOTE: You may cancel streamed requests only on Node >= v8.0.0
   270  
   271  You may cancel requests with `AbortController`. A suggested implementation is [`abort-controller`](https://www.npmjs.com/package/abort-controller).
   272  
   273  An example of timing out a request after 150ms could be achieved as the following:
   274  
   275  ```js
   276  import AbortController from 'abort-controller';
   277  
   278  const controller = new AbortController();
   279  const timeout = setTimeout(
   280    () => { controller.abort(); },
   281    150,
   282  );
   283  
   284  fetch(url, { signal: controller.signal })
   285    .then(res => res.json())
   286    .then(
   287      data => {
   288        useData(data)
   289      },
   290      err => {
   291        if (err.name === 'AbortError') {
   292          // request was aborted
   293        }
   294      },
   295    )
   296    .finally(() => {
   297      clearTimeout(timeout);
   298    });
   299  ```
   300  
   301  See [test cases](https://github.com/bitinn/node-fetch/blob/master/test/test.js) for more examples.
   302  
   303  
   304  ## API
   305  
   306  ### fetch(url[, options])
   307  
   308  - `url` A string representing the URL for fetching
   309  - `options` [Options](#fetch-options) for the HTTP(S) request
   310  - Returns: <code>Promise&lt;[Response](#class-response)&gt;</code>
   311  
   312  Perform an HTTP(S) fetch.
   313  
   314  `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`.
   315  
   316  <a id="fetch-options"></a>
   317  ### Options
   318  
   319  The default values are shown after each option key.
   320  
   321  ```js
   322  {
   323      // These properties are part of the Fetch Standard
   324      method: 'GET',
   325      headers: {},        // request headers. format is the identical to that accepted by the Headers constructor (see below)
   326      body: null,         // request body. can be null, a string, a Buffer, a Blob, or a Node.js Readable stream
   327      redirect: 'follow', // set to `manual` to extract redirect headers, `error` to reject redirect
   328      signal: null,       // pass an instance of AbortSignal to optionally abort requests
   329  
   330      // The following properties are node-fetch extensions
   331      follow: 20,         // maximum redirect count. 0 to not follow redirect
   332      timeout: 0,         // req/res timeout in ms, it resets on redirect. 0 to disable (OS limit applies). Signal is recommended instead.
   333      compress: true,     // support gzip/deflate content encoding. false to disable
   334      size: 0,            // maximum response body size in bytes. 0 to disable
   335      agent: null         // http(s).Agent instance or function that returns an instance (see below)
   336  }
   337  ```
   338  
   339  ##### Default Headers
   340  
   341  If no values are set, the following request headers will be sent automatically:
   342  
   343  Header              | Value
   344  ------------------- | --------------------------------------------------------
   345  `Accept-Encoding`   | `gzip,deflate` _(when `options.compress === true`)_
   346  `Accept`            | `*/*`
   347  `Connection`        | `close` _(when no `options.agent` is present)_
   348  `Content-Length`    | _(automatically calculated, if possible)_
   349  `Transfer-Encoding` | `chunked` _(when `req.body` is a stream)_
   350  `User-Agent`        | `node-fetch/1.0 (+https://github.com/bitinn/node-fetch)`
   351  
   352  Note: when `body` is a `Stream`, `Content-Length` is not set automatically.
   353  
   354  ##### Custom Agent
   355  
   356  The `agent` option allows you to specify networking related options which are out of the scope of Fetch, including and not limited to the following:
   357  
   358  - Support self-signed certificate
   359  - Use only IPv4 or IPv6
   360  - Custom DNS Lookup
   361  
   362  See [`http.Agent`](https://nodejs.org/api/http.html#http_new_agent_options) for more information.
   363  
   364  In 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.
   365  
   366  ```js
   367  const httpAgent = new http.Agent({
   368      keepAlive: true
   369  });
   370  const httpsAgent = new https.Agent({
   371      keepAlive: true
   372  });
   373  
   374  const options = {
   375      agent: function (_parsedURL) {
   376          if (_parsedURL.protocol == 'http:') {
   377              return httpAgent;
   378          } else {
   379              return httpsAgent;
   380          }
   381      }
   382  }
   383  ```
   384  
   385  <a id="class-request"></a>
   386  ### Class: Request
   387  
   388  An HTTP(S) request containing information about URL, method, headers, and the body. This class implements the [Body](#iface-body) interface.
   389  
   390  Due to the nature of Node.js, the following properties are not implemented at this moment:
   391  
   392  - `type`
   393  - `destination`
   394  - `referrer`
   395  - `referrerPolicy`
   396  - `mode`
   397  - `credentials`
   398  - `cache`
   399  - `integrity`
   400  - `keepalive`
   401  
   402  The following node-fetch extension properties are provided:
   403  
   404  - `follow`
   405  - `compress`
   406  - `counter`
   407  - `agent`
   408  
   409  See [options](#fetch-options) for exact meaning of these extensions.
   410  
   411  #### new Request(input[, options])
   412  
   413  <small>*(spec-compliant)*</small>
   414  
   415  - `input` A string representing a URL, or another `Request` (which will be cloned)
   416  - `options` [Options][#fetch-options] for the HTTP(S) request
   417  
   418  Constructs a new `Request` object. The constructor is identical to that in the [browser](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request).
   419  
   420  In most cases, directly `fetch(url, options)` is simpler than creating a `Request` object.
   421  
   422  <a id="class-response"></a>
   423  ### Class: Response
   424  
   425  An HTTP(S) response. This class implements the [Body](#iface-body) interface.
   426  
   427  The following properties are not implemented in node-fetch at this moment:
   428  
   429  - `Response.error()`
   430  - `Response.redirect()`
   431  - `type`
   432  - `trailer`
   433  
   434  #### new Response([body[, options]])
   435  
   436  <small>*(spec-compliant)*</small>
   437  
   438  - `body` A `String` or [`Readable` stream][node-readable]
   439  - `options` A [`ResponseInit`][response-init] options dictionary
   440  
   441  Constructs a new `Response` object. The constructor is identical to that in the [browser](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response).
   442  
   443  Because Node.js does not implement service workers (for which this class was designed), one rarely has to construct a `Response` directly.
   444  
   445  #### response.ok
   446  
   447  <small>*(spec-compliant)*</small>
   448  
   449  Convenience 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.
   450  
   451  #### response.redirected
   452  
   453  <small>*(spec-compliant)*</small>
   454  
   455  Convenience property representing if the request has been redirected at least once. Will evaluate to true if the internal redirect counter is greater than 0.
   456  
   457  <a id="class-headers"></a>
   458  ### Class: Headers
   459  
   460  This class allows manipulating and iterating over a set of HTTP headers. All methods specified in the [Fetch Standard][whatwg-fetch] are implemented.
   461  
   462  #### new Headers([init])
   463  
   464  <small>*(spec-compliant)*</small>
   465  
   466  - `init` Optional argument to pre-fill the `Headers` object
   467  
   468  Construct a new `Headers` object. `init` can be either `null`, a `Headers` object, an key-value map object or any iterable object.
   469  
   470  ```js
   471  // Example adapted from https://fetch.spec.whatwg.org/#example-headers-class
   472  
   473  const meta = {
   474    'Content-Type': 'text/xml',
   475    'Breaking-Bad': '<3'
   476  };
   477  const headers = new Headers(meta);
   478  
   479  // The above is equivalent to
   480  const meta = [
   481    [ 'Content-Type', 'text/xml' ],
   482    [ 'Breaking-Bad', '<3' ]
   483  ];
   484  const headers = new Headers(meta);
   485  
   486  // You can in fact use any iterable objects, like a Map or even another Headers
   487  const meta = new Map();
   488  meta.set('Content-Type', 'text/xml');
   489  meta.set('Breaking-Bad', '<3');
   490  const headers = new Headers(meta);
   491  const copyOfHeaders = new Headers(headers);
   492  ```
   493  
   494  <a id="iface-body"></a>
   495  ### Interface: Body
   496  
   497  `Body` is an abstract interface with methods that are applicable to both `Request` and `Response` classes.
   498  
   499  The following methods are not yet implemented in node-fetch at this moment:
   500  
   501  - `formData()`
   502  
   503  #### body.body
   504  
   505  <small>*(deviation from spec)*</small>
   506  
   507  * Node.js [`Readable` stream][node-readable]
   508  
   509  Data 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].
   510  
   511  #### body.bodyUsed
   512  
   513  <small>*(spec-compliant)*</small>
   514  
   515  * `Boolean`
   516  
   517  A boolean property for if this body has been consumed. Per the specs, a consumed body cannot be used again.
   518  
   519  #### body.arrayBuffer()
   520  #### body.blob()
   521  #### body.json()
   522  #### body.text()
   523  
   524  <small>*(spec-compliant)*</small>
   525  
   526  * Returns: <code>Promise</code>
   527  
   528  Consume the body and return a promise that will resolve to one of these formats.
   529  
   530  #### body.buffer()
   531  
   532  <small>*(node-fetch extension)*</small>
   533  
   534  * Returns: <code>Promise&lt;Buffer&gt;</code>
   535  
   536  Consume the body and return a promise that will resolve to a Buffer.
   537  
   538  #### body.textConverted()
   539  
   540  <small>*(node-fetch extension)*</small>
   541  
   542  * Returns: <code>Promise&lt;String&gt;</code>
   543  
   544  Identical to `body.text()`, except instead of always converting to UTF-8, encoding sniffing will be performed and text converted to UTF-8 if possible.
   545  
   546  (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.)
   547  
   548  <a id="class-fetcherror"></a>
   549  ### Class: FetchError
   550  
   551  <small>*(node-fetch extension)*</small>
   552  
   553  An operational error in the fetching process. See [ERROR-HANDLING.md][] for more info.
   554  
   555  <a id="class-aborterror"></a>
   556  ### Class: AbortError
   557  
   558  <small>*(node-fetch extension)*</small>
   559  
   560  An 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.
   561  
   562  ## Acknowledgement
   563  
   564  Thanks to [github/fetch](https://github.com/github/fetch) for providing a solid implementation reference.
   565  
   566  `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).
   567  
   568  ## License
   569  
   570  MIT
   571  
   572  [npm-image]: https://flat.badgen.net/npm/v/node-fetch
   573  [npm-url]: https://www.npmjs.com/package/node-fetch
   574  [travis-image]: https://flat.badgen.net/travis/bitinn/node-fetch
   575  [travis-url]: https://travis-ci.org/bitinn/node-fetch
   576  [codecov-image]: https://flat.badgen.net/codecov/c/github/bitinn/node-fetch/master
   577  [codecov-url]: https://codecov.io/gh/bitinn/node-fetch
   578  [install-size-image]: https://flat.badgen.net/packagephobia/install/node-fetch
   579  [install-size-url]: https://packagephobia.now.sh/result?p=node-fetch
   580  [discord-image]: https://img.shields.io/discord/619915844268326952?color=%237289DA&label=Discord&style=flat-square
   581  [discord-url]: https://discord.gg/Zxbndcm
   582  [opencollective-image]: https://opencollective.com/node-fetch/backers.svg
   583  [opencollective-url]: https://opencollective.com/node-fetch
   584  [whatwg-fetch]: https://fetch.spec.whatwg.org/
   585  [response-init]: https://fetch.spec.whatwg.org/#responseinit
   586  [node-readable]: https://nodejs.org/api/stream.html#stream_readable_streams
   587  [mdn-headers]: https://developer.mozilla.org/en-US/docs/Web/API/Headers
   588  [LIMITS.md]: https://github.com/bitinn/node-fetch/blob/master/LIMITS.md
   589  [ERROR-HANDLING.md]: https://github.com/bitinn/node-fetch/blob/master/ERROR-HANDLING.md
   590  [UPGRADE-GUIDE.md]: https://github.com/bitinn/node-fetch/blob/master/UPGRADE-GUIDE.md