gaxios

An HTTP request client that provides an axios like interface over top of node-fetch.

Install

1$ npm install gaxios

Example

1import {request} from 'gaxios';
2const res = await request({url: 'https://google.com/'});

fetch-Compatible API Example

We offer a drop-in fetch-compatible API as well.

1import {instance} from 'gaxios';
2const res = await instance.fetch('https://google.com/');

To disable the auto-processing of the request body in res.data, set {responseType: 'stream'} or .adapter on a Gaxios instance's defaults or per-request.

Setting Defaults

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:

1import {Gaxios} from 'gaxios';
2
3const gaxios = new Gaxios();
4
5gaxios.defaults = {
6  baseURL: 'https://example.com'
7  headers: new Headers({
8    Authorization: 'SOME_TOKEN'
9  })
10}
11
12await gaxios.request({url: '/data'});

Note that setting default values will take precedence over other authentication methods, i.e., application default credentials.

GaxiosResponse

The GaxiosResponse object extends the fetch API's Response object, with the addition of:

• config: the configuration used for the request.
• data: the transformed .body, such as JSON, text, arrayBuffer, or more.

Request Options

1interface GaxiosOptions = {
2  // The url to which the request should be sent.  Required.
3  url: string | URL,
4
5  // The HTTP method to use for the request.  Defaults to `GET`.
6  method: 'GET',
7
8  // The base Url to use for the request.
9  // Resolved as `new URL(url, baseURL)`
10  baseURL: 'https://example.com/v1/' | URL;
11
12  // The HTTP methods to be sent with the request.
13  headers: new Headers(),
14
15  // The data to send in the body of the request. Objects will be serialized as JSON
16  // except for:
17  // - `ArrayBuffer`
18  // - `Blob`
19  // - `Buffer` (Node.js)
20  // - `DataView`
21  // - `File`
22  // - `FormData`
23  // - `ReadableStream`
24  // - `stream.Readable` (Node.js)
25  // - strings
26  // - `TypedArray` (e.g. `Uint8Array`, `BigInt64Array`)
27  // - `URLSearchParams`
28  // - all other objects where:
29  //   - headers.get('Content-Type') === 'application/x-www-form-urlencoded' (as they will be serialized as `URLSearchParams`)
30  //
31  // Here are a few examples that would prevent setting `Content-Type: application/json` by default:
32  // - data: JSON.stringify({some: 'data'}) // a `string`
33  // - data: fs.readFile('./some-data.jpeg') // a `stream.Readable`
34  data: {
35    some: 'data'
36  },
37
38  // The max size of the http response content in bytes allowed.
39  // Defaults to `0`, which is the same as unset.
40  maxContentLength: 2000,
41
42  // The query parameters that will be encoded using `URLSearchParams` and
43  // appended to the url
44  params: {
45    querystring: 'parameters'
46  },
47
48  // The timeout for the HTTP request in milliseconds. No timeout by default.
49  timeout: 60000,
50
51  // Optional method to override making the actual HTTP request. Useful
52  // for writing tests and instrumentation
53  adapter?: async (options, defaultAdapter) => {
54    const res = await defaultAdapter(options);
55    res.data = {
56      ...res.data,
57      extraProperty: 'your extra property',
58    };
59    return res;
60  };
61
62  // The expected return type of the request.  Options are:
63  // 'json' | 'stream' | 'blob' | 'arraybuffer' | 'text' | 'unknown'
64  // Defaults to `unknown`.
65  //
66  // If the `fetchImplementation` is native `fetch`, the
67  // stream is a `ReadableStream`, otherwise `readable.Stream`.
68  //
69  // Note: Setting 'stream' does not consume the `Response#body` - this can
70  // be useful for passthrough requests, where a consumer would like to
71  // transform the `Response#body`, or for using Gaxios as a drop-in `fetch`
72  // replacement.
73  responseType: 'unknown',
74
75  // The node.js http agent to use for the request.
76  agent: someHttpsAgent,
77
78  // Custom function to determine if the response is valid based on the
79  // status code.  Defaults to (>= 200 && < 300)
80  validateStatus: (status: number) => true,
81
82  /**
83   * Implementation of `fetch` to use when making the API call. Will use
84   * `node-fetch` by default.
85   */
86  fetchImplementation?: typeof fetch;
87
88  // Configuration for retrying of requests.
89  retryConfig: {
90    // The number of times to retry the request.  Defaults to 3.
91    retry?: number;
92
93    // The number of retries already attempted.
94    currentRetryAttempt?: number;
95
96    // The HTTP Methods that will be automatically retried.
97    // Defaults to ['GET','PUT','HEAD','OPTIONS','DELETE']
98    httpMethodsToRetry?: string[];
99
100    // The HTTP response status codes that will automatically be retried.
101    // Defaults to: [[100, 199], [408, 408], [429, 429], [500, 599]]
102    statusCodesToRetry?: number[][];
103
104    // Function to invoke when a retry attempt is made.
105    onRetryAttempt?: (err: GaxiosError) => Promise<void> | void;
106
107    // Function to invoke which determines if you should retry
108    shouldRetry?: (err: GaxiosError) => Promise<boolean> | boolean;
109
110    // When there is no response, the number of retries to attempt. Defaults to 2.
111    noResponseRetries?: number;
112
113    // The amount of time to initially delay the retry, in ms.  Defaults to 100ms.
114    retryDelay?: number;
115  },
116
117  // Enables default configuration for retries.
118  retry: boolean,
119
120  // Enables aborting via AbortController
121  signal?: AbortSignal
122
123  /**
124   * A collection of parts to send as a `Content-Type: multipart/related` request.
125   */
126  multipart?: GaxiosMultipartOptions;
127
128  /**
129   * An optional proxy to use for requests.
130   * Available via `process.env.HTTP_PROXY` and `process.env.HTTPS_PROXY` as well - with a preference for the this config option when multiple are available.
131   * The `agent` option overrides this.
132   *
133   * @see {@link GaxiosOptions.noProxy}
134   * @see {@link GaxiosOptions.agent}
135   */
136  proxy?: string | URL;
137
138  /**
139   * A list for excluding traffic for proxies.
140   * Available via `process.env.NO_PROXY` as well as a common-separated list of strings - merged with any local `noProxy` rules.
141   *
142   * - When provided a string, it is matched by
143   *   - Wildcard `*.` and `.` matching are available. (e.g. `.example.com` or `*.example.com`)
144   * - When provided a URL, it is matched by the `.origin` property.
145   *   - For example, requesting `https://example.com` with the following `noProxy`s would result in a no proxy use:
146   *     - new URL('https://example.com')
147   *     - new URL('https://example.com:443')
148   *   - The following would be used with a proxy:
149   *     - new URL('http://example.com:80')
150   *     - new URL('https://example.com:8443')
151   * - When provided a regular expression it is used to match the stringified URL
152   *
153   * @see {@link GaxiosOptions.proxy}
154   */
155  noProxy?: (string | URL | RegExp)[];
156
157  /**
158   * An experimental, customizable error redactor.
159   *
160   * Set `false` to disable.
161   *
162   * @remarks
163   *
164   * This does not replace the requirement for an active Data Loss Prevention (DLP) provider. For DLP suggestions, see:
165   * - https://cloud.google.com/sensitive-data-protection/docs/redacting-sensitive-data#dlp_deidentify_replace_infotype-nodejs
166   * - https://cloud.google.com/sensitive-data-protection/docs/infotypes-reference#credentials_and_secrets
167   *
168   * @experimental
169   */
170  errorRedactor?: typeof defaultErrorRedactor | false;
171}

License

Apache-2.0