feat!: Upgrade to node-fetch v3

.github/workflows/ci.yaml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: [14, 16, 18, 20]
+        node: [18, 20]
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-node@v3
@@ -32,7 +32,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-node@v3
         with:
-          node-version: 14
+          node-version: 18
       - run: npm install
       - run: npm test
         env:
@@ -43,7 +43,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-node@v3
         with:
-          node-version: 14
+          node-version: 18
       - run: npm install
       - run: npm run lint
   docs:
@@ -52,7 +52,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-node@v3
         with:
-          node-version: 14
+          node-version: 18
       - run: npm install
       - run: npm run docs
       - uses: JustinBeckwith/linkinator-action@v1

README.md

@@ -56,7 +56,7 @@ interface GaxiosOptions = {
   headers: { 'some': 'header' },
 
   // The data to send in the body of the request. Data objects will be
-  // serialized as JSON.
+  // serialized as JSON, except for `FormData`.
   //
   // Note: if you would like to provide a Content-Type header other than
   // application/json you you must provide a string or readable stream, rather
@@ -71,10 +71,6 @@ interface GaxiosOptions = {
   // Defaults to `0`, which is the same as unset.
   maxContentLength: 2000,
 
-  // The max number of HTTP redirects to follow.
-  // Defaults to 100.
-  maxRedirects: 100,
-
   // The querystring parameters that will be encoded using `qs` and
   // appended to the url
   params: {
@@ -105,6 +101,8 @@ interface GaxiosOptions = {
   // The expected return type of the request.  Options are:
   // json | stream | blob | arraybuffer | text | unknown
   // Defaults to `unknown`.
+  // If the `fetchImplementation` is native `fetch`, the
+  // stream is a `ReadableStream`, otherwise `readable.Stream`
   responseType: 'unknown',
 
   // The node.js http agent to use for the request.
@@ -114,9 +112,9 @@ interface GaxiosOptions = {
   // status code.  Defaults to (>= 200 && < 300)
   validateStatus: (status: number) => true,
 
-  // Implementation of `fetch` to use when making the API call. By default,
-  // will use the browser context if available, and fall back to `node-fetch`
-  // in node.js otherwise.
+  /**
+   * Implementation of `fetch` to use when making the API call. Will use `fetch` by default.
+   */
   fetchImplementation?: typeof fetch;
 
   // Configuration for retrying of requests.
@@ -151,8 +149,7 @@ interface GaxiosOptions = {
   // Enables default configuration for retries.
   retry: boolean,
 
-  // Cancelling a request requires the `abort-controller` library.
-  // See https://github.com/bitinn/node-fetch#request-cancellation-with-abortsignal
+  // Enables aborting via AbortController
   signal?: AbortSignal
 
   /**

package.json

@@ -47,18 +47,15 @@
     "@types/mv": "^2.1.0",
     "@types/ncp": "^2.0.1",
     "@types/node": "^20.0.0",
-    "@types/node-fetch": "^2.5.7",
     "@types/sinon": "^17.0.0",
     "@types/tmp": "0.2.6",
     "@types/uuid": "^9.0.0",
-    "abort-controller": "^3.0.0",
     "assert": "^2.0.0",
     "browserify": "^17.0.0",
     "c8": "^8.0.0",
     "cors": "^2.8.5",
     "execa": "^5.0.0",
     "express": "^4.16.4",
-    "form-data": "^4.0.0",
     "gts": "^5.0.0",
     "is-docker": "^2.0.0",
     "karma": "^6.0.0",
@@ -74,7 +71,7 @@
     "multiparty": "^4.2.1",
     "mv": "^2.1.1",
     "ncp": "^2.0.0",
-    "nock": "^13.0.0",
+    "nock": "^14.0.0-beta.5",
     "null-loader": "^4.0.0",
     "puppeteer": "^21.0.0",
     "sinon": "^17.0.0",
@@ -88,8 +85,7 @@
   "dependencies": {
     "extend": "^3.0.2",
     "https-proxy-agent": "^7.0.1",
-    "is-stream": "^2.0.0",
-    "node-fetch": "^2.6.9",
+    "node-fetch": "^3.3.2",
     "uuid": "^9.0.1"
   }
 }

src/common.ts

@@ -94,7 +94,8 @@
       try {
         this.response.data = translateData(
           this.config.responseType,
-          this.response?.data
+          // workaround for `node-fetch`'s `.data` deprecation...
+          this.response?.bodyUsed ? this.response?.data : undefined
         );
       } catch {
         // best effort - don't throw an error within an error
@@ -118,22 +119,17 @@
   }
 }
 
+/**
+ * @deprecated use native {@link globalThis.Headers}.
+ */
 export interface Headers {
   [index: string]: any;
 }
 export type GaxiosPromise<T = any> = Promise<GaxiosResponse<T>>;
 
-export interface GaxiosXMLHttpRequest {
-  responseURL: string;
-}
-
-export interface GaxiosResponse<T = any> {
+export interface GaxiosResponse<T = any> extends Response {
   config: GaxiosOptions;
   data: T;
-  status: number;
-  statusText: string;
-  headers: Headers;
-  request: GaxiosXMLHttpRequest;
 }
 
 export interface GaxiosMultipartOptions {
@@ -144,12 +140,14 @@
 /**
  * Request options that are used to form the request.
  */
-export interface GaxiosOptions {
+export interface GaxiosOptions extends Omit<RequestInit, 'headers'> {
   /**
    * Optional method to override making the actual HTTP request. Useful
    * for writing tests.
+   *
+   * @deprecated Use {@link GaxiosOptions.fetchImplementation} instead.
    */
   adapter?: <T = any>(
     options: GaxiosOptions,
     defaultAdapter: (options: GaxiosOptions) => GaxiosPromise<T>
   ) => GaxiosPromise<T>;
@@ -169,29 +167,61 @@
     | 'OPTIONS'
     | 'TRACE'
     | 'PATCH';
+  /**
+   * Recommended: Provide a native {@link globalThis.Headers Headers} object.
+   *
+   * @privateRemarks
+   *
+   * This type does not have the native {@link globalThis.Headers Headers} in
+   * its signature as it would break customers looking to modify headers before
+   * providing to this library (new, unnecessary type checks/guards).
+   */
   headers?: Headers;
+  /**
+   * The data to send in the {@link RequestInit.body} of the request. Data objects will be
+   * serialized as JSON, except for `FormData`.
+   *
+   * Note: if you would like to provide a Content-Type header other than
+   * application/json you you must provide a string or readable stream, rather
+   * than an object:
+   *
+   * ```ts
+   * {data: JSON.stringify({some: 'data'})}
+   * {data: fs.readFile('./some-data.jpeg')}
+   * ```
+   */
   data?: any;
-  body?: any;
   /**
-   * The maximum size of the http response content in bytes allowed.
+   * The maximum size of the http response `Content-Length` in bytes allowed.
    */
   maxContentLength?: number;
   /**
    * The maximum number of redirects to follow. Defaults to 20.
+   *
+   * @deprecated non-spec. Should use `20` if enabled per-spec: https://fetch.spec.whatwg.org/#http-redirect-fetch
    */
   maxRedirects?: number;
+  /**
+   * @deprecated non-spec. Should use `20` if enabled per-spec: https://fetch.spec.whatwg.org/#http-redirect-fetch
+   */
   follow?: number;
   /**
    * A collection of parts to send as a `Content-Type: multipart/related` request.
+   *
+   * This is passed to {@link RequestInit.body}.
    */
   multipart?: GaxiosMultipartOptions[];
   params?: any;
   paramsSerializer?: (params: {[index: string]: string | number}) => string;
   timeout?: number;
   /**
    * @deprecated ignored
    */
   onUploadProgress?: (progressEvent: any) => void;
+  /**
+   * If the `fetchImplementation` is native `fetch`, the
+   * stream is a `ReadableStream`, otherwise `readable.Stream`
+   */
   responseType?:
     | 'arraybuffer'
     | 'blob'
@@ -203,16 +233,28 @@
   validateStatus?: (status: number) => boolean;
   retryConfig?: RetryConfig;
   retry?: boolean;
-  // Should be instance of https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
-  // interface. Left as 'any' due to incompatibility between spec and abort-controller.
-  signal?: any;
+  /**
+   * Enables aborting via {@link AbortController}.
+   */
+  signal?: AbortSignal;
+  /**
+   * @deprecated non-spec. https://github.com/node-fetch/node-fetch/issues/1438
+   */
   size?: number;
   /**
-   * Implementation of `fetch` to use when making the API call. By default,
-   * will use the browser context if available, and fall back to `node-fetch`
-   * in node.js otherwise.
+   * Implementation of `fetch` to use when making the API call. Will use `fetch` by default.
+   *
+   * @example
+   *
+   * let customFetchCalled = false;
+   * const myFetch = (...args: Parameters<typeof fetch>) => {
+   *  customFetchCalled = true;
+   *  return fetch(...args);
+   * };
+   *
+   * {fetchImplementation: myFetch};
    */
-  fetchImplementation?: FetchImplementation;
+  fetchImplementation?: typeof fetch;
   // Configure client to use mTLS:
   cert?: string;
   key?: string;
@@ -259,7 +301,7 @@
   errorRedactor?: typeof defaultErrorRedactor | false;
 }
 /**
- * A partial object of `GaxiosResponse` with only redactable keys
+ * A partial object of `GaxiosOptions` with only redactable keys
  *
  * @experimental
  */
@@ -272,7 +314,7 @@
  *
  * @experimental
  */
 export type RedactableGaxiosResponse<T = any> = Pick<
   GaxiosResponse<T>,
   'config' | 'data' | 'headers'
 >;
@@ -331,42 +373,7 @@
   retryBackoff?: (err: GaxiosError, defaultBackoffMs: number) => Promise<void>;
 }
 
-export type FetchImplementation = (
-  input: FetchRequestInfo,
-  init?: FetchRequestInit
-) => Promise<FetchResponse>;
-
-export type FetchRequestInfo = any;
-
-export interface FetchResponse {
-  readonly status: number;
-  readonly statusText: string;
-  readonly url: string;
-  readonly body: unknown | null;
-  arrayBuffer(): Promise<unknown>;
-  blob(): Promise<unknown>;
-  readonly headers: FetchHeaders;
-  json(): Promise<any>;
-  text(): Promise<string>;
-}
-
-export interface FetchRequestInit {
-  method?: string;
-}
-
-export interface FetchHeaders {
-  append(name: string, value: string): void;
-  delete(name: string): void;
-  get(name: string): string | null;
-  has(name: string): boolean;
-  set(name: string, value: string): void;
-  forEach(
-    callbackfn: (value: string, key: string) => void,
-    thisArg?: any
-  ): void;
-}
-
 function translateData(responseType: string | undefined, data: any) {
   switch (responseType) {
     case 'stream':
       return data;
@@ -389,32 +396,47 @@
  *
  * @experimental
  */
 export function defaultErrorRedactor<T = any>(data: {
   config?: RedactableGaxiosOptions;
   response?: RedactableGaxiosResponse<T>;
 }) {
   const REDACT =
     '<<REDACTED> - See `errorRedactor` option in `gaxios` for configuration>.';
 
-  function redactHeaders(headers?: Headers) {
+  function redactHeaders(headers?: Headers | globalThis.Headers) {
     if (!headers) return;
 
-    for (const key of Object.keys(headers)) {
+    function check(key: string) {
       // any casing of `Authentication`
-      if (/^authentication$/i.test(key)) {
-        headers[key] = REDACT;
-      }
-
       // any casing of `Authorization`
-      if (/^authorization$/i.test(key)) {
-        headers[key] = REDACT;
-      }
-
       // anything containing secret, such as 'client secret'
-      if (/secret/i.test(key)) {
-        headers[key] = REDACT;
+      return (
+        /^authentication$/i.test(key) ||
+        /^authorization$/i.test(key) ||
+        /secret/i.test(key)
+      );
+    }
+
+    function redactHeadersObject(headers: Headers) {
+      for (const key of Object.keys(headers)) {
+        if (check(key)) headers[key] = REDACT;
       }
     }
+
+    function redactHeadersHeaders(headers: globalThis.Headers) {
+      headers.forEach((value, key) => {
+        if (check(key)) headers.set(key, REDACT);
+      });
+
+      // headers.g
+    }
+
+    // support `node-fetch` Headers and other third-parties
+    if (headers instanceof Headers || 'set' in headers) {
+      redactHeadersHeaders(headers as globalThis.Headers);
+    } else {
+      redactHeadersObject(headers);
+    }
   }
 
   function redactString(obj: GaxiosOptions, key: keyof GaxiosOptions) {
@@ -481,8 +503,11 @@
     defaultErrorRedactor({config: data.response.config});
     redactHeaders(data.response.headers);
 
-    redactString(data.response, 'data');
-    redactObject(data.response.data);
+    // workaround for `node-fetch`'s `.data` deprecation...
+    if ((data.response as {} as Response).bodyUsed) {
+      redactString(data.response, 'data');
+      redactObject(data.response.data);
+    }
   }
 
   return data;