react-fetch


react-fetch is a lightweight and straightforward react package designed to simplify data fetching in react applications. It provides an intuitive way to make HTTP requests and manage the state of the data, loading, and errors within your components.

Table of Contents

- Installation
- useFetch
- usePagination
- useInfiniteLoading
- useScrollRestoration
- useInfiniteScrollRestoration
- useIsOnline
- Loader Component
- GlobalLoader Component
- LoadingFallback Component
- LoadingSuspense Component
- RefreshControl Component
- Documentation
- Contributing
- License
- Contact

Installation

Install using Yarn:

``sh
yarn add @resourge/react-fetch
`

or NPM:

`sh
npm install @resourge/react-fetch --save
`

react-native

To use in react-native, it requires to use react-native-url-polyfill

`Typescript
// index.js
// Add
import 'react-native-url-polyfill/auto';
`

useFetch

useFetch is a custom react hook designed to simplify data fetching and state management within functional react components. It handles loading states, errors, data updates, and request aborting. This hook is particularly useful when working with APIs or fetching data from external sources.

Usage

To use useFetch, import it into your react component:

`JSX
import react from 'react'

import {
useFetch
} from '@resourge/react-fetch'

const MyComponent = () => {
const {
data,
error,
fetch,
isLoading,
setFetchState
} = useFetch(
() => {
return Http.get("url");
},
{
initialState: []
}
);

// Use data, error, fetch, isLoading, and setFetchState as needed

return (


useFetch accepts two parameters:

1. method: A function that performs the data fetching. It should return a Promise that resolves with the fetched data.
2. config: An optional configuration object with the following properties:
- enable (boolean, default: true): When false, useEffect will not trigger fetch.
- loadingService (string): Specifies a specific LoadingService instead of triggering the global one.
- deps (readonly array): useEffect dependencies.
- id (string): Assign a unique ID to the fetch request.
- initialState (any): Default data values.
- onEffectEnd (function): A function that executes only after useEffect completes.
- scrollRestoration (function or array of functions): Functions to restore scroll position.
- silent (boolean, default: false): When false, no loading will be triggered.

#### Examples

Fetch as useState and useEffect

`Javascript
const {
data,
error,
fetch,
isLoading,
setFetchState
} = useFetch(
() => {
return Http.get("url");
},
{
initialState: []
}
);

`

Fetch as useEffect

`Javascript
const {
error,
fetch,
isLoading
} = useFetch(
() => {
return Http.get("url");
},
{
deps: []
}
);
`

Only fetch

`Javascript
const {
error,
fetch,
isLoading
} = useFetch(
() => {
return Http.get("url");
}
);
`

$3

The Loading in useFetch can behave either globally or locally, depending on its usage within the useFetch hook.

- Global Loading: By default, loading will trigger a global loading state if not used within the component where useFetch is called. This means it will update a global loading indicator, potentially affecting other components listening for loading state changes.

- Local Loading: If isLoading is used within the component's rendering logic, loading will only trigger locally. This allows for more granular control over loading states within different parts of the application.

#### Examples

In the following example, isLoading is used within the component's rendering logic, causing it to trigger a local loading state:

`Javascript
const {
data,
error,
fetch,
isLoading,
setFetchState
} = useFetch(
() => {
return Http.get("url");
},
{
initialState: []
}
);

return (


`Javascript
const {
data,
error,
fetch,
setFetchState
} = useFetch(
() => {
return Http.get("url");
},
{
initialState: [],
// Optional, for triggering a specific loader other than the global
// loadingService: 'specificLoadingService' // This will trigger a
}
);
`

usePagination

usePagination is a custom react hook designed to facilitate managing pagination in react applications. It manages pagination, filtering, sorting, and data fetching, providing a seamless experience for handling large datasets. It's built on top of useFetch, so all configurations and methods are the same.

Usage

`JSX
import { usePagination } from '@resourge/react-fetch';

const MyComponent = () => {
const {
data,
isLoading,
error,
fetch,
changeItemsPerPage,
changePage,
resetPagination,
pagination,
sortTable
} = usePagination(
async (metadata) => {
// Implement your logic to fetch data based on metadata
const response = await Http.get("url");
return { data: response.data, totalItems: response.totalItems };
},
{
initialState: [],
}
);

if (isLoading) {
return

export default MyComponent;
`

$3

usePagination accepts two parameters:

1. method: A function that performs the data fetching. It should return a Promise that resolves with the fetched data.
2. config: An configuration object with the following properties:
- ...config (object): Same useFetch Parameters.
- pagination (object): Specifies the default pagination settings. This includes the initial page number and the number of items per page.
- filter (object): Specifies the default filter settings. This can include properties like filter criteria or initial filter values.
- sort (object): Specifies the default sorting settings. This can include properties like the initial sort order and column.

$3

- filter: Holds the current filter criteria used to query the data.
`typescript
const filter: UserFilter = {
name: "John",
age: 30,
};
`
- setFilter: A method to update the filter criteria
`typescript
setFilter({
page: 1,
perPage: 10,
sort: [{ orderBy: OrderByEnum.ASC, orderColumn: "name" }],
customFilter: "example",
});
`
- sortTable: Method to change the sorting of the table.

`typescript
// Using full sorting criteria
sortTable([{ orderBy: OrderByEnum.DESC, orderColumn: "date" }]);

// Using individual column sorting parameters
sortTable(OrderByEnum.ASC, "name");
`

- sort: Holds the current sorting criteria.
`typescript
sort: [
{ orderBy: OrderByEnum.ASC, orderColumn: "name" },
{ orderBy: OrderByEnum.DESC, orderColumn: "date" },
];
`
- changeItemsPerPage: Method to change the number of items displayed per page.
`typescript
changeItemsPerPage(20);
`
- changePage: Method to change the current page. Optionally accepts the total number of items.
`typescript
changePage(2);
`
- changePagination: Method to change both the current page and the number of items per page.
`typescript
changePagination(1, 50);
`
- changeTotalPages: Method to change the total number of pages based on the total number of items.
`typescript
changeTotalPages(200);
`
- data: The fetched data.
- error: Error state from the fetch operation.
- fetch: Method to refetch the data.
`typescript
fetch().then((data) => {
console.log("Fetched data:", data);
});
`
- getPaginationHref: Method to build an href for pagination navigation.
`typescript
getPaginationHref(3);
`
- isLoading: Loading state of the fetch operation.
- pagination: Current pagination parameters including page, items per page, total items, and total pages.
- reset: Method to reset the pagination, sort, and/or filter to their initial or provided values.

`typescript
reset();

reset({ filter: { name: "John" } });
`

- resetPagination: Method to reset the pagination to initial/default values.
`typescript
resetPagination();
`
- setPaginationState: Method to manually set the fetch state.
`typescript
setPaginationState([]);
`

useInfiniteLoading

useInfiniteLoading is a custom react hook designed to facilitate infinite loading in react applications. It manages pagination, filtering, sorting, and data fetching, providing a seamless experience for handling large datasets. It's built on top of useFetch, so all configurations and methods are the same.

Usage

`JSX
import { useInfiniteLoading } from '@resourge/react-fetch';

const MyComponent = () => {
const { data, isLoading, error, loadMore, changeItemsPerPage } = useInfiniteLoading(
async (metadata) => {
// Implement your logic to fetch data based on metadata
const response = await Http.get("url");
return { data: response.data, totalItems: response.totalItems };
},
{
initialState: [],
}
);

if (isLoading) {
return

export default MyComponent;
`

$3

useInfiniteLoading accepts two parameters:

1. method: A function that performs the data fetching. It should return a Promise that resolves with the fetched data.
2. config: An configuration object with the following properties:
- ...config (object): Same useFetch Parameters.
- pagination (object): Specifies the default pagination settings. This includes the initial page number and the number of items per page.
- filter (object): Specifies the default filter settings. This can include properties like filter criteria or initial filter values.
- sort (object): Specifies the default sorting settings. This can include properties like the initial sort order and column.

$3

Properties

useScrollRestoration

useScrollRestoration is a custom react hook designed to restore scroll positions when navigating between pages or components. It helps maintain scroll positions and ensuring a seamless user experience.

Usage

`javascript
import { useScrollRestoration } from "@resourge/react-fetch";

const MyComponent = () => {
// 'action' must be 'pop' for restoration to work;
const [scrollRestore, ref, onScroll] = useScrollRestoration("pop");

// Use scrollRestore, ref, and onScroll as needed

return (


useScrollRestoration accepts two parameters:

1. action: A string specifying the action that triggers scroll restoration. Only 'pop' will restore the scroll position.
1. scrollRestorationId: An optional unique ID categorizing the current component. It defaults to window.location.pathname if not provided.

$3

`Javascript
import { useScrollRestoration, useFetch } from '@resourge/react-fetch';
// or react-router
import { useAction } from '@resourge/react-router';

const MyComponent = () => {
// 'action' must be 'pop' for restoration to work;
const action = useAction();
const [scrollRestoration, ref, onScroll] = useScrollRestoration(action);

// Fetch data and trigger scroll restoration
// 'scrollRestoration' is a function to restore scroll position
const { data, fetch, error } = useFetch(
() => {
return HttpService.get("url");
},
{
initialState: [],
scrollRestoration // Pass scrollRestoration to useFetch for scroll restoration
}
);

return (
// onScroll is optional because ref will do, but for cases where ref can't listen to onScroll the function does the job


In this example, useScrollRestoration is used to manage scroll restoration based on the action parameter (which should be 'pop' for restoration to work) and a unique scrollRestorationId. It provides a scrollRestoration function to restore scroll position and can be used in conjunction with other hooks like useFetch for seamless scroll restoration during navigation.

_Note: If you choose not to use the ref returned by useScrollRestoration, the system will use the global window onScroll event to handle scroll restoration._

useInfiniteScrollRestoration

useInfiniteScrollRestoration is a custom react hook designed for restoring scroll positions in infinite scroll components within a react application. It enables seamless restoration of scroll positions when navigating back and forth between pages or components, enhancing the user experience.

Usage

`javascript
import { useInfiniteScrollRestoration } from "@resourge/react-fetch";

const MyComponent = () => {
// 'action' must be 'pop' for restoration to work;
const [scrollRestore, ref, onScroll] = useInfiniteScrollRestoration("pop");

// Use scrollRestore, ref, and onScroll as needed

return (


useInfiniteScrollRestoration accepts two parameters:

1. action: A string specifying the action that triggers scroll restoration. Only 'pop' will restore the scroll position.
1. scrollRestorationId: An optional unique ID categorizing the current component. It defaults to window.location.pathname if not provided.

$3

`Javascript
import { useInfiniteScrollRestoration, useInfiniteLoading } from '@resourge/react-fetch';
// or react-router
import { useAction } from '@resourge/react-router';

const MyComponent = () => {
// 'action' must be 'pop' for restoration to work;
const action = useAction();
const [scrollRestoration, ref, onScroll] = useInfiniteScrollRestoration(action);

// Fetch data and trigger scroll restoration
// 'scrollRestoration' is a function to restore scroll position
const { data, fetch, error } = useInfiniteLoading(
async (metadata) => {
// Implement your logic to fetch data based on metadata
const response = await Http.get("url");
return { data: response.data, totalItems: response.totalItems };
},
{
initialState: [],
scrollRestoration // Pass scrollRestoration to useFetch for scroll restoration
}
);

return (
// onScroll is optional because ref will do, but for cases where ref can't listen to onScroll the function does the job


In this example, useInfiniteScrollRestoration is used to manage scroll restoration based on the action parameter (which should be 'pop' for restoration to work) and a unique scrollRestorationId. It provides a scrollRestoration function to restore scroll position and can be used in conjunction with other hooks like useInfiniteLoading for seamless scroll restoration during navigation.

_Note: If you choose not to use the ref returned by useScrollRestoration, the system will use the global window onScroll event to handle scroll restoration._

useIsOnline

useIsOnline is a custom react hook designed to monitor the online status of the application.

$3

`javascript
import { useIsOnline } from "path/to/useIsOnline";

const MyComponent = () => {
const isOnline = useIsOnline();

return (


In this example, useIsOnline is used to monitor the online status of the application. The isOnline variable will be true when the application is online and false when offline. This can be useful for showing different UI components or handling network-related behavior accordingly.

Loader

The Loader component is a react component designed to handle loading states within your application. It works in conjunction with LoadingService to provide a way for useFetch to display loading indicators based on there state.

Props

loaderId

- Type: string
- Default: ''
- Description: Unique id to distinguish the Loader from other loaders. When not specified, it is treated as a global loader.

loadingElement or children

- Type: react.ReactNode
- Default: globalLoading
- Description: The loading element to display when the Loader is in a loading state. This element will be shown instead of the children when loading is true.


Usage

To use the Loader component, simply include it in your JSX with the desired loaderId and loadingElement:

`javascript
import react from "react";
import { Loader } from "@resourge/react-fetch";

const MyComponent = () => {
return (


In this example, the Loader component is used with a specific loaderId ("myLoaderId") to trigger loading based on the state of useFetch's with loadingService specified (in this case as "myLoaderId"). The default loadingElement will be displayed when the loader is in a loading state.

If you want to use the Loader component as the default loader (without a specific loaderId), simply omit the loaderId prop:

`javascript
import react from "react";
import { Loader } from "@resourge/react-fetch";

const MyComponent = () => {
return (


In this case, the Loader component will function as a global loader, meaning it will display the loadingElement or children for all useFetch without loadingService.

GlobalLoader

The GlobalLoader component is a react component designed to display a global loading indicator on the entire page. It utilizes the Loader component and createPortal from react to render the loading element as an overlay on top of the page content.

Props

loaderId

- Type: string
- Default: ''
- Description: Unique id to distinguish the GlobalLoader from other loaders. - When not specified, it functions as a global loader covering the entire page.

style

- Type: react.CSSProperties
- Default: {}
- Description: Custom styles to apply to the global loading overlay.

children

- Type: react.ReactNode
- Default:
- Description: The content to display within the global loading overlay. If not - provided, a default loading indicator will be used.

color

- Type: string
- Default: globalColor
- Description: The color of the loading indicator. Default is globalColor.

Usage

`javascript
import react from "react";
import { GlobalLoader } from "@resourge/react-fetch";

const MyComponent = () => {
return (


You can also provide custom loading content to the GlobalLoader:

`javascript
import react from "react";
import { GlobalLoader } from "@resourge/react-fetch";
import CustomLoadingComponent from "path/to/CustomLoadingComponent";

const MyComponent = () => {
return (


The LoadingFallback component is a react component designed to show a loading indicator on mount and hide it on unmount. It utilizes the LoadingService from the @resourge/http-service package to manage the loading state.

Usage

`javascript
import react from "react";
import { LoadingFallback } from "@resourge/react-fetch";

const MyComponent = () => {
return (


In this example, the LoadingFallback component will display a loading indicator when the component mounts, and it will hide the loading indicator when the component unmounts.

LoadingSuspense

The LoadingSuspense component is a react component designed to show a loading indicator when lazy-loaded components are being loaded. It utilizes react's Suspense component to handle the loading state and displays a LoadingFallback component as a fallback when the lazy components are loading.

Usage

`javascript
import react from "react";
import { LoadingSuspense } from "@resourge/react-fetch";

const MyLazyComponent = react.lazy(() => import("./MyLazyComponent"));

const MyComponent = () => {
return (


In this example, the LoadingSuspense component will display the LoadingFallback component while MyLazyComponent is being loaded lazily.

RefreshControl

RefreshControl is a react component designed to facilitate the implementation of infinite scrolling behavior with refresh controls in react applications. It provides a convenient way to manage scroll detection and trigger data loading for infinite scroll components. _Note: Browse only, use FlatList for react-native_

Usage

`tsx
import { RefreshControl } from "@resourge/react-fetch";

const MyComponent = ({ context }: { context: InfiniteLoadingReturn }) => {
return (
context={context}
detectionMargin="100%" // Optional: Set detection margin
renderComponent={({ isLastIncomplete, onClick }) => (
// Render your custom refresh control component here


export default MyComponent;
`

Props

context

- Type: object
- Description: Containing the context data provided by the useInfiniteLoading hook.

renderComponent

- Type: function
- Description: Renders the custom refresh control component. It receives props indicating whether the last page is incomplete and a function to trigger loading more data.

detectionMargin

- Type: function
- Description: By default, it is set to '100%'. Specifies the detection margin for intersection observer. Can be adjusted to fine-tune scroll detection behavior.

Documentation

For comprehensive documentation and usage examples, visit the react Fetch documentation.

Contributing

Contributions to @resourge/react-fetch` are welcome! To contribute, please follow the contributing guidelines.

License

Fetch is licensed under the MIT License.

Contact

For questions or support, please contact the maintainers:

- GitHub: Resourge