Skip to content

xunmi1/http-client

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

68 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

@xunmi/http-client

ci codecov npm bundle size npm version

An HTTP client based on the Fetch API.

The target is modern browsers. For isomorphic usage, you can polyfill (make sure to polyfill the global environment), for example: cross fetch.

Install

  • NPM

    npm install @xunmi/http-client
    # or
    yarn add @xunmi/http-client
  • CDN

    <script src="https://cdn.jsdelivr.net/npm/@xunmi/http-client"></script>

Usage

import HttpClient from '@xunmi/http-client';

const httpClient = new HttpClient({ baseURL: 'https://api.example.com/' });

httpClient
  .get('resource')
  .then(result => {
    // do something
  })
  .catch(error => {
    // handle error
  });

Request Method Aliases

Provide method aliases

import HttpClient from '@xunmi/http-client';

const httpClient = new HttpClient(options);

httpClient.request(url, options);

httpClient.get(url, options);

httpClient.post(url, options);

httpClient.delete(url, options);

httpClient.put(url, options);

httpClient.patch(url, options);

httpClient.head(url, options);

httpClient.options(url, options);

Request Options

RequestOptions is an extension of Request parameters.

interface RequestOptions extends RequestInit {
  // Request method.
  // The default is 'GET'.
  method?: string;

  // The request credentials you want to use for the request.
  // The default is 'same-origin'.
  credentials?: 'include' | 'omit' | 'same-origin';

  // The type of data that the server will respond.
  // The default is 'json'.
  responseType?: 'json' | 'text' | 'arrayBuffer' | 'blob' | 'formData';

  // The `baseURL` to use in case url is a relative URL.
  baseURL?: string;

  // The data to be sent as the request body.
  // It will be serialized automatically when is a plain object.
  // When using the `body` option at the same time, use `body` first.
  data?: Record<string, any> | any[] | BodyInit;

  // The URL parameters to be sent with the request.
  // It will append when `url` contains parameters.
  params?: Record<string, any> | any[][] | string | URLSearchParams;

  // The number of milliseconds a request can take before automatically being terminated.
  // The default is `undefined` (no timeout).
  timeout?: number;

  // Download progress event handler.
  onDownloadProgress?: (event: { total: number; loaded: number; done: boolean; value?: any }) => void;
}

Default Return Value

The response for a request contains the following information.

The final return value depends on the user's first middleware.

interface ReturnValue {
  // The server's response data.
  data: any;
  // The status code of the response.
  status: number;
  // The status message corresponding to the status code.
  statusText: string;
  // The Headers object associated with the response.
  headers: Headers;
}

Middleware

In order to facilitate request processing and functional extension, HttpClient used a middleware model.

Example:

  • Logger middleware.

    const httpClient = new HttpClient();
    
    // Logger middleware
    httpClient.use(async (ctx, next) => {
      const start = Date.now();
      const result = await next();
      const cost = Date.now() - start;
      console.log(`${ctx.method} ${ctx.url} - ${cost}ms`);
      return result;
    });
  • Use middleware to get Response object to replace the default return value.

    httpClient.use((ctx, next) => next().then(() => ctx.response));
    
    httpClient.get('resource').then(res => {
      console.log(res instanceof Response); // true
    });

Note:

  • next can only be called once in one middleware.
  • ctx.response is undefined before next is called.

Middleware Order

httpClient.use(async (ctx, next) => {
  console.log(1);
  await next();
  console.log(4);
});

httpClient.use(async (ctx, next) => {
  console.log(2);
  await next();
  console.log(3);
});

The order of multiple middleware:

1 -> 2 -> fetch -> 3 -> 4

Context

Each middleware receives a Context object that encapsulates an incoming request options and the corresponding response.

httpClient.use((ctx: Context, next: Next) => next());
  • ctx.request: Request options after conversion.

    interface ContextRequest {
      url: string;
      params: URLSearchParams;
      headers: Headers;
      // ...
    }
  • ctx.response: Response object, and attached the converted response (data).

  • Request aliases (getter):

    • ctx.url
    • ctx.method
  • Response aliases (getter):

    • ctx.status
    • ctx.statusText
    • ctx.headers
    • ctx.data

Exception

If there is an error in the request, an Exception will be thrown.

Exception Type

You can check the Exception's name to determine the error type.

  • HttpError: Status code is not in the range of 200 - 299. (name: HTTP_ERROR)

  • TimeoutError: The error thrown when the request times out. (name: TIMEOUT_ERROR)

  • ParseError: The error thrown when the parsing of response fails, then maybe you need to check the responseType. (name: PARSE_ERROR)

  • AbortError: The error thrown when the request has been aborted. (name: ABORT_ERROR)

Exception Handling

You can use middleware for unified handling, or use catch to handle a single request.

Example:

const Exception = HttpClient.Exception;
const httpClient = new HttpClient();

httpClient.use((ctx, next) => {
  return next().catch(error => {
    if (error instanceof Exception) {
      if (error.name === Exception.HTTP_ERROR) {
        // request context
        console.log(error.context);
      }
    }
    return Promise.reject(error);
  });
});

Use Cases

Files Uploading

const formData = new FormData();
// mock file
const file = new File(['foo'], 'foo.txt', { type: 'text/plain' });
formData.append('file', file);

httpClient.post('upload', { data: formData });

Cancellation

Abort the request using AbortController API.

const Exception = HttpClient.Exception;
const controller = new AbortController();

setTimeout(() => controller.abort(), 5000);

httpClient.get('resource', { signal: controller.signal }).catch(error => {
  if (error instanceof Exception && error.name === Exception.ABORT_ERROR) {
    console.log(`'${error.context.url}' has aborted.`);
  }
});