Haper hooks

haper-hooks is a small library with a few React hooks for easier data fetching from REST APIs. For better performance in SPA applications hooks automatically detects already unmounted components and cancels requests initialized by them if any is pending

Install

npm install --save haper-hooks

Usage

Quick example

import React, {} from 'react';
import {render} from 'react-dom';
import {HaperProvider, useCollection} from 'haper-hooks';

interface User {
    name: string
    surname: string
    email: string
}

function UsersList() {
    const {
        loading, //bool
        data, // Array<User>
        error, // Error | 'cancel'
    } = useCollection<User>('/user');

    return (
        <div>
            {loading && 'Loading'}
            {error && (error?.message || error)}
            {
                data.map(user => (
                    <p key={user.email}>{user.name} {user.surname}</p>
                ))
            }
        </div>
    );
}

render(
    <HaperProvider baseUrl="http://localhost:3001">
        <UsersList />
    </HaperProvider>,
    document.getElementById('root')
)

Hooks

useCollection

You should use it for simple and relatively small lists without pagination

Usage:

import {useCollection} from 'haper-hooks';

interface User {
    name: string
    surname: string
    email: string
}

function UsersList() {
    const {
        loading, //bool
        data, // Array<User>
        error, // Error | 'cancel'
    } = useCollection<User>('/user');

    return (
        <div>
            {loading && 'Loading'}
            {error && (error?.message || error)}
            {
                data.map(user => (
                    <p key={user.email}>{user.name} {user.surname}</p>
                ))
            }
        </div>

    );
}

Params

name	required	type	comment
endpoint	✅	string
params	❌	Partial< Params>|null	initial params
fetchOnInit	❌	boolean	should callback be called on component mount

Returned object

name	type	comment
reload	(newParams?: Partial< P >) => any	reload data with new params
loading	boolean	initial params
data	Array< T>	data fetched for current page
error	E

useEntity

You should use it for single data entity

Usage

import {useEntity} from 'haper-hooks';

interface User {
    name: string
    surname: string
    email: string
}

function UserProfile() {
    const {
        loading, //bool
        data: user, // User
        error, // Error | 'cancel'
    } = useEntity<User>('/user');

    return (
        <div>
            {loading && 'Loading'}
            {error && (error?.message || error)}
            <h2>{user?.name} {user?.surname}</h2>
            <p>{user?.email}</p>
        </div>

    );
}

Params

name	required	type	comment
endpoint	✅	string
params	❌	Partial< Params>|null	initial params
fetchOnInit	❌	boolean	should callback be called on component mount

Returned object

name	type	comment
reload	(newParams?: Partial< P >) => any	reload data with new params
loading	boolean	initial params
data	Array< T>	data fetched for current page
error	E

useCollectionWithPagination

This hook contains more logic focused on lists pagination. Values like offset and size after set in frontend are send to backend with request as query params along with other user params if such were specified

Usage

import {useCollectionWithPagination} from 'haper-hooks';

interface User {
    name: string
    surname: string
    email: string
}

function UserList() {
    const {
            data,
            allPages,
            reload: reloadList,
            loading,
            next,
            prev,
            currentPage
        } = useCollectionWithPagination<DataModel, Filters>({
            endpoint: '/user',
            currentPage: 1
        });

    return (
        <div>
            {loading && 'Loading'}
            {error && (error?.message || error)}
            {
                data.map(user => (
                    <p key={user.email}>{user.name} {user.surname}</p>
                ))
            }
            <p>Page {currentPage}/${allPages}</p>
            <button onClick={next}>next page</button>
            <button onClick={prev}>prev page</button>
            <button onClick={reloadList}>reload list</button>
            <button onClick={() => {
                reloadList({
                    name: 'Dawid'
                }); // this will send request with query params like: /user?offset=x&size=y&name=Dawid
            }}>Show all users wit name Dawid</button>
        </div>
    );
}

Params

name	required	type	comment
endpoint	✅	string
userParams	❌	Partial< Params>	initial params
currentPage	❌	number	initial page
getTotal	❌	(response: PaginationResponse ) => number	extractor function for total value from PaginationResponse
getData	❌	(response: PaginationResponse ) => Array< T>	extractor function for data value from PaginationResponse
getPaginationParams	❌	({ size, offset}, userParams) => object	composer function for request params from internal size and offset and users additional params for example filters etc.

Returned object

name	type	comment
setSize	(size: number ) => any	determines how many data entities should be fetched per request
loading	boolean	initial params
data	Array< T>	data fetched for current page
error	E
allPages	number
currentPage	number
next	() => any	go to next page
prev	() => any	go to prev page
setPage	(page:number) => any
reload	(newParams?: Partial , pageNumber?: number ) => any	reload data with new params

Usage with haper api builder

haper gives you additional approach to create api with which you can better encapsulate your endpoints and combine them with models in one place (if you using TypeScript, which I recommend)

For example you can create endpoint function and indicate model it takes as a parameters and which it will return after run

import {createApiBuilder, createHaper} from 'haper';

const haper = createHaper({});
const api = createApiBuilder(haper);

interface User {
    id: number
    name: string
}

interface ApiList<T> {
    total: number,
    data: T[]
}

interface UserListParams {
    size: number,
    offset: number,
    search?: string
}

export const getUsersList = api.get<ApiList<User>, UserListParams>(`/employee/users`);

async function main() {
    // you can use fetching function even without hooks, hooks are just additional layer
    const usersResponse = await getUsersList({
       size: 10,
       offset: 0
    });
    
    console.log(usersResponse); // { total: 100, data: [10xUser] }
}

main();

below I present examples of using hooks

useQueryCollection

Example:

import { useQueryCollection } from 'haper-hooks';

// useQuery* first param of hook is always getData function which fetch data for hook and returns it in a required by hook shape
const {
        data,
        loading,
        error,
        cancel
    } = useQueryCollection<User, UserListParams>(
        // first function is fetching function, it fetches users list by calling haper endpoint defined before
        async ({ requestId, params }) => {
            // if you want automatic request cancellation on unmount you need to pass request id to fetching function
            const tempData = await getUsersList(params, requestId);
    
            return tempData.data; // in useQueryCollection we need to return only array of T, so here we returning it
        },
        // as a second argument you can pass initial values for params object 
        {
            offset: 0,
            size: 10
        }
    );

Params

name	required	type	comment
getData	✅	(args: {requestId: string, initial: boolean, params: Partial< P >}) => Promise<T[]>
initialParams	❌	Partial< P >	initial params

get data initial param indicates if it's first call on component mount

Returned object

name	type	comment
loading	boolean	loading indicator
initial	boolean	is first, initial fetch
data	Array< T >	fetched data
params	Partial< P >	current params object
error	Error	undefined
cancel	() => any	cancels current request if pending
mutate	(params: Partial< P >) => any	changes request params and fetches new data
reload	() => any	reload data without changing params

useQueryCollectionWithPagination

Example:

import { useQueryCollectionWithPagination } from 'haper-hooks';

// useQuery* first param of hook is always getData function which fetch data for hook and returns it in a required by hook shape
const {
    data,
    next,
    pageNumber,
    params,
    prev,
    setPageSize,
    mutate,
    loading,
    pageSize,
    initial,
    total,
} = useQueryCollectionWithPagination<User, UserListParams>(
     ({ pageSize, pageNumber, params }) => {
        return getUsersList(JSON.parse(JSON.stringify({
            ...params,
            offset: pageNumber * pageSize,
            size: pageSize,
        })));
    },
    {
        pageSize: 20,
        pageNumber: 1,
    },
);

function goToNextPage() {
    next();
}

function filterByName(name: string) {
  mutate({
    pageNumber: 1,
    resetData: true,
    params: {
        search: name
    }
  });
}

Params

name	required	type	comment
getData	✅	(args: {requestId: string, initial: boolean, params: Partial< P >}) => Promise<T[]>
initialPaginationData	❌	{pageSize: number, pageNumber: number, params: Partial< P >}	pagination initial data

get data initial param indicates if it's first call on component mount

Returned object

name	type	comment
loading	boolean	loading indicator
data	Array< T >	fetched data
error	Error	undefined
total	number	total items number (obtained from response)
pageSize	number	current page size
pageNumber	number	current page number
totalPages	number	total pages (obtained from response)
setPageSize	(size: number) => any	set items per page
setPage	(page: number) => any	set current page number
next	() => any	go to next page
prev	() => any	go to prev page
cancel	() => any	cancels current request if pending
resetData	() => any	reset current data
mutate	(params: Partial< P >) => any	changes request params and fetches new data

useQueryEntity

Example:

import { useQueryCollection } from 'haper-hooks';

// useQuery* first param of hook is always getData function which fetch data for hook and returns it in a required by hook shape
const {
        data,
        loading,
        error,
        cancel
    } = useQueryCollection<User, GetUserParams>(
        ({ requestId, params }) => {
            // if you want automatic request cancellation on unmount you need to pass request id to fetching function
            return getUser(params, requestId);
        },
    );

Params

name	required	type	comment
getData	✅	(args: {requestId: string, initial: boolean, params: Partial< P >}) => Promise
initialParams	❌	Partial< P >	initial params

get data initial param indicates if it's first call on component mount

Returned object

name	type	comment
loading	boolean	loading indicator
data	T	undefined
error	Error	undefined
cancel	() => any	cancels current request if pending

Most common cases

Provide custom haper instance

Most of the time I use raw haper for other fetching tasks along with haper-hooks and I like to create it's instance by myself, register some interceptors etc. in that case I want to provide my custom instance of haper to all haper-hooks. This is example how you can do it

import React, {} from 'react';
import {render} from 'react-dom';
import {HaperProvider, useCollection} from 'haper-hooks';
import {createHaper} from 'haper';

const haper = createHaper({});

haper.registerResponseDataInterceptor('* * *', (apiResponse: { error: boolean, result: any }) => {
    if (apiResponse.error) {
        throw new Error('Api error');
    }

    return apiResponse.result;
});

interface User {
    name: string
    surname: string
    email: string
    id: number
}

function UsersList() {
    const {
        loading, //bool
        data, // Array<User>
        error, // Error | 'cancel'
        reload
    } = useCollection<User>('/user');
    
    return (
        <div>
            {loading && 'Loading'}
            {error && (error?.message || error)}
            {
                data.map(user => (
                    <button 
                        key={user.email} 
                        onClick={async () => {
                            await haper.delete(`/user/${user.id}`);
                            reload();
                        }}
                    >
                        Delete user {user.name} {user.surname}
                    </button>
                ))
            }
        </div>
    );
}

render(
    <HaperProvider haperInstance={haper}>
        <UsersList />
    </HaperProvider>,
    document.getElementById('root')
)