React Use Query

A fast and efficient library for making requests and manage state result in a global level, that give data access from all components of any level, using in React with cache and browser event superpowers. From version 2 was itroduced a custom global state management system, check it out here.

  

New version of react use query library. Check on npm and github.

🎉 Version 2.0.x is live 🎉

Check out for changes in the CHANGELOG:

Changelog

Supporting the project

Maintaining a project takes time. To help allocate time, you can Buy Me a Coffee 😉

What is React Use Query?

Package to manage all types of queries, using useQuery(url, options) hook, with cache control system and granular access to context state. It can be used to optimize all request process.

It is fast and don't make useless request thanks to cache control system. It can also give you access to context state everywhere in your app thanks to useQueryState(name) hook and .

If you need to trigger request just after an event like button click, in an efficient way, you should use useQueryEvent(url, options) hook instead (example here).

Contents

1. Install
2. Get Started
3. Options
4. Returns
5. Usage Examples
- 5.1. Basic
- 5.2. Pagination
- 5.3. Request on event
- 5.4. Using selector
6. Global state management
- 6.1. Working with global state

Install

Inside your project run on terminal:

``cmd
npm i @aredant/use-query-manager
`

or

`cmd
yarn add @aredant/use-query-manager
`

The only one dependency that will be installed is @aredant/use-query-manager.

Get Started

Import the package on your main file and wrap project inside QueryProvider.

`js
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.jsx'

import { QueryProvider } from "@aredant/use-query-manager"

import './index.css'

ReactDOM.createRoot(document.getElementById('root')).render(


,
)
`

Options

Following the list of all avaiable options of useQuery hook:

| Name | Type | Description |
|---------------------|:-------------------------------|:-----------------------------------------------------------------------------|
| name | String | It should contains name string for context state granular control. |
| selector | String | It should contains key value to select from result object. |
| pick | Function or Array | It rappresent the function or the array to pick just a portion of data. |
| transform | Function | It rappresent the funcion to transform data before saving on state. |
| method | String | It should be one of "GET", "POST", "PUT", "PATCH", "DELETE". |
| headers | Object | Headers must be an object. It should contains request headers key value. |
| body | Any | Request body data |
| isDebuggerActivated | Boolean | It should be activated if you need to debug all process. |
| cacheTimeout | Number | It rappresent the timeout to remove cached data from memory in milliseconds. |

Following the list of all avaiable options of useQueryEvent hook:

| Name | Type | Description |
|---------------------|:-------------------------------|:-----------------------------------------------------------------------------|
| name | String | It should contains name string for context state granular control. |
| selector | String | It should contains key value to select from result object. |
| pick | Function or Array | It rappresent the function or the array to pick just a portion of data. |
| transform | Function | It rappresent the funcion to transform data before saving on state. |
| method | String | It should be one of "GET", "POST", "PUT", "PATCH", "DELETE". |
| headers | Object | Headers must be an object. It should contains request headers key value. |
| body | Any | Request body data |
| isDebuggerActivated | Boolean | It should be activated if you need to debug all process. |
| cacheTimeout | Number | It rappresent the timeout to remove cached data from memory in milliseconds. |

Returns

useQuery hook return an object with following keys:

| Name | Type | Description |
|-----------|:------------------------------|:-----------------------------------------------------------------------------------------|
| data | Any | Data returned from request |
| error | Error or null | Request error. |
| loading | Boolean | Request loading state. |
| mutate | Function(data) | Mutate function to manipulate data state, available everywhere inside QueryProvider. |
| refresh | Function | Data refresh function. |
| cache | Object | Cache control function: get(url), has(url), clear() |

useQueryEvent hook return an object with following keys:

| Name | Type | Description |
|-------------|:------------------------------|:-----------------------------------------------------------------------------------------|
| sendRequest | Function | Trigger function to send request |
| isSending | Boolean | State of sending status |
| data | Any | Data returned from request |
| error | Error or null | Request error. |
| loading | Boolean | Request loading state. |
| mutate | Function(data) | Mutate function to manipulate data state, available everywhere inside QueryProvider. |
| refresh | Function | Data refresh function. |
| cache | Object | Cache control function: get(url), has(url), clear() |

Usage Examples

Following usage example:

$3

main.jsx

`js
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.jsx'

import { QueryProvider } from "@aredant/use-query-manager"

ReactDOM.createRoot(document.getElementById('root')).render(


,
)
`

App.jsx

`js
import { useEffect } from 'react'
import { useQuery } from '@aredant/use-query-manager'

import InnerComponent from './InnerComponent'

const App = () => {
const { data, error, loading, mutate, refresh, cache } = useQuery("https://dummyjson.com/products", {
name: "products", // State name to select right context
selector: "products", // Selector for first level request data
method: "GET", // Request method
headers: {}, // Request headers
body: undefined, // Request body
transform: (data) => { // Transform response data
return data.filter((item) => item.id % 2 === 0);
},
pick: (key, value) => { // Pick a portion of data
if (typeof value === "string" || key === "images") return undefined;
return value;
},
cacheTimeout: 5000, // Timeout to auto-clear cache, 0 if you don't want to auto-clear cache
isDebuggerActivated: true, // -> Take a look to the inspector console
});

useEffect(() => {
console.log(data, error, loading);
}, [data, error, loading]);

return (
<>


export default App
`

InnerComponent.js

`js
import {useQueryState} from '@aredant/use-query-manager'

const InnerComponent = () => {
const [data, setData] = useQueryState(); // Get all available query data
const [products, setProducts] = useQueryState("products"); // Get just a portion of data by name

return (


        {data && JSON.stringify(data, null, 2)}
        {products && JSON.stringify(products, null, 2)}
    

export default InnerComponent;
`

$3

main.jsx

`js
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.jsx'

import { QueryProvider } from "@aredant/use-query-manager"

ReactDOM.createRoot(document.getElementById('root')).render(


,
)
`

App.jsx

`js
import { useState, useEffect } from 'react'
import { useQuery } from '@aredant/use-query-manager'

const API_URL = "https://dummyjson.com/products";

const _formatSkip = (limit, page) => {
return limit * (page - 1);
}

const App = () => {
const [page, setLimit] = useState(1);
const [limit, setPage] = useState(10);
const [url, setUrl] = useState(${API_URL}?limit=${limit}&skip=${_formatSkip(limit, page)});

const { data: products, error, loading, mutate, refresh, cache } = useQuery(url, {
name: "products", // State name to select right context
selector: "products", // Selector for first level request data
method: "GET", // Request method
headers: {}, // Request headers
body: undefined, // Request body
transform: (data) => { // Transform response data
return data.filter((item) => item.id % 2 === 0);
},
// pick: (key, value) => { // Pick a portion of data
// if (typeof value === "string" || key === "images") return undefined;
// return value;
// },
pick: ["id", "title", "description"], // Pick a portion of data using array of key name
cacheTimeout: 5000, // Timeout to auto-clear cache, 0 if you don't want to auto-clear cache
isDebuggerActivated: true, // -> Take a look to the inspector console
});

const handlePrevPage = () => {
if (page > 1) setPage((page) => page - 1);
}

const handleNextPage = () => {
if (page < Math.ceil(products.length / limit)) setPage((page) => page + 1);
}

useEffect(() => {
setUrl(${API_URL}?limit=${limit}&skip=${_formatSkip(limit, page)});
}, [page, limit]);

return (
<>


export default App
`

$3

If you want to trigger the request on event like click you can use useQueryEvent hook. Check the following example:

main.jsx

`js
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.jsx'

import { QueryProvider } from "@aredant/use-query-manager"

ReactDOM.createRoot(document.getElementById('root')).render(


,
)
`

App.jsx

`js
import { useEffect, useState } from 'react';
import { useQueryState, useQueryEvent } from './hooks';

import "./App.css";

const App = () => {
const [id, setId] = useState(1);
const [url, setUrl] = useState(https://dummyjson.com/products/${id});

const { sendRequest, isSending, data, error, loading, refresh } = useQueryEvent(url, {
name: "product",
isDebuggerActivated: true
});

useEffect(() => {
setUrl(https://dummyjson.com/products/${id});
}, [id])

return (
<>


              {
                data && JSON.stringify(data, null, 2)
              }
            

export default App
`

Of course you can use a combination of useQuery and useQueryEvent inside the same component.

$3

main.jsx

`js
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.jsx'

import { QueryProvider } from "@aredant/use-query-manager"

ReactDOM.createRoot(document.getElementById('root')).render(


,
)
`

App.jsx

`js
import { useEffect } from 'react'
import { useQuery } from '@aredant/use-query-manager'

import InnerComponent from './InnerComponent'

const App = () => {
const { data, error, loading, mutate, refresh, cache } = useQuery("https://dummyjson.com/products", {
name: "products", // State name to select right context
selector: "products", // Selector for first level request data
method: "GET", // Request method
headers: {}, // Request headers
body: undefined, // Request body
transform: (data) => { // Transform response data
return data.filter((item) => item.id % 2 === 0);
},
pick: (key, value) => { // Pick a portion of data
if (typeof value === "string" || key === "images") return undefined;
return value;
},
cacheTimeout: 5000, // Timeout to auto-clear cache, 0 if you don't want to auto-clear cache
isDebuggerActivated: true, // -> Take a look to the inspector console
});

useEffect(() => {
console.log(data, error, loading);
}, [data, error, loading]);

return (
<>


export default App
`

InnerComponent.js

`js
import { useQuerySelector } from '@aredant/use-query-manager'

const InnerComponent = () => {
const products = useQuerySelector((state) => state.products); // Get just a portion of data by name using query selector callback function

return (


        {products && JSON.stringify(products, null, 2)}
    

export default InnerComponent;
`

Global state management

From version 2.0.0 is available a fully featured global state management system.

$3

First of all you need to setup a store using createQueryStore and all dispatchers usign createDispatcher and pass them to QueryProvider as follow:

store.js

`js
import { createQueryStore } from '@aredant/use-query-manager'

export default createQueryStore({
auth: { // !IMPORTANT Must match with dispatcher name
token: null,
user: null,
}
});
`

dispatchers/authDispatcher.js

`js
import { createQueryDispatcher } from '@aredant/use-query-manager'

export default createQueryDispatcher({
name: "auth", // !IMPORTANT Must match with store key object name
actions: {
login: (state, payload) => {
state.token = payload.token;
state.user = payload.user;
},
logout: (state) => {
state.token = null;
state.user = null;
}
}
});
`

main.jsx

`js
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.jsx'

import { QueryProvider } from '@aredant/use-query-manager'

import store from './store'
import authDispatcher from './dispatchers/authDispatcher'

import './index.css'

const dispatchers = [
authDispatcher,
]

ReactDOM.createRoot(document.getElementById('root')).render(


,
)
`

Then you can use dispatcher inside any component of your app.

App.jsx

`js
import { useQueryState, useQuerySelector, useQueryDispatcher } from '@aredant/use-query-manager';

import "./App.css";

const App = () => {
const [data, setData] = useQueryState("auth");

const auth = useQuerySelector(({ auth }) => auth);
const { login, logout } = useQueryDispatcher("auth");

return (
<>


            // ====================== 

            // -------- DATA -------- 

            // ======================
            

            

            {data && JSON.stringify(data, null, 2)}
        

export default App
```