[General FE] Build your HttpClient using window.fetch

[reboottime]

Overview

This article presents the use cases of an HTTP client and provides a solution for customizing a http client util utilizing window.fetch.

Requirements Analysis

1. In certain scenarios, a single page application might utilize multiple API service resources, necessitating the customization of each request group with its distinct API base URL.
2. Learning from the popular http client solution, axios.js, a http client needs to offer http request methods directly (such as DELETE, GET, PATCH, PUT, or POST). It would be highly beneficial if the HTTP client utility could directly expose these methods for ease of use. For example

httpClientInstance.get
httpClientInstance.post

HttpClient.get
HttpClient.post

3. Support for retrying a failed request, ensuring that the system can automatically attempt the request again in case of failure
4. Support aborting a request when necessary, for example, when a component is unmounted then corresponding request needs to be cancelled.

[reboottime]

Create the basic HttpClient that makes http request

Here is the source code hosted on gist.

In the sample code, there are two technical details we want to pay attention

1. How to handle the header for form data
2. How to handle response data

Side Notes

1. When uploading files, form data is typically used, and in some cases, to pass json data together with some file data, so you need to transform the whole json data into Form Data .
2. When the backend returns a status code equal to or greater than 400, window.fetch does not consider the HTTP request as failed. Therefore, we rely on the response.ok property to determine whether an HTTP request was successful or not.
3. Since the response from backend side could be a pure string, the best way to handle window.fetch response parsing is to translate the response as string first, then try converse the response as a json

const response = await fetch(url, conf);
    const text = await response.text();

    // window.fetch sets ok as true only if the response http code is between 200 ~ 299
    // Here we return early
    if (!response.ok) {
      return Promise.reject(
        new Error(`HTTP error! status: ${response.status}, info: ${text}`)
      );
    }

    try {
      return JSON.parse(text) as T;
    } catch {
      return text as T;
    }

[reboottime]

Supporting Cancelling HTTP Requests

The underhood support by browser

Modern browser has an AbortController interface that represents a controller object that allows you to abort one or more Web requests as and when desired.

To combine the abort controller with an http request triggered by window.fetch, we need to give the abort controller signal to the request init. In the following example, the fetch() method is passed a second parameter with the signal property of the AbortController. This enables the request to be cancelled if needed by calling the abort() method of the AbortController.

const controller = new AbortController();
const { abort, signal } = controller;

fetch(url, { signal })
    .then((response) => {
      console.log("Download complete", response);
    })
    .catch((err) => {
      console.error(`Download error: ${err.message}`);
    });

// To cancel the request associated with the above signal:
abort();

My final solution

export default class HttpClient implements IHttpClient {
  private instance: IHttpClient;
  private controllers = new Map<string, AbortController>();

  constructor(baseUri: string, options?: HttpClientOptions) {
    this.instance = new _HttpClient(baseUri, options);
  }

  abort = (options: RequestConf) => {
    const key = this.getControllerKey(options);

    const controller = this.controllers.get(key);

    if (controller) {
      controller.abort();
      this.controllers.delete(key);
    }
  };

  delete = <T>(options: Omit<RequestConf, 'method' | 'data'>) => {
    return this.request<T>('DELETE', options);
  };

  get = <T>(options: Omit<RequestConf, 'method' | 'data'>) => {
    return this.request<T>('GET', options);
  };

  patch = <T>(options: Omit<RequestConf, 'method'>) => {
    return this.request<T>('PATCH', options);
  };

  put = <T>(conf: Omit<RequestConf, 'method'>) => {
    return this.request<T>('PUT', conf);
  };

  post = <T>(conf: Omit<RequestConf, 'method'>) => {
    return this.request<T>('POST', conf);
  };

  private request = async <T>(
    method: HttpMethods,
    options: typeof method extends 'GET' | 'DELETE'
      ? Omit<RequestConf, 'method' | 'data'>
      : Omit<RequestConf, 'method'>
  ) => {
    let controller: AbortController;
    let controllerKey = '';

    if (!options.signal) {
      controller = new AbortController();
      controllerKey = this.getControllerKey({ ...options, method });

      options.signal = controller.signal;
      this.controllers.set(controllerKey, controller);
    }

    const methodName = method.toLowerCase() as Lowercase<HttpMethods>;

    try {
      const result = await this.instance[methodName](options);

      return result as T;
    } catch (e) {
      return Promise.reject(e);
    } finally {
      this.controllers.delete(controllerKey);
    }
  };

  private getControllerKey(options: RequestConf) {
    const url = options.apiPath;
    const method = options.method;
    const params = ['GET' , 'DELETE'].includes(method)
      ? (JSON.stringify(options.query) || '')
      : (JSON.stringify(options.data) || '');

    const key = `${url}:${method}:${params}`;

    return key;
  }
}

References:

1. MDN AbortController
2. MDN use signal with window.fetch()

[reboottime]

Support retry

When using an HTTP client with React Query, you may not need to add retry support since React Query provides retry configuration out of the box for query and mutation requests.

If supporting retry configuration is still a thing for you, here is an example you about supporting retry times and retry delays for an http request

function fetchWithRetry(url: string, options: RequestInit, retries = 3, delay = 1000) {
  return new Promise((resolve, reject) => {
    const wrappedFetch = (attempt: number) => {
      fetch(url, options)
        .then(response => {
          if (response.ok) {
            resolve(response);
          } else {
            throw new Error(`Fetch failed with status ${response.status}`);
          }
        })
        .catch(error => {
          if (attempt < retries) {
            console.warn(`Fetch failed, retrying in ${delay}ms (${attempt + 1}/${retries})`);
            setTimeout(() => wrappedFetch(attempt + 1), delay);
          } else {
            reject(error);
          }
        });
    };
    wrappedFetch(0);
  });
}

[reboottime]

What about canceling a request using axios.js lib

import axios, { CancelToken } from 'axios';

const source = CancelToken.source();

axios.get('/api/data', { cancelToken: source.token })
  .then(response => {
    // Handle the response
  })
  .catch(error => {
    if (axios.isCancel(error)) {
      console.log('Request canceled', error.message);
    } else {
      // Handle the error
    }
  });

source.cancel('Request canceled');

[reboottime]

Compatibility

Compatibility of window.fetch

window.fetch is supported by most modern desktop and mobile browsers. Here is a list of the desktop browsers and mobile browsers that support window.fetch:

Desktop Browsers:

• Chrome (since version 42)
• Firefox (since version 39)
• Safari (since version 10)
• Edge (since version 15)
• Opera (since version 29)
• Internet Explorer (since version 11)

Mobile Browsers:

• iOS Safari (since version 10)
• Android Browser (since version 4.4 KitKat)
• Chrome for Android (since version 42)
• Firefox for Android (since version 56)
• Opera for Android (since version 29)
• Samsung Internet (since version 4.0)

Note that some older versions of these browsers may not support window.fetch.

Compatibility of AbortController

AbortController is a relatively new feature introduced in ECMAScript 2017, so it is not supported by all browsers, especially older ones. Here is a list of the desktop and mobile browsers that support AbortController:

Desktop Browsers:

• Chrome (since version 66)
• Firefox (since version 57)
• Safari (since version 12)
• Edge (since version 79)
• Opera (since version 53)

Mobile Browsers:

• iOS Safari (since version 12.2)
• Chrome for Android (since version 66)
• Firefox for Android (since version 57)
• Opera for Android (since version 53)
• Samsung Internet (since version 9.0)

Note that some older versions of these browsers may not support AbortController. If you need to support older browsers, you can use a polyfill such as abortcontroller-polyfill, which provides a similar functionality using other browser APIs.