A React Query utility package for efficient data fetching and caching
npm install query-harborbash
Install required dependencies
npm install @tanstack/react-query react-cookie axios
`
Hooks Overview
$3
A custom hook for making standard API requests with built-in caching and state management.
#### Features
- Automatic authentication header handling
- Configurable cache and stale times
- Built-in error handling
- Query invalidation support
#### Basic Usage
`javascript
const {
queryData,
isLoading,
isError,
error,
refetchQuery
} = useGlobalQuery({
url: '/api/users',
queryKey: ['users'],
methodType: 'GET'
});
`
$3
A custom hook for handling data mutations (create, update, delete operations) with support for FormData.
#### Features
- FormData support with nested object handling
- Automatic query invalidation after successful mutation
- Priority data support
- Built-in error handling
#### Basic Usage
`javascript
const {
runMutation,
mutationLoading,
mutationData,
mutationError,
isMutationSucceeded
} = useGlobalMutation({
url: '/api/users',
queriesToInvalidate: ['users'],
methodType: 'POST',
data: userData
});
`
#### FormData Upload Examples
##### Basic FormData Upload
`javascript
const {
runMutation,
mutationLoading
} = useGlobalMutation({
url: '/api/upload',
queriesToInvalidate: ['files'],
methodType: 'POST',
isFormData: true,
data: {
file: fileObject,
title: 'My Document'
}
});
`
##### Complex FormData with Arrays
`javascript
// Without excludedIndexKeys
const data = {
files: [file1, file2],
metadata: {
titles: ['Doc 1', 'Doc 2']
}
};
// This will generate FormData with structure:
// files[0] = file1
// files[1] = file2
// metadata[titles][0] = Doc 1
// metadata[titles][1] = Doc 2
`
##### Using excludedIndexKeys
`javascript
const MultipleFileUpload = () => {
const {
runMutation,
mutationLoading
} = useGlobalMutation({
url: '/api/upload-multiple',
queriesToInvalidate: ['files'],
methodType: 'POST',
isFormData: true,
// Specify which keys should not include array indices
excludedIndexKeys: ['files', 'documents'],
data: {
files: [file1, file2, file3],
documents: [docFile1, docFile2],
metadata: {
titles: ['Doc 1', 'Doc 2', 'Doc 3'],
categories: ['Cat 1', 'Cat 2', 'Cat 3']
}
}
});
return (
);
};
`
The above example will generate FormData with the following structure:
`plaintext
// Keys with excludedIndexKeys:
files = file1
files = file2
files = file3
documents = docFile1
documents = docFile2
// Regular array keys (maintain indices):
metadata[titles][0] = Doc 1
metadata[titles][1] = Doc 2
metadata[titles][2] = Doc 3
metadata[categories][0] = Cat 1
metadata[categories][1] = Cat 2
metadata[categories][2] = Cat 3
`
##### Real-World Example: Multiple File Upload with Metadata
`javascript
const DocumentUploadForm = () => {
const [files, setFiles] = useState([]);
const [metadata, setMetadata] = useState({
department: 'HR',
tags: ['confidential', 'employee'],
});
const {
runMutation,
mutationLoading,
isMutationSucceeded
} = useGlobalMutation({
url: '/api/documents/upload',
queriesToInvalidate: ['documents'],
methodType: 'POST',
isFormData: true,
excludedIndexKeys: ['files'], // files will be sent without indices
data: {
files: files,
metadata: metadata,
timestamp: new Date().toISOString(),
user: {
id: currentUserId,
role: userRole
}
}
});
const handleFileChange = (e) => {
setFiles(Array.from(e.target.files));
};
const handleUpload = () => {
runMutation();
};
return (
type="file"
multiple
onChange={handleFileChange}
/>
{mutationLoading ? (
Uploading...
) : (
)}
{isMutationSucceeded && (
Upload completed successfully!
)}
);
};
`
This will generate FormData where:
- Multiple files are sent with the same key name ('files')
- Metadata is properly nested with array indices preserved
- Additional data is structured appropriately
The resulting FormData structure will be:
`plaintext
files = File1
files = File2
metadata[department] = HR
metadata[tags][0] = confidential
metadata[tags][1] = employee
timestamp = 2024-02-23T10:00:00.000Z
user[id] = 123
user[role] = admin
`
#### When to Use excludedIndexKeys
Use excludedIndexKeys when:
1. Working with file upload APIs that expect multiple files with the same key
2. Dealing with legacy APIs that don't support indexed form fields
3. Implementing multi-file upload where the server expects a flat structure
4. Handling file arrays where order doesn't matter
$3
A custom hook for handling infinite scroll or pagination scenarios.
#### Features
- Automatic pagination handling
- Built-in cache management
- Total count tracking
- Next page detection
#### Basic Usage
`javascript
const {
queryData,
isLoading,
isError,
error,
fetchNextPage,
hasNextPage,
totalCount
} = useGlobalInfiniteQuery({
url: '/api/posts',
queryKey: ['posts'],
methodType: 'GET',
data: { limit: 10 }
});
`
$3
A utility hook for managing cookies across the application.
#### Features
- Simple cookie management
- Type-safe cookie operations
- Easy integration with authentication
#### Basic Usage
`javascript
const { cookie, setCookie, removeCookie } = useCookie({
cookieName: 'accessToken'
});
``