Ratios

A React hook library for managing axios requests, includes cancellation mechanism.

Installation

• If you're using yarn: yarn add ratios
• If you're using npm: npm install ratios --save

Demo

See live demo on Stackblitz.

For more information about why we should cancel a request before component unmounts, please see this article.

Basic usage

1. First, manage your axios requests in a proper way

// File: /src/apis/user.js
import axios from "axios";

const instance = axios.create({
  baseURL: "/api/users",
  headers: {
    "Content-Type": "application/json",
  },
  // ...
});

const UserAPI = {
  getAll: (config) => instance.get("", config),
  create: (data) => (config) => instance.post("", data, config),
  updateById: (id, data) => (config) => instance.put(`/${id}`, data, config),
  deleteById: (id) => (config) => instance.delete(`/${id}`, config),
};

export default UserAPI;

2. Import the "useAxiosRequest" hook from Ratios, and use one of the axios requests we just created as argument

import React from "react";
import { useAxiosRequest } from "ratios";
import UserAPI from "../apis/user";

const MyComponent = () => {
  const getUsersRequest = useAxiosRequest(UserAPI.getAll);

  return (
    <div>
      {getUsersRequest.isLoading ? (
        "Loading..."
      ) : (
        <ol>
          {getUsersRequest.data.map((user) => (
            <li key={user.id}>{user.name}</li>
          ))}
        </ol>
      )}
    </div>
  );
};

export default MyComponent;

And that's it! The hook will cancel the request for you when the component unmounts.

Advanced usage

1. With custom config (e.g, query parameters)

import React, { useState } from "react";
import { useAxiosRequest } from "ratios";
import UserAPI from "../apis/user";

const MyComponent = () => {
  const [filter, setFilter] = useState({
    name: "",
    age: 5,
  });

  const getUsersRequest = useAxiosRequest((cancelTokenConfig) =>
    UserAPI.getByQuery({
      ...cancelTokenConfig,
      params: filter,
    })
  );

  // Your other codes
};

2. With custom arguments (e.g, create user)

import React, { useState } from "react";
import { useAxiosRequest } from "ratios";
import UserAPI from "../apis/user";

const MyComponent = () => {
  const [form, setForm] = useState({
    name: "John Doe",
    age: 10,
  });

  const createUserRequest = useAxiosRequest(UserAPI.create(form), {
    defaultIsLoading: false,
    immediate: false,
    onError: handleError,
  });

  const handleSubmitClick = async () => {
    const createdUser = await createUserRequest.execute();
    console.log("Created user: ", createdUser);
  };

  const handleError = (error) => {
    console.log("Something went wrong.");
    console.error(error);
  };

  // Your other codes
};

3. useCancelTokenSource hook

If you just want to apply cancellation mechanism to your existing app, you can use the "useCancelTokenSource" hook.

import { useCancelTokenSource } from "ratios";

const MyComponent = () => {
  const cancelTokenSource = useCancelTokenSource();

  const myFunction = async () => {
    try {
      const { data } = await myAPI.getSomething({
        cancelToken: cancelTokenSource.token,
      });
      console.log(data);
    } catch (error) {
      if (cancelTokenSource.isCancelError(error)) {
        console.log("Request is cancelled.");
      } else {
        throw error;
      }
  };

  // Your other codes
};

The request will be cancelled automatically when component unmounts.

API

1. Properties for useAxiosRequest()

| key | Type | Description | | --------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | isLoading | boolean | If the request is still going on. | | data | <T = any> | The data property returned from axios response. | | setData | (callback: (prevData: T) => T) | The function to update data. | | executed | boolean | If the request has been executed. | | execute | () => Promise<T> | Execute the request manually. If the isLoading property is still true, then it will NOT execute the request. Will return the data property from axios response if success. |

2. Options for useAxiosRequest()

| key | Type | Required | Default Value | Description | | ---------------- | --------------------- | -------- | ------------- | ----------------------------------------------------------------------------- | | defaultIsLoading | boolean | false | true | The default value of request.isLoading. | | defaultData | any | false | undefined | The default value of request.data. | | immediate | boolean | false | true | If the request should be executed immediately after the component is mounted. | | cancelPrevious | boolean | false | true | If the previous request should be cancelled before executing a new one. | | onSuccess | (data: T) => any | false | undefined | Function to execute when API is successfully executed. | | onError | (error: any) => any | false | undefined | Function to execute when an error occurred during API execution. | | onCancelled | (error: any) => any | false | undefined | Function to execute when the request is cancelled. |

3. Properties for useCancelTokenSource()

| key | Type | Description | | ------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------- | | token | CancelToken | The cancel token. | | cancel | () => CancelToken | undefined | Return next token if repeatable is true, else return undefined. | | isCancelError | (value: any) => boolean | Use this method to check if an error is thrown due to cancellation. This method equals to axios.isCancel. |

4. Options for useCancelTokenSource()

| key | Type | Required | Default Value | Description | | ---------- | --------- | -------- | ------------- | ---------------------------------------- | | repeatable | boolean | false | true | If the token can be used multiple times. |