feat: fetch (POC)

README.md

@@ -4,7 +4,7 @@
 [![codecov](https://codecov.io/gh/googleapis/gaxios/branch/master/graph/badge.svg)](https://codecov.io/gh/googleapis/gaxios)
 [![Code Style: Google](https://img.shields.io/badge/code%20style-google-blueviolet.svg)](https://github.com/google/gts)
 
-> An HTTP request client that provides an `axios` like interface over top of `node-fetch`.
+> An HTTP request client that provides an `axios` like interface over top of `fetch`.
 
 ## Install
 
@@ -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: {
@@ -114,9 +110,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.

package.json

@@ -71,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",
@@ -85,8 +85,6 @@
   "dependencies": {
     "extend": "^3.0.2",
     "https-proxy-agent": "^7.0.1",
-    "is-stream": "^2.0.0",
-    "node-fetch": "^3.3.2",
     "uuid": "^9.0.1"
   }
 }

src/common.ts

@@ -118,22 +118,17 @@ export class GaxiosError<T = any> extends Error {
   }
 }
 
+/**
+ * @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,10 +139,12 @@ export interface GaxiosMultipartOptions {
 /**
  * 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,
@@ -169,20 +166,38 @@ export interface GaxiosOptions {
     | '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.
+   */
   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:
+   *
+   * @example
+   *
+   * {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.
    */
   maxContentLength?: number;
-  /**
-   * The maximum number of redirects to follow. Defaults to 20.
-   */
-  maxRedirects?: number;
-  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;
@@ -203,15 +218,24 @@ export interface GaxiosOptions {
   validateStatus?: (status: number) => boolean;
   retryConfig?: RetryConfig;
   retry?: boolean;
-  // Enables aborting via AbortController
+  /**
+   * Enables aborting via {@link AbortController}
+   */
   signal?: AbortSignal;
-  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;
@@ -258,7 +282,7 @@ export interface GaxiosOptions {
   errorRedactor?: typeof defaultErrorRedactor | false;
 }
 /**
- * A partial object of `GaxiosResponse` with only redactable keys
+ * A partial object of `GaxiosOptions` with only redactable keys
  *
  * @experimental
  */
@@ -330,41 +354,6 @@ export interface RetryConfig {
   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':
@@ -395,23 +384,27 @@ export function defaultErrorRedactor<T = any>(data: {
   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)) {
-      // any casing of `Authentication`
-      if (/^authentication$/i.test(key)) {
-        headers[key] = REDACT;
-      }
+    const source: string[] =
+      headers instanceof Headers
+        ? // TS is missing Headers#keys at the time of writing
+          (headers as {} as {keys(): string[]}).keys()
+        : Object.keys(headers);
 
+    for (const key of source) {
+      // any casing of `Authentication`
       // 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;
+      if (
+        /^authentication$/i.test(key) ||
+        /^authorization$/i.test(key) ||
+        /secret/i.test(key)
+      ) {
+        headers instanceof Headers
+          ? headers.set(key, REDACT)
+          : (headers[key] = REDACT);
       }
     }
   }