This is a complementary library that should be used with @tanstack/react-query for API REQUESTS and more
We have been working on a project using ReactJS and React-Native and we were happy with the React-Query package, now known as Tanstack-Query, which had made our lives easier by managing most of the state management features needed for enterprise software development. This had helped us focus on building functionalities easily without worrying about server state management.
However, we still faced some challenges. For each project, we have to configure how Tanstack-Query would connect to the Backend API and manage GET, POST, PUT, and PATCH requests efficiently. One of the major challenges was handling dynamic queryKeys in Tanstack-Query. For example, when building a screen with pagination, useQuery will have re-call the queryFunction every time the key changed, which will load the current page data. This meant that the queryKey changed dynamically, and sometimes we needed to use the queryKey of the current page to perform certain tasks like updating a specific row in the view. This was always tedious.
But we were not discouraged. So, we set out to find a solution which led to the development of this package. This package would handle dynamic queryKeys in Tanstack-Query and solve other related problems. It made configuring Tanstack-Query to connect to the Backend API and managing GET, POST, PUT, and PATCH requests a breeze. It also solved the problem of dynamic queryKeys, making it much easier to update specific rows in the view.
Please note that this package is still being developed and may not function as expected. We are working to refine its implementation structure to meet a functional standard. The documentation may not align with the current implementation, so if you encounter any difficulties while setting up the package, please raise an issue in the GitHub repository. We appreciate your patience and understanding as we work to improve this package.
- [âś…] Global settings for requests
- [âś…] Requests context implementations
- [âś…] Post, Get, Patch Requests
- [âś…] Query key tracker to track dynamic query and help fetch query cache from any page
- [âś…] Persistent queries implementation (Not completed)
- [❌] Put request
- [❌] Generic return type (this is currently an issue if the API does not return object with the necessary properties required by the library)
- [❌] Generic Pagination for any response without infinite queries
- [❌] Infinite Get Query implementation (still using implementation meant for our use case)
- [❌] Server sent events
- [❌] Socket implementations
- [❌] Tests
You must install @tanstack/react-query and axios first to use this package
yarn add @tanstack/react-query axios
After that install this package
$ npm install @ventlio/tanstack-query
OR
$ yarn add @ventlio/tanstack-query
Currently the library return type expects data structure of the below schema, so depending on the API design, you can reach out to the developer to implement the return type that follows the below schema.
export interface IRequestError {
statusCode: number;
message: string;
timeStamp: Date;
status: boolean;
data?: any;
}
export interface IRequestSuccess<T> {
statusCode: number;
message: string;
timeStamp: Date;
status: boolean;
data: T;
}
Follow the below instructions to have the package running on your project
# For ReactJS
REACT_APP_API_URL='https://api.example.com'
REACT_APP_API_TIMEOUT=300000
# For NextJS
NEXT_PUBLIC_API_URL='https://api.example.com'
NEXT_PUBLIC_API_TIMEOUT=300000
import { QueryClient } from '@tanstack/react-query';
import { TanstackQueryConfig, bootstrapQueryRequest } from '@ventlio/tanstack-query';
// Global queryClient
const queryClient = new QueryClient();
// do this before adding the queryClient to QueryClientProvider
bootstrapQueryRequest(queryClient);
// recommended setup for mobile apps as the .env setup won't work
bootstrapQueryRequest(queryClient, {
context: 'app', // this is required to make the library switch to app context where necessary
environments: {
appBaseUrl: baseUrl,
appTimeout: 30000,
},
modelConfig: {
idColumn: 'id', // used for useQueryModel to uniquely identify query data in a collection/array instance
},
});
You can now use it in a QueryClientProvider
import { QueryClientProvider } from '@tanstack/react-query';
import { queryClient } from './queryClient';
function App() {
return (
<QueryClientProvider client={queryClient}>
<HomePage />
<About />
</QueryClientProvider>
);
}
Updating the configurations inside a component
import { useQueryBaseURL, useQueryHeaders, useQueryTimeout } from '@ventlio/tanstack-query';
function LoginPage() {
const { headers, setQueryHeaders } = useQueryHeaders();
const [authToken, setAuthToken] = useState();
useEffect(() => {
// after user has logged in successfully set the authorization header token
// this should also be done mostly in the layout that contains the authenticated views of the app
// for instance in AuthLayout, so that after login in the authToken can still be used to authenticate future request
// when user refreshes the page
setQueryHeaders({ Authorization: `Bearer ${authToken}` });
}, []);
return <>{/** codes */}</>;
}
The useGetRequest
hook is a custom React Query hook that handles GET requests. It returns an object that contains the current state of the query, as well as several methods to update the query.
The useGetRequest
hook takes an object as its parameter with the following properties:
path
: a string representing the URL path for the GET request. Required.load
: a boolean indicating whether to load the query immediately. Default:false
.queryOptions
: an object containing additional options for the query. Optional.keyTracker
: a string that tracks changes to the query key. Optional.
The useGetRequest
hook returns an object with the following properties:
data
: the data returned by the query, if successful.isLoading
: a boolean indicating whether the query is currently loading.isError
: a boolean indicating whether the query resulted in an error.error
: the error message, if an error occurred.updatePath
: a function that updates the path of the query.nextPage
: a function that navigates to the next page of results, if pagination is present.prevPage
: a function that navigates to the previous page of results, if pagination is present.get
: a function that updates the path and options of the query and returns the data.gotoPage
: a function that navigates to a specific page of results, if pagination is present.page
: the current page number, if pagination is present.queryKey
: an array representing the query key.
import { useGetRequest } from '@ventlio/tanstack-query';
const MyComponent = () => {
const { data, isLoading, isError, error, updatePath, nextPage, prevPage, get, gotoPage, page, queryKey } =
useGetRequest({
path: '/api/mydata',
load: true,
queryOptions: {
staleTime: 10000,
refetchOnWindowFocus: false,
},
keyTracker: 'mydata',
});
return (
<div>
{isLoading && <p>Loading...</p>}
{isError && <p>{error.message}</p>}
{data && (
<ul>
{data.map((item) => (
<li key={item.id}>{item.name}</li>
))}
</ul>
)}
<button onClick={() => nextPage()}>Next Page</button>
<button onClick={() => prevPage()}>Previous Page</button>
<button onClick={() => gotoPage(1)}>Go to Page 1</button>
<button onClick={() => get('/api/mydata?page=2')}>Get Page 2</button>
</div>
);
};
The usePostRequest
function is a custom React hook that provides an easy way to make POST requests using the @tanstack/react-query
library.
To use the usePostRequest
hook, import it from the module where it's defined and call it in your component like this:
import { usePostRequest } from '@ventlio/tanstack-query';
const MyComponent = () => {
const { post, isLoading, isError, isSuccess, data, error } = usePostRequest({
path: '/api/posts',
isFormData: true,
});
const handleFormSubmit = async (formData) => {
try {
const response = await post(formData);
console.log(response);
} catch (e) {
console.error(e);
}
};
return (
<form onSubmit={handleFormSubmit}>
{/* form inputs */}
<button type="submit">Submit</button>
</form>
);
};
The usePostRequest
hook takes an object with two optional properties:
path
(required): the URL path to make the POST request to.isFormData
(optional, default isfalse
): a boolean that indicates whether to send the request data as form data.
The usePostRequest
hook returns an object with the following properties:
post
: a function that takes the data to be sent in the request and an optionalMutateOptions
object, and returns a promise that resolves to the response data.isLoading
: a boolean that indicates whether the request is currently loading.isError
: a boolean that indicates whether the request resulted in an error.isSuccess
: a boolean that indicates whether the request was successful.data
: the response data, if the request was successful.error
: the error object, if the request resulted in an error.
The usePostRequest
hook internally uses the useMutation
hook from the @tanstack/react-query
library to register a mutation that sends the POST request. It also uses the internal makeRequest
function to actually make the request.
It users the useQueryConfig
hook internally to get the headers
, baseURL
, and timeout
values that are passed to makeRequest
.
If the request is successful, the hook scrolls the page to the top using the window.scrollTo
method. If the request fails, it also scrolls to the top before throwing the error.
usePatchRequest
is a React hook that allows you to make PATCH requests. It takes in a path
parameter that specifies the path of the API endpoint to call.
usePatchRequest<TResponse>({ path: string }): { patch, ...mutation }
path
(required): A string that represents the path of the API endpoint to call.
usePatchRequest
returns an object with the following properties:
patch
: A function that can be called to initiate a PATCH request....mutation
: The rest of the properties returned by theuseMutation
hook.
import { usePatchRequest } from '@ventlio/tanstack-query';
function App() {
const { patch, isLoading, isError, isSuccess, data } =
usePatchRequest <
User >
{
path: '/users/1',
};
const updateUser = async (user: User) => {
await patch(user);
};
return (
<div>
<button onClick={() => updateUser({ name: 'John' })}>Update User</button>
{isLoading && <div>Loading...</div>}
{isError && <div>Error updating user</div>}
{isSuccess && <div>Successfully updated user {data?.name}</div>}
</div>
);
}
In this example, we are using the usePatchRequest
hook to send a PATCH request to update a user's name. We call the patch
function with the new user data to initiate the request. The isLoading
, isError
, isSuccess
, and data
properties are used to display the request status and response data.
Note that we have assumed the existence of a User
interface in this example.
The useDeleteRequest
hook is a custom hook used to make HTTP DELETE requests using @tanstack/react-query
library. This hook returns an object that contains a destroy
function and other properties inherited from the useQuery
hook.
This hook does not take any parameter.
The hook returns an object containing:
destroy
: a function used to make the DELETE request and returns the server's response.- Other properties inherited from the
useQuery
hook.
Here's an example of how to use the useDeleteRequest
hook:
import { useDeleteRequest } from '@ventlio/tanstack-query';
function DeleteButton({ link }) {
const { isLoading, isError, error, data, destroy } = useDeleteRequest();
const handleDelete = async () => {
const response = await destroy(link);
// do something with the response
};
return (
<button onClick={handleDelete} disabled={isLoading}>
{isLoading ? 'Deleting...' : 'Delete'}
</button>
);
}
In the above example, we created a DeleteButton
component that uses the useDeleteRequest
hook to make a DELETE request to the specified link
when the button is clicked. The destroy
function returns the server's response, which we can then use to update the UI.
A simple utility function that utilizes useQueryClient
hook from @tanstack/react-query
to refetch a query and retrieve updated data.
- Import
useRefetchQuery
from your desired file:
import { useRefetchQuery } from '@ventlio/tanstack-query';
- Call
useRefetchQuery
with aqueryKey
parameter which is an array of any types that uniquely identifies the query:
const { refetchQuery } = useRefetchQuery(['myQueryKey']);
- Invoke
refetchQuery
function to refetch the query and retrieve updated data:
const { data } = await refetchQuery<MyDataType>();
If you want to refetch a different query, you can pass a different queryKey
parameter to refetchQuery
function:
const { data } = (await refetchQuery) < MyDataType > ['myOtherQueryKey'];
If you want to perform additional operations after refetching the query, you can use the data
returned by refetchQuery
function:
const { data } = await refetchQuery<MyDataType>();
// Perform additional operations with data
queryKey
: An array of any types that uniquely identifies the query.
refetchQuery
: A function that refetches the query and retrieves updated data.
import { useQueryClient } from '@tanstack/react-query';
import { useRefetchQuery } from '@ventlio/tanstack-query';
const MyComponent = () => {
const queryClient = useQueryClient();
const { refetchQuery } = useRefetchQuery(['myQueryKey']);
const handleClick = async () => {
try {
// Refetch the query and retrieve updated data
const { data } = await refetchQuery<MyDataType>();
// Perform additional operations with data
console.log(data);
} catch (error) {
// Handle error
console.error(error);
}
};
return (
<button onClick={handleClick}>
Refetch Query
</button>
);
};
A custom hook that utilizes useQueryClient
hook from @tanstack/react-query
and useState
hook from react
to track a query key and retrieve query data.
- Import
useKeyTrackerModel
from @ventlio/tanstack-query:
import { useKeyTrackerModel } from '@ventlio/tanstack-query';
- Call
useKeyTrackerModel
with akeyTracker
parameter which is a string that uniquely identifies the query key:
const { refetchQuery, getQueryKey, queryKey, data } = useKeyTrackerModel < MyDataType > 'myKeyTracker';
- Invoke
getQueryKey
function to retrieve the query key:
const key = getQueryKey();
- Invoke
refetchQuery
function to retrieve query data:
const queryData = refetchQuery();
- Use
queryKey
anddata
as needed in your component:
return (
<div>
<p>Query Key: {queryKey}</p>
<p>Query Data: {data}</p>
</div>
);
keyTracker
: A string that uniquely identifies the query key.
refetchQuery
: A function that retrieves query data.getQueryKey
: A function that retrieves the query key.queryKey
: The query key.data
: The query data.
import { useQueryClient } from '@tanstack/react-query';
import { useState } from 'react';
import { useKeyTrackerModel } from '@ventlio/tanstack-query';
const MyComponent = () => {
const queryClient = useQueryClient();
const { refetchQuery, getQueryKey, queryKey, data } = useKeyTrackerModel < MyDataType > 'myKeyTracker';
const handleClick = async () => {
// Retrieve the query key
const key = getQueryKey();
// Retrieve query data
const queryData = refetchQuery();
// Perform additional operations with query key and data
console.log(key, queryData);
};
return (
<div>
<button onClick={handleClick}>Get Query Data</button>
<p>Query Key: {queryKey}</p>
<p>Query Data: {data}</p>
</div>
);
};
Contributions to this codebase are welcome. If you find any issues or have any suggestions, please feel free to create an issue or pull request.
This project is licensed under the MIT License - see the LICENSE file for details.