react-http-query v2.3.1

Description

A simple React Query library that utilizes the window.fetch request function by default. It also supports providing an axios instance to replace the default window.fetch.

Table of contents

• Simple Usage
• makeRequest
  • Configurations
  • Usage Examples
    • GET
    • POST
    • Form Data Request
    • Other Request Methods
• useRequest
  • Parameter Properties
  • Usage Examples
• Request Provider
  • Properties
  • Usage Examples
• useRequestConfig
• useRequestData
  • Parameters
  • Usage Examples
• Interceptors
  • Request
  • Response

Simple Usage

import React from 'react';
import { useRequest } from 'react-http-query';

const App = () => {
    const [{data, loading, success, error}, makeRequest] = useRequest();

    React.useEffect(() => {
        makeRequest('https://example.com/users');
    }, [])

    return (<>
        { loading && <div>loading...</div> }
        { data && !loading 
            && <main>
                <p>{ data.name }</p>
                <p>{ data.age }</p>
            </main>
        }
        { error && !loading && <div>An error occur fetching user</div> }
    </>)
}

makeRequest

const [{}, makeRequest] = useRequest();

makeRequest is the function returned by the useRequest hook at array index 1, that is used in making your api call. It can be given any name depending on the request purpose e.g. makeLoginRequest makeDeleteUserRequest etc. It takes two parameters which are

• A required url, which could be an absolute url or a relative path if base url is provided in either the useRequest hook or Request Provider that wraps all your app components.
• An optional configuration object. It takes all properties that can be passed to window fetch function and some additional properties that is discussed below.

Configuration

Usage Examples

GET

import React from 'react';
import { useRequest } from 'react-http-query';

const App = () => {
    const [{data, loading, success, error}, makeUserRequest] = useRequest();

    React.useEffect(() => {
        // Generated url -> https://example.com/users?page=1&pageSize=20
        makeUserRequest('https://example.com/users', {
            query: { page: 1, pageSize: 20 },
            retries: 3,
        });
        // No need to explicitly passed the method. GET method is assumed if no body is passed.
    }, [])
}

POST

import { useRequest } from 'react-http-query';

const App = () => {
    const [{data, loading, success, error}, makeLoginRequest] = useRequest();

    const onFormSubmit = ({username, password}) => {
        makeLoginRequest('https://example.com/login', {
            body: { username, password },
            timeout: 5000 // 5 secs
        });
        // No need to explicitly passed the method. POST method is assumed when there is a body.
    }
}

Note: makeRequest function also returns the request's response if it is await in an async function const data = await makeRequest(/users), which implies a makeRequest instance can be used to make request to multiple endpoints. This would be a bad practice, as it is advice you create different instances for each request, so their state can be properly managed.

Form Data Request

import { useRequest } from 'react-http-query';

const App = () => { const {data, loading, success, error}, makeSignUpRequest = useRequest();

const onFormSubmit = ({username, password, event}) => {
    makeSignUpRequest('https://example.com/signup', {
        formData: { username, password, avatar: event.target.files[0] },
        successMessage: "Your profile have been successfully created."
    });
    // The request payload would be a FormData.
}

}

### Other Request Methods
To make http request other than `GET` or `POST`, the method has to be explicitly specified.
```jsx
import React from 'react';
import { useRequest } from 'react-http-query';

const App = () => {
    const [{data, loading, success, error}, makeProfileUpdateRequest] = useRequest();

    const onFormSubmit = ({lastName, address}) => {
        makeProfileUpdateRequest('https://example.com/user', {
            body: { lastName, address },
            method: "PUT",
            errorMessage: "An error occur updating your profile"
        });
        // The request payload would be a FormData.
    }
}

useRequest

const [{data, loading, success, error, message}, makeRequest] = useRequest();

The useRequest hook provides the request metadata which are:

• Request state
  • data: Any The data returned from the request.
  • loading: Boolean value indicating whether the request is ongoing.
  • success: Boolean value indicating if the request succeeded.
  • error: Boolean value indicating if the request failed.
  • message: String either the error or success message that could be retrieve from the request.
  • previousData: Any The data returned from the previous request.
  • refetch: Function A function that allows you to initiate a network request using the configuration of the most recent network request. It accepts an optional parameter, which represents query parameters. You can provide a partial set of query parameters, and these will be merged with the initial query parameters. When the refetch function is called, it disregards any cached responses from previous network requests and initiates a new network request. This ensures that you obtain fresh data from the server or endpoint.

Parameter Properties

useRequest it accepts two optional parameters.

The first parameters is an objects that allows of the below properties: | Properties | Description | | --- | --- | | name | The name of the request. This should be a unique identifier, different from any other name given to other request in your application. It is used to retrieve request data stored in the application state, localStorage or sessionStorage. | | baseUrl | The base URL of requests made by the makeRequest function. makeRequest can be provided with path instead of absolute url, if the baseUrl is assigned a value. | | onSuccess | A callback function that gets invoked when the request succeed. It receives the request's metadata, which includes the response body & derived success message if any. This callback can be used to perform any necessary operations when the request succeeds. | | onMount | A callback function that is called once your component mounts, it returns a makeRequest function as an argument, that could be used to make a request on mount of the components. | | onError | A callback function that gets invoked when the request fails. It receives the request's metadata, which includes the error body & derived error message if any. This callback can be used to perform any necessary operations when the request encounters an error. | | interceptors | This allow request to be intercepted at the component level before the call is being made or before the response are being passed to the component state. It allows two optional function parameters, which are response and request. See more about intercpetors | | localStorage | A Boolean value that determines if the request's response data should be stored in local storage. The stored value can be retrieved from any part of the application using the useRequestData with the name property. | | sessionStorage | A Boolean value that determines if the request's response data should be stored in session storage. The stored value can be retrieved from any part of the application using the useRequestData with the name property. | | memoryStorage | A Boolean value that determines if the request's response data should be stored in the application memory(state). A browser refresh would cause the data stored to be lost, except the request is made again. The stored value can be retrieved from any part of the application using the useRequestData with the name property. | | onUploadProgress | A Function that recieves progress events for uploads. @note available only when axios is provided in the RequestProvider. | | onDownloadProgress | A Function that recieves progress events for downloads. @note available only when axios is provided in the RequestProvider. | | enableRequest | Determines whether the request should be made to the server. If it's an array, waits until none of its items are undefined, null, or an empty string. If it's a non-array, waits until it resolves to a truthy value or 0. | | validateStatus | validateStatus defines whether to resolve or reject the promise for a given HTTP response status code. @note available only when axios is provided in the RequestProvider. |

The second parameter is a dependency array. When values in this array change, they trigger a rerun of the network request specified in the onMount property of the first parameter. If a network call is in progress when a dependency update occurs, that call is canceled.

Usage Examples

import { useRequest } from 'react-http-query';

const App = () => {
    const [enableButton, setEnableButton] = useState(true);
    const [{loading}, makeLoginRequest] = useRequest({
        name: 'user-profile',
        baseUrl: 'https://example.com',
        onSuccess: (response) => {
            /**
             * response data details
             * `statusText`: Request status text.
             * `headers`: Request headers.
             * `data`: Request response data.
             * `status`: Request status code.
             */
            navigate(`/dashboard/${response.data.data.id}`);
        },
        onError: (error) => {
            /**
             * error data details
             * `statusText`: Request status text.
             * `headers`: Request headers.
             * `data`: Request response data.
             * `status`: Request status code.
             */
            showToast(error.data.message);
            setEnableButton(true);
        },
        localStorage: true,
    });

    const onSubmitButtonClick = ({username, password}) => {
        setEnableButton(false);
        makeLoginRequest('/user/login', {
            body: { username, password },
            successMessage: "Login Successful!"
        });
    }
    ...
}

Refetch example.

import { useRequest } from 'react-http-query';

const App = () => {
    const [{refetch}] = useRequest({
        onMount: (makeUserListRequest) => 
            // request url would be `https://base-url.com/users?page=1&limit=20`
            makeUserListRequest('/users', { query: { page: 1, limit: 20 }})
    });

    return (
        // `refetch` takes an optional query params which would be merged with previous query 
        // params.
        // request url would be `https://base-url.com/users?page=2&limit=20` retaining the limit
        // query params.
        <button onClick={() => refetch({ page: 2 })}>Page 2</button>
    )
    ...
}

Interceptor example.

import { useRequest } from 'react-http-query';

const App = () => {
    const [{loading}, makeActivitiesRequest] = useRequest({
        baseUrl: 'https://example.com',
        interceptors: {
            // Do anything before sending the request, including updating the  request headers, body,
            //method, query parameters and url.
            request: (payload) => ({
                ...payload,
                headers: {
                    ...payload.headers,
                    Authorization: `Bearer ${authToken}`
                }
            })
        }
    });

    const onFetchActivities = () => {
        makeActivitiesRequest('/user/activities');
    }
    ...
}

Request Provider

The request provider provides a powerful means of managing/configuring all application request from a single point, such as intercepting & updating all requests, displaying error and success toast, setting loaders to be displayed for all requests, setting baseUrl and using path at every other point in your application and many more. It should ideally be the parent component to every other component making use of the useRequest() in your application. The properties table below shows all properties that can be assigned to the request provider

Properties

Usage Examples

import { useRequest, RequestProvider } from 'react-http-query';

const Profile = () => {
    const [{ data, loading }] = useRequest({
        // The baseUrl set in the RequestProvider would be prepend to the path of this request
        onMount: (makeRequest) => makeRequest('/profile')
    });

    return (
        <>
            { !loading && data 
                && <div>
                    <div>{data.user.name}</div>
                    <div>{data.user.age}</div>
                </div>
            }
        </>   
    )
}

const App = () => {

    return (
        {/* The RequestProvider can be implemented in a separate file and then use in your
          * App component. This so you will separate the concerns of the request configuration and
          * keep your app.js file clean. 
          */
         }
        <RequestProvider
            baseUrl="https://www.example.com"
            authToken={authToken}
            onError={(error) => {
                return <Toast message={error.data.message} />
            }}
            interceptors={{
                request: (payload) => ({
                    ...payload,
                    headers: {
                        ...payload.headers
                        // All request from the application would have this `csfrToken` on the request header
                        "x-csfr-token": csfrToken
                    }
                }),
                response: (payload) => {
                    // Action could be performed base on the request status, like navigating to the login page on invalid authentication
                    // error response.
                    if (payload.status === 401) {
                        navigate('/login');
                    }
                }
            }}
            // Timeout in `seconds` to show toast messages if provided.
            popupTimeout={10}
            // Request abort timeout in `milliseconds` if request duration exceeds the set `requestTimeout`
            requestTimeout={10000}
        >
            <Profile />
        </RequestProvider>
    )
}

useRequestConfig

The useRequestConfig returns properties that can be used to configure the application request from any part of the application. It also returns loading, that is either true or false depending on whether there is an ongoing request. Below are properties returned by useRequestConfig:

• loading: loading state of requests within the application.
• setAuthToken: Set the Authorization bearer token to be used for all requests. This could be after the user must have login to the application.
• setBaseUrl: Set the base URL to be used for all requests.

const { loading, setAuthToken, setBaseUrl } = useRequestConfig();

// Set the auth token that would be used by all request within the application
setAuthToken(authToken);

useRequestData

useRequestData is used to retrieve data save to the localStorage, sessionStorage, or memoryStorage using the assigned name. It allows two positional arguments | Argument | Description | Allowed Values | Required | | --- | --- | --- | --- | | name | The assigned request name. | string | yes | | storageLocation | The location specified for the data to be stored. If not provided, it checkes through all locations. If provided, it checks only the location and if not found, it returns undefined | memory | session | local | no |

Usage Examples

...
import { useRequest, RequestContext, useRequestData } from 'react-http-query';

const Login = () => {
    const [{}, makeLoginRequest] = useRequest({ 
        name: "user-profile", 
        localStorage: true,
        interceptors: {
            // The interceptor is to ensure only the user information is saved to the local storage,
            // rather than saving all information coming from the server, which could includes statusCode, successMessage, etc.
            response: (payload) => ({
                ...payload,
                data: payload.data?.data
            })
        } 
    })
    ...
}

const Dashboard = () => {
    const userProfile = useRequestData("user-profile", "local");
    const { setAuthToken } = useContext(RequestContext);

    React.useEffect(() => {
        setAuthToken(userProfile?.token);
    }, [setAuthToken, userProfile?.token])
    ...
}

useRequestData is not the only means of retrieving saved data. When data are saved to either the memoryStorage, sessionStorage, or localStorage and another request is made to the same endpoint, a check will be made to see if there is an existing saved data, if there is it returns the saved data, otherwise it makes another round of request. A new request will be made if there is a change in the query parameters or forceRefetch is set to true in the makeRequest config. This is especially useful for static data, such as list of countries, etc. as it reduces the number of server call.

const FirstCall = () => {
    [{}] = useRequest({ 
        memoryStorage: true,
        // Request gets to the sever, as this is the first call.
        onMount: (makeCountryLookupRequest) => makeCountryLookupRequest('/lookup/countries')
    });
}

const SecondCall = () => {
    // It is important to still set memoryStorage to true, on subsequent requests
    // This would ensure that the response are cached as well, if another call is made to the server.
    [{}] = useRequest({ 
        memoryStorage: true,
        // Request will not get to the server, saved data from the memory would be retrieved.
        // Response time would be faster than first call.
        onMount: (makeCountryLookupRequest) => makeCountryLookupRequest('/lookup/countries')
    });
}

const ThirdCall = () => {
    [{}] = useRequest({ 
        memoryStorage: true,
        // Request gets to the sever, because `forceRefetch` is set to `true`
        onMount: (makeCountryLookupRequest) => {
            makeCountryLookupRequest('/lookup/countries', { forceRefetch: true })
        }
    });
}

Interceptors

Interceptors are means to intercept requests, perform actions based on the request payload or update the request payload and intercept responses and perform given actions based on the response payload. Interceptors can be added to RequestProvider which is the app level interceptor, as it intercept all requests call within the application. Interceptors can also be added to useRequest, this only intercept the requests call made with the makeRequest function derived from the useRequest. When interceptor is provided both at the app level and also to useRequest, payload goes through the app level interceptor before getting to the useRequest interceptor. An update made to the payload at the app level interceptor would be available in the payload at the useRequest interceptor.

Request

Request interceptor intercept outgoing requests.

const App = () => {
    return (
        <RequestProvider
            baseUrl="https://www.example.com"
            interceptors={{
                request: (payload) => {
                    // Below are all the properties of the request interceptor payload.
                    // payload.headers
                    // payload.body
                    // payload.url
                    // payload.method
                    // payload.queryParam
                    return {
                        ...payload,
                        headers: {
                            ...payload.headers
                            "x-request-id": "1234"
                        }
                    }
                }
            }}
        >
            <Profile />
        </RequestProvider>
    )
}


const Profile = () => {
    const [{}, makeRequest] = useRequest({
        interceptors: {
            request: (payload) => {
                // The information added at the app level interceptor would be available in this 
                // interceptor. It's set value can be overwritten.
                console.log(payload.headers["x-request-id"]) // 123
                delete payload.headers["x-request-id"];
                return payload
            }
        }
    })
}

Response

Response interceptor intercept incoming responses.

const App = () => {
    return (
        <RequestProvider
            baseUrl="https://www.example.com"
            interceptors={{
                response: (payload) => {
                    // Below are all the properties of the response interceptor payload.
                    // payload.data
                    // payload.status
                    // payload.url
                    // payload.method
                    // payload.queryParam

                    // Only the data properties can be updated. Other properties are read-only.
                    return {
                        ...payload,
                        data: {
                            ...payload.data,
                            url: payload.url
                        }
                    }
                }
            }}
        >
            <Profile />
        </RequestProvider>
    )
}


const Profile = () => {
    const [{}, makeRequest] = useRequest({
        interceptors: {
            response: (payload) => {
                // The information added at the app level interceptor would be available in this 
                // interceptor
                console.log(payload.data.url) // prints the url added at the app level interceptor.
            }
        }
    })
}