Cursor rule

1---
2description: Guidelines for Query Hooks
3globs: **/hooks/query/**/*.ts, **/_hooks/query/**/*.ts
4alwaysApply: false
5---
6# Guidelines for Query Hooks
7 
8## Purpose and Overview
9Query hooks abstract data fetching operations using TanStack Query to provide optimized caching, loading states, error handling, and refetching strategies. They connect UI components to the data access layer, making components cleaner and more focused on presentation rather than data fetching logic.
10 
11## Structure and Organization
12 
13### Query Hooks Module Structure
14```
15src/
16├── hooks/                  # Shared hooks module
17│   └── query/              # Shared query hooks
18│       └── [entity]/
19│           ├── use-[entity]-query.ts                    # Read single entity
20│           ├── use-search-[entity]s-query.ts            # Search with regular pagination
21│           └── use-search-[entity]s-infinite-query.ts   # Search with infinite scroll
22└── features/
23    └── [feature-name]/
24        └── _hooks/         # Feature-specific hooks
25            └── query/      # Feature-specific query hooks
26                └── [entity]/
27                    ├── use-[entity]-query.ts
28                    ├── use-search-[entity]s-query.ts
29                    └── use-search-[entity]s-infinite-query.ts
30```
31 
32## Naming Conventions
33 
34### Files
35- `use-[entity]-query.ts`: For querying a single entity by ID
36- `use-search-[entity]s-query.ts`: For searching entities with regular pagination
37- `use-search-[entity]s-infinite-query.ts`: For searching entities with infinite scroll
38 
39### Functions
40- `use[Entity]Query`: For querying a single entity
41- `useSearch[Entity]sQuery`: For searching entities with regular pagination
42- `useSearch[Entity]sInfiniteQuery`: For searching entities with infinite scroll
43 
44### Types
45- `Use[Entity]QueryArgs`: Arguments for single entity query
46- `UseSearch[Entity]sQueryArgs`: Arguments for regular search query
47- `UseSearch[Entity]sInfiniteQueryArgs`: Arguments for infinite search query
48 
49## Implementation Guidelines
50 
51### Query Hooks
52- Use TanStack Query's `useQuery` hook for regular queries
53- Use `useInfiniteQuery` for paginated/infinite scroll queries
54- Import data fetching functions directly from `@/data`
55- Define appropriate query keys for proper caching
56- Structure the hook to handle loading, success, and error states
57- Use TypeScript's `UseQueryOptions` or `Omit<UseQueryOptions, 'queryKey' | 'queryFn'>` for args type
58- Spread additional args to allow overriding default options
59 
60### Query Key Structure
61- Use descriptive and hierarchical query keys
62- Follow REST-like patterns: `['/[entity]', ...params]`
63- Include relevant parameters in query keys for proper cache invalidation
64- Examples:
65  - Single entity: `['/[entity]', entityId]`
66  - Multiple entities: `['/[entity]s']`
67  - Search: `['/[entity]s', '/search', searchParams]`
68 
69## CRUD Query Examples
70 
71### 1. Single Entity Query (Read)
72```typescript
73// use-[entity]-query.ts
74import { useQuery } from '@tanstack/react-query';
75import { get[Entity]sBy[Entity]Id, type Get[Entity]sBy[Entity]IdData } from '@/data';
76 
77export type Use[Entity]QueryArgs = Get[Entity]sBy[Entity]IdData;
78 
79export function use[Entity]Query(args: Use[Entity]QueryArgs) {
80  return useQuery({
81    queryKey: ['/[entity]s', args.[entity]Id],
82    queryFn: () => get[Entity]sBy[Entity]Id(args),
83  });
84}
85```
86 
87### 2. Search Query with Regular Pagination (Read Multiple)
88```typescript
89// use-search-[entity]s-query.ts
90import { useQuery, type UseQueryOptions } from '@tanstack/react-query';
91import { type ApiError, search[Entity]s, type Search[Entity]sData, type Search[Entity]sResponse } from '@/data';
92 
93export type UseSearch[Entity]sQueryArgs = Omit<
94  UseQueryOptions<Search[Entity]sResponse, ApiError>,
95  'queryKey' | 'queryFn'
96> & {
97  payload: Search[Entity]sData;
98};
99 
100export function useSearch[Entity]sQuery({ payload,  ...args }: UseSearch[Entity]sQueryArgs) {
101  return useQuery({
102    ...args,
103    queryKey: ['/[entity]s', '/search', payload],
104    queryFn: () => search[Entity]s(payload),
105  });
106}
107```
108 
109### 3. Search Query with Infinite Scroll (Read Multiple)
110```typescript
111// use-search-[entity]s-infinite-query.ts
112import { useInfiniteQuery } from '@tanstack/react-query';
113import { search[Entity]s, type Search[Entity]sData } from '@/data';
114 
115export type UseSearch[Entity]sInfiniteQueryArgs = Search[Entity]sData;
116 
117export function useSearch[Entity]sInfiniteQuery(args?: UseSearch[Entity]sInfiniteQueryArgs) {
118  return useInfiniteQuery({
119    queryKey: ['/[entity]s', '/search', args],
120    queryFn: ({ pageParam }) => search[Entity]s({ ...args, page: pageParam }),
121    initialPageParam: 1,
122    getNextPageParam: lastPage => lastPage.next_page,
123    getPreviousPageParam: firstPage => firstPage.previous_page,
124  });
125}
126```
127 
128### Complete CRUD Query Folder Structure Example
129```
130src/hooks/query/[entity]/
131├── use-[entity]-query.ts                    # Read single entity
132├── use-search-[entity]s-query.ts            # Search with regular pagination
133└── use-search-[entity]s-infinite-query.ts   # Search with infinite scroll
134```
135 
136## Best Practices
137 
138### Performance Considerations
139- Implement appropriate staleTime and cacheTime based on data volatility
140- Use suspense mode when applicable for concurrent rendering
141- Consider implementing placeholderData or initialData for better UX
142 
143### Error Handling
144- Implement appropriate error handling strategies
145- Consider using onError callbacks for specific error handling logic
146- Document possible error scenarios
147 
148### Dependent Queries
149- Use the enabled option to control when a query should run
150- Chain queries using the data from one query as input for another
151 
152### Prefetching
153- Implement prefetching strategies for predictable user interactions
154- Use queryClient.prefetchQuery for anticipated data needs
155 
156### Infinite Queries
157- Use useInfiniteQuery for pagination or infinite scrolling scenarios
158- Structure the response data to include necessary pagination metadata