veza/apps/web/docs/MUTATIONS_OPTIMISTIC_UPDATES_AUDIT.md

# Mutations Optimistic Updates Audit

**Date**: 2026-01-11  
**Action**: 4.4.1.4 - Audit all mutations for optimistic updates  
**Status**: ✅ Complete

## Summary

This document audits all React Query mutations in the codebase to identify which mutations have optimistic updates and which are missing them.

## Methodology

- Searched for all `useMutation` calls in the codebase
- Checked each mutation for:
  - `onMutate` handler (optimistic update)
  - `createOptimisticUpdate`, `createArrayOptimisticUpdate`, `createToggleOptimisticUpdate` usage
  - Manual optimistic update logic in `onMutate`
- Categorized mutations by optimistic update status

## Mutations WITH Optimistic Updates ✅

### 1. Like/Unlike Track (`LikeButton.tsx`)
- **Mutations**: `likeMutation`, `unlikeMutation`
- **Type**: Manual `onMutate` with local state
- **Pattern**: Updates local state (`isLiked`, `likeCount`) optimistically
- **Rollback**: Manual revert in `onError`
- **Lines**: 67-96 (like), 99-120 (unlike)

### 2. Follow/Unfollow Playlist (`PlaylistFollowButton.tsx`)
- **Mutations**: `followMutation`, `unfollowMutation`
- **Type**: Manual `onMutate` with local state
- **Pattern**: Updates local state (`following`, `followerCount`) optimistically
- **Rollback**: Manual revert in `onError`
- **Lines**: 84-114 (follow), 117-145 (unfollow)

## Mutations WITHOUT Optimistic Updates ❌

### Playlist Operations (`usePlaylist.ts`)

#### 1. `useCreatePlaylist`
- **Mutation**: Create playlist
- **Current**: Only `onSuccess` invalidation
- **Recommendation**: Add optimistic update to immediately show new playlist in list

#### 2. `useUpdatePlaylist`
- **Mutation**: Update playlist
- **Current**: Only `onSuccess` invalidation
- **Recommendation**: Add optimistic update using `createOptimisticUpdate` utility

#### 3. `useDeletePlaylist`
- **Mutation**: Delete playlist
- **Current**: Only `onSuccess` invalidation
- **Recommendation**: Add optimistic update to immediately remove from list

#### 4. `useAddTrackToPlaylist`
- **Mutation**: Add track to playlist
- **Current**: Only `onSuccess` invalidation
- **Recommendation**: Add optimistic update using `createArrayOptimisticUpdate` (operation: 'add')

#### 5. `useAddCollaborator`
- **Mutation**: Add collaborator to playlist
- **Current**: Only `onSuccess` invalidation
- **Recommendation**: Add optimistic update using `createArrayOptimisticUpdate` (operation: 'add')

#### 6. `useRemoveCollaborator`
- **Mutation**: Remove collaborator from playlist
- **Current**: Only `onSuccess` invalidation
- **Recommendation**: Add optimistic update using `createArrayOptimisticUpdate` (operation: 'remove')

#### 7. `useUpdateCollaboratorPermission`
- **Mutation**: Update collaborator permission
- **Current**: Only `onSuccess` invalidation
- **Recommendation**: Add optimistic update using `createArrayOptimisticUpdate` (operation: 'update')

#### 8. `useReorderPlaylistTracks`
- **Mutation**: Reorder tracks in playlist
- **Current**: Only `onSuccess` invalidation
- **Recommendation**: Add optimistic update to immediately show new order

### Comment Operations

#### 9. `createCommentMutation` (`CommentSection.tsx`)
- **Mutation**: Create comment
- **Current**: Only `onSuccess` invalidation
- **Recommendation**: Add optimistic update using `createArrayOptimisticUpdate` (operation: 'add')

#### 10. `createReplyMutation` (`CommentThread.tsx`)
- **Mutation**: Create reply to comment
- **Current**: Only `onSuccess` invalidation
- **Recommendation**: Add optimistic update using `createArrayOptimisticUpdate` (operation: 'add')

#### 11. `updateCommentMutation` (`CommentThread.tsx`)
- **Mutation**: Update comment
- **Current**: Only `onSuccess` invalidation
- **Recommendation**: Add optimistic update using `createArrayOptimisticUpdate` (operation: 'update')

#### 12. `deleteCommentMutation` (`CommentThread.tsx`)
- **Mutation**: Delete comment
- **Current**: Only `onSuccess` invalidation
- **Recommendation**: Add optimistic update using `createArrayOptimisticUpdate` (operation: 'remove')

### Chat Operations

#### 13. `leaveRoomMutation` (`ChatSidebar.tsx`)
- **Mutation**: Leave chat room
- **Current**: Only `onSuccess` invalidation
- **Recommendation**: Add optimistic update to immediately remove from conversation list

#### 14. `deleteRoomMutation` (`ChatSidebar.tsx`)
- **Mutation**: Delete chat room
- **Current**: Only `onSuccess` invalidation
- **Recommendation**: Add optimistic update to immediately remove from conversation list

### Notification Operations

#### 15. `markAsReadMutation` (`NotificationMenu.tsx`, `NotificationsPage.tsx`)
- **Mutation**: Mark notification as read
- **Current**: Only `onSuccess` invalidation
- **Recommendation**: Add optimistic update using `createArrayOptimisticUpdate` (operation: 'update')

#### 16. `markAllAsReadMutation` (`NotificationMenu.tsx`, `NotificationsPage.tsx`)
- **Mutation**: Mark all notifications as read
- **Current**: Only `onSuccess` invalidation
- **Recommendation**: Add optimistic update to immediately update all notifications

### Share Link Operations

#### 17. `createShareMutation` (`ShareLinkManager.tsx`)
- **Mutation**: Create share link
- **Current**: Only `onSuccess` invalidation
- **Recommendation**: Add optimistic update to immediately show share link

#### 18. `revokeShareMutation` (`ShareLinkManager.tsx`)
- **Mutation**: Revoke share link
- **Current**: Only `onSuccess` invalidation
- **Recommendation**: Add optimistic update to immediately remove share link

### Auth Operations

#### 19. `useLogin` (`useLogin.ts`)
- **Mutation**: Login
- **Current**: No optimistic update (correct - auth state should not be optimistic)
- **Recommendation**: ✅ No optimistic update needed (security-sensitive)

#### 20. `useRegister` (`useRegister.ts`)
- **Mutation**: Register
- **Current**: No optimistic update (correct - auth state should not be optimistic)
- **Recommendation**: ✅ No optimistic update needed (security-sensitive)

## Statistics

- **Total Mutations Found**: 20+
- **With Optimistic Updates**: 4 (20%) - LikeButton, PlaylistFollowButton
- **With Partial Optimistic Updates**: 2 (10%) - ShareLinkManager (local state in onSuccess)
- **Without Optimistic Updates**: 14+ (70%)
- **Should Not Have Optimistic Updates**: 2 (auth operations)

## Patterns Identified

### Pattern 1: Manual Local State Optimistic Updates
- **Used in**: `LikeButton`, `PlaylistFollowButton`
- **Approach**: Update local component state in `onMutate`, revert in `onError`
- **Pros**: Simple, works for isolated component state
- **Cons**: Doesn't update React Query cache, requires manual rollback

### Pattern 2: React Query Cache Invalidation Only
- **Used in**: Most mutations
- **Approach**: Only invalidate queries on success, wait for refetch
- **Pros**: Simple, ensures data consistency
- **Cons**: No immediate feedback, requires network round-trip

### Pattern 3: Utility-Based Optimistic Updates (Available but Unused)
- **Available**: `createOptimisticUpdate`, `createArrayOptimisticUpdate`, `createToggleOptimisticUpdate`
- **Used in**: None currently
- **Approach**: Use utility functions for consistent optimistic updates
- **Pros**: Consistent pattern, automatic rollback, updates React Query cache
- **Cons**: Requires setup

## Recommendations

### High Priority (User-Facing Operations)
1. **Playlist operations** (`useCreatePlaylist`, `useUpdatePlaylist`, `useDeletePlaylist`)
2. **Track operations** (`useAddTrackToPlaylist`)
3. **Comment operations** (create, update, delete)
4. **Follow/Like operations** (already have optimistic updates ✅)

### Medium Priority (Frequent Operations)
1. **Collaborator operations** (add, remove, update)
2. **Notification operations** (mark as read)
3. **Share link operations** (create, revoke)

### Low Priority (Less Frequent)
1. **Chat operations** (leave room, delete room)
2. **Reorder operations** (reorder playlist tracks)

## Next Steps

1. ✅ **Action 4.4.1.4**: Audit complete - Documented all mutations
2. **Action 4.4.1.5**: Add optimistic updates to mutations missing them (prioritize high-priority operations)
3. **Action 4.4.1.2**: Migrate manual optimistic updates to use utility functions (LikeButton, PlaylistFollowButton)

## Files Audited

- `apps/web/src/features/playlists/hooks/usePlaylist.ts` - 9 mutations
- `apps/web/src/features/tracks/components/LikeButton.tsx` - 2 mutations (with optimistic ✅)
- `apps/web/src/features/playlists/components/PlaylistFollowButton.tsx` - 2 mutations (with optimistic ✅)
- `apps/web/src/features/tracks/components/CommentSection.tsx` - 1 mutation
- `apps/web/src/features/tracks/components/CommentThread.tsx` - 3 mutations
- `apps/web/src/features/chat/components/ChatSidebar.tsx` - 2 mutations
- `apps/web/src/components/notifications/NotificationMenu.tsx` - 2 mutations
- `apps/web/src/features/notifications/pages/NotificationsPage.tsx` - 2 mutations
- `apps/web/src/components/share/ShareLinkManager.tsx` - 2 mutations
- `apps/web/src/features/auth/hooks/useLogin.ts` - 1 mutation (no optimistic needed ✅)
- `apps/web/src/features/auth/hooks/useRegister.ts` - 1 mutation (no optimistic needed ✅)