haper-hooks v1.2.1

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

Returned object

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

Returned object

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

Returned object

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

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

Returned object

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

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

Returned object

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

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

Returned object

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')
)