Cursor rule

1---
2description: Guidelines for Mutation Hooks
3globs: **/hooks/query/**/*.ts, **/_hooks/query/**/*.ts
4alwaysApply: false
5---
6# Guidelines for Mutation Hooks
7 
8## Purpose and Overview
9Mutation hooks abstract data modification operations (create, update, delete) using TanStack Query's useMutation hook. They provide loading states, error handling, and optimistic updates. These hooks connect UI components to the data access layer for write operations, keeping components focused on presentation rather than data manipulation logic.
10 
11## Structure and Organization
12 
13### Mutation Hooks Module Structure
14```
15src/
16├── hooks/                      # Shared hooks module
17│   └── query/                  # Shared query hooks (includes mutations)
18│       └── [entity]/
19│           ├── use-create-[entity]-mutation.ts        # Create operation
20│           ├── use-update-[entity]-mutation.ts        # Update operation
21│           ├── use-delete-[entity]-mutation.ts        # Delete operation
22│           └── use-[specific-action]-[entity]-mutation.ts  # Other specific mutations
23└── features/
24    └── [feature-name]/
25        └── _hooks/             # Feature-specific hooks
26            └── query/          # Feature-specific query hooks (includes mutations)
27                └── [entity]/
28                    ├── use-create-[entity]-mutation.ts
29                    ├── use-update-[entity]-mutation.ts
30                    └── use-delete-[entity]-mutation.ts
31```
32 
33## Naming Conventions
34 
35### Files
36- `use-create-[entity]-mutation.ts`: For create operations
37- `use-update-[entity]-mutation.ts`: For update operations
38- `use-delete-[entity]-mutation.ts`: For delete operations
39- `use-[specific-action]-[entity]-mutation.ts`: For other specific actions (e.g., `use-set-active-[entity]-mutation.ts`)
40 
41### Functions
42- `useCreate[Entity]Mutation`: For create operations
43- `useUpdate[Entity]Mutation`: For update operations
44- `useDelete[Entity]Mutation`: For delete operations
45- `use[SpecificAction][Entity]Mutation`: For other specific actions
46 
47### Types
48- `UseCreate[Entity]MutationArgs`: Arguments for create mutation hook
49- `UseUpdate[Entity]MutationArgs`: Arguments for update mutation hook
50- `UseDelete[Entity]MutationArgs`: Arguments for delete mutation hook
51- `Use[SpecificAction][Entity]MutationArgs`: Arguments for specific action mutation hook
52 
53## Implementation Guidelines
54 
55### Mutation Hooks
56- Use TanStack Query's `useMutation` hook
57- Import mutation functions directly from `@/data`
58- Use TypeScript's `MutationOptions` type for args
59- Spread args at the beginning to allow overriding any option
60- Always get `queryClient` using `useQueryClient()`
61- Handle cache invalidation in `onSuccess`
62- Handle errors in `onError` with optional error alerting utility
63- Call the provided callback after internal logic
64 
65## CRUD Mutation Examples
66 
67### 1. Create Mutation
68```typescript
69// use-create-[entity]-mutation.ts
70import { type MutationOptions, useMutation, useQueryClient } from '@tanstack/react-query';
71import { post[Entity]s, type Post[Entity]sData, type Post[Entity]sResponse } from '@/data';
72import { alertApiError } from '@/utils/api-errors';
73 
74export type UseCreate[Entity]MutationArgs = MutationOptions<
75  Post[Entity]sResponse,
76  Error,
77  Post[Entity]sData
78>;
79 
80export function useCreate[Entity]Mutation(args: UseCreate[Entity]MutationArgs = {}) {
81  const queryClient = useQueryClient();
82 
83  return useMutation({
84    ...args,
85    mutationFn: post[Entity]s,
86    onSuccess: async (data, variables, context) => {
87      await queryClient.invalidateQueries({ queryKey: ['/[entity]s'] });
88      args.onSuccess?.(data, variables, context);
89    },
90    onError: (error, variables, context) => {
91      if (args?.onError) return args.onError(error, variables, context);
92      alertApiError(error);
93    },
94  });
95}
96```
97 
98### 2. Update Mutation
99```typescript
100// use-update-[entity]-mutation.ts
101import { type MutationOptions, useMutation, useQueryClient } from '@tanstack/react-query';
102import {
103  put[Entity]sBy[Entity]Id,
104  type Put[Entity]sBy[Entity]IdData,
105  type Put[Entity]sBy[Entity]IdResponse,
106} from '@/data';
107import { alertApiError } from '@/utils/api-errors';
108 
109export type UseUpdate[Entity]MutationArgs = MutationOptions<
110  Put[Entity]sBy[Entity]IdResponse,
111  Error,
112  Put[Entity]sBy[Entity]IdData
113>;
114 
115export function useUpdate[Entity]Mutation(args: UseUpdate[Entity]MutationArgs = {}) {
116  const queryClient = useQueryClient();
117 
118  return useMutation({
119    ...args,
120    mutationFn: put[Entity]sBy[Entity]Id,
121    onSuccess: async (data, variables, context) => {
122      await queryClient.invalidateQueries({ queryKey: ['/[entity]s'] });
123      args.onSuccess?.(data, variables, context);
124    },
125    onError: (error, variables, context) => {
126      if (args?.onError) return args.onError(error, variables, context);
127      alertApiError(error);
128    },
129  });
130}
131```
132 
133### 3. Delete Mutation
134```typescript
135// use-delete-[entity]-mutation.ts
136import { type MutationOptions, useMutation, useQueryClient } from '@tanstack/react-query';
137import {
138  delete[Entity]sBy[Entity]Id,
139  type Delete[Entity]sBy[Entity]IdData,
140  type Delete[Entity]sBy[Entity]IdResponse,
141} from '@/data';
142import { alertApiError } from '@/utils/api-errors';
143 
144export type UseDelete[Entity]MutationArgs = MutationOptions<
145  Delete[Entity]sBy[Entity]IdResponse,
146  Error,
147  Delete[Entity]sBy[Entity]IdData
148>;
149 
150export function useDelete[Entity]Mutation(args: UseDelete[Entity]MutationArgs = {}) {
151  const queryClient = useQueryClient();
152 
153  return useMutation({
154    ...args,
155    mutationFn: delete[Entity]sBy[Entity]Id,
156    onSuccess: async (data, variables, context) => {
157      await queryClient.invalidateQueries({ queryKey: ['/[entity]s'] });
158      args.onSuccess?.(data, variables, context);
159    },
160    onError: (error, variables, context) => {
161      if (args?.onError) return args.onError(error, variables, context);
162      alertApiError(error);
163    },
164  });
165}
166```
167 
168### Complete CRUD Mutation Folder Structure Example
169```
170src/hooks/query/[entity]/
171├── use-create-[entity]-mutation.ts    # Create
172├── use-update-[entity]-mutation.ts    # Update
173└── use-delete-[entity]-mutation.ts    # Delete
174```
175 
176## Best Practices
177 
178### Cache Invalidation
179- Implement appropriate cache invalidation in onSuccess
180- Consider which queries need to be invalidated after a mutation
181- Use queryClient.invalidateQueries for cache invalidation
182 
183### Error Handling
184- Implement appropriate error handling strategies
185- Forward errors to the consuming components
186- Consider global error handling for common error scenarios
187 
188### Side Effects
189- Keep side effects (like showing toast notifications) in the component using the mutation
190- Use the onSuccess and onError callbacks for side effects
191 
192### Mutation States
193- Expose and use mutation states (isLoading, isError, isSuccess) in UI components
194- Handle different states appropriately in the UI