legacy-libs/gaxios/README.md

   1 # gaxios
   2
   3 [![npm version](https://img.shields.io/npm/v/gaxios.svg)](https://www.npmjs.org/package/gaxios)
   4 [![Build Status](https://api.cirrus-ci.com/github/JustinBeckwith/gaxios.svg)](https://cirrus-ci.com/github/JustinBeckwith/gaxios)
   5 [![codecov](https://codecov.io/gh/JustinBeckwith/gaxios/branch/master/graph/badge.svg)](https://codecov.io/gh/JustinBeckwith/gaxios)
   6 [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
   7
   8 > An HTTP request client that provides an `axios` like interfance over top of `node-fetch`.  Only really useful if you're trying to migrate from axios to the fetch.
   9
  10 ## Install
  11 ```sh
  12 $ npm install gaxios
  13 ```
  14
  15 ## Example
  16
  17 ```js
  18 const {request} = require('gaxios');
  19 const res = await request({
  20   url: 'https://www.googleapis.com/discovery/v1/apis/'
  21 });
  22 ```
  23
  24 ## Setting Defaults
  25 Gaxios supports setting default properties both on the default instance, and on additional instances. This is often useful when making many requests to the same domain with the same base settings.  For example:
  26
  27 ```js
  28 const gaxios = require('gaxios');
  29 gaxios.instance.defaults = {
  30   baseURL: 'https://example.com'
  31   headers: {
  32     Authorization: 'SOME_TOKEN'
  33   }
  34 }
  35 gaxios.request({url: '/data'}).then(...);
  36 ```
  37
  38 ## Request Options
  39
  40 ```js
  41 {
  42   // The url to which the request should be sent.  Required.
  43   url: string,
  44
  45   // The HTTP method to use for the request.  Defaults to `GET`.
  46   method: 'GET',
  47
  48   // The base Url to use for the request. Prepended to the `url` property above.
  49   baseURL: 'https://example.com';
  50
  51   // The HTTP methods to be sent with the request.
  52   headers: { 'some': 'header' },
  53
  54   // The data to base64 encode and send in the body of the request.
  55   data: {
  56     some: 'data'
  57   },
  58
  59   // The max size of the http response content in bytes allowed.
  60   // Defaults to `0`, which is the same as unset.
  61   maxContentLength: 2000,
  62
  63   // The max number of HTTP redirects to follow.
  64   // Defaults to 100.
  65   maxRedirects: 100,
  66
  67   // The querystring parameters that will be encoded using `qs` and
  68   // appended to the url
  69   params: {
  70     querystring: 'parameters'
  71   },
  72
  73   // By default, we use the `querystring` package in node core to serialize
  74   // querystring parameters.  You can override that and provide your
  75   // own implementation.
  76   paramsSerializer: (params) => {
  77     return qs.stringify(params);
  78   },
  79
  80   // The timeout for the HTTP request. Defaults to 0.
  81   timeout: 1000,
  82
  83   // Optional method to override making the actual HTTP request. Useful
  84   // for writing tests.
  85   adapter?: (options) => {
  86     return {
  87       data: 'your data'
  88     }
  89   };
  90
  91   // The expected return type of the request.  Options are:
  92   // json | stream | blob | arraybuffer | text
  93   // Defaults to `json`.
  94   responseType: 'json',
  95
  96   // The node.js http agent to use for the request.
  97   agent: someHttpsAgent,
  98
  99   // Custom function to determine if the response is valid based on the
 100   // status code.  Defaults to (>= 200 && < 300)
 101   validateStatus: (status: number) => true,
 102
 103   // Configuration for retrying of requests.
 104   retryConfig: {
 105     // The number of times to retry the request.  Defaults to 3.
 106     retry?: number;
 107
 108     // The number of retries already attempted.
 109     currentRetryAttempt?: number;
 110
 111     // The amount of time to initially delay the retry.  Defaults to 100.
 112     retryDelay?: number;
 113
 114     // The HTTP Methods that will be automatically retried.
 115     // Defaults to ['GET','PUT','HEAD','OPTIONS','DELETE']
 116     httpMethodsToRetry?: string[];
 117
 118     // The HTTP response status codes that will automatically be retried.
 119     // Defaults to: [[100, 199], [429, 429], [500, 599]]
 120     statusCodesToRetry?: number[][];
 121
 122     // Function to invoke when a retry attempt is made.
 123     onRetryAttempt?: (err: GaxiosError) => void;
 124
 125     // Function to invoke which determines if you should retry
 126     shouldRetry?: (err: GaxiosError) => boolean;
 127
 128     // When there is no response, the number of retries to attempt. Defaults to 2.
 129     noResponseRetries?: number;
 130   },
 131
 132   // Enables default configuration for retries.
 133   retry: boolean,
 134
 135   // Cancelling a request requires the `abort-controller` library.
 136   // See https://github.com/bitinn/node-fetch#request-cancellation-with-abortsignal
 137   signal?: AbortSignal
 138 }
 139 ```
 140
 141 ## License
 142 [Apache-2.0](LICENSE)