diff --git a/EXHAUSTIVE_TODO_LIST.md b/EXHAUSTIVE_TODO_LIST.md index a4775c3e7..d9cfc91fb 100644 --- a/EXHAUSTIVE_TODO_LIST.md +++ b/EXHAUSTIVE_TODO_LIST.md @@ -893,12 +893,13 @@ Critical path dependencies: ### Sub-Epic 4.1: Migrate Domain Data to React Query 🟡 #### Task 4.1.1: Remove User from Zustand Auth Store -- [ ] **Action 4.1.1.1**: Create React Query hook for user +- [x] **Action 4.1.1.1**: Create React Query hook for user - **Scope**: `apps/web/src/features/auth/hooks/useUser.ts` (create) - `useQuery(['user', 'me'], getMe)` - - **Dependencies**: None + - **Dependencies**: None ✅ - **Risk**: LOW - - **Validation**: Hook returns user data + - **Validation**: Hook returns user data ✅ - **Rollback**: Delete hook + - **Status**: ✅ Complete - Created useUser hook with React Query, enabled only when authenticated, with proper caching - [ ] **Action 4.1.1.2**: Update authStore to remove user, keep only isAuthenticated - **Scope**: `apps/web/src/features/auth/store/authStore.ts` - Remove `user` field, keep boolean @@ -998,12 +999,13 @@ Critical path dependencies: ### Sub-Epic 4.3: Simplify Auth State 🟢 #### Task 4.3.1: Remove Complex Deduplication Logic -- [ ] **Action 4.3.1.1**: Create useUser hook using React Query +- [x] **Action 4.3.1.1**: Create useUser hook using React Query - **Scope**: `apps/web/src/features/auth/hooks/useUser.ts` - Use `useQuery(['user', 'me'], getMe)` - - **Dependencies**: Action 4.1.1.1 complete + - **Dependencies**: Action 4.1.1.1 complete ✅ - **Risk**: LOW - - **Validation**: Hook uses React Query, has built-in deduplication + - **Validation**: Hook uses React Query, has built-in deduplication ✅ - **Rollback**: Delete hook + - **Status**: ✅ Complete - Same as Action 4.1.1.1, hook already created - [ ] **Action 4.3.1.2**: Simplify refreshUser using React Query - **Scope**: `apps/web/src/features/auth/store/authStore.ts:142-218` - Remove manual deduplication, use React Query hook diff --git a/apps/web/docs/OPTIMISTIC_STORE_UPDATES_AUDIT.md b/apps/web/docs/OPTIMISTIC_STORE_UPDATES_AUDIT.md new file mode 100644 index 000000000..baa507e1e --- /dev/null +++ b/apps/web/docs/OPTIMISTIC_STORE_UPDATES_AUDIT.md @@ -0,0 +1,113 @@ +# Optimistic Store Updates Audit + +**Date**: 2026-01-11 +**Action**: 4.4.1.1 - Audit custom optimistic updates +**Status**: ✅ Complete + +## Summary + +This document audits the custom optimistic update utilities in `apps/web/src/utils/optimisticStoreUpdates.ts` and documents all optimistic update patterns found in the codebase. + +## File: `apps/web/src/utils/optimisticStoreUpdates.ts` + +### Purpose +Provides utilities for implementing optimistic updates in Zustand stores with automatic rollback on error. This is a custom implementation before migrating to React Query's built-in optimistic updates. + +### Functions Provided + +#### 1. `createOptimisticStoreUpdate` +- **Purpose**: Creates an optimistic update for a Zustand store +- **Returns**: `OptimisticUpdateResult` with `previousState`, `rollback()`, and `applyResponse()` functions +- **Features**: + - Snapshots current state before update + - Applies optimistic update immediately + - Provides rollback function (custom or default) + - Provides applyResponse function (optional) +- **Lines**: 48-116 + +#### 2. `withOptimisticUpdate` +- **Purpose**: Higher-order function that wraps an async action to add optimistic update support +- **Returns**: Wrapped async function with optimistic update logic +- **Features**: + - Applies optimistic update before API call + - Applies server response on success (optional) + - Rolls back on error (custom or default) + - Logs rollback events +- **Lines**: 124-181 + +#### 3. `withOptimisticArrayUpdate` +- **Purpose**: Helper for array operations (add, remove, update) with optimistic updates +- **Returns**: Wrapped async function with optimistic array update logic +- **Features**: + - Supports 'add', 'remove', 'update' operations + - Handles array state updates optimistically + - Rolls back entire state on error + - Logs rollback events +- **Lines**: 218-286 + +### Interfaces + +#### `OptimisticStoreUpdateOptions` +- `getState: () => TState` +- `setState: (updater) => void` +- `optimisticUpdate: (state, variables) => Partial | TState` +- `rollback?: (state, variables, error?) => Partial | TState` +- `applyResponse?: (state, variables, response) => Partial | TState` + +#### `OptimisticUpdateResult` +- `previousState: TState` +- `rollback: () => void` +- `applyResponse: (response: unknown) => void` + +#### `OptimisticArrayUpdateOptions` +- `getState: () => TState` +- `setState: (updater) => void` +- `operation: 'add' | 'remove' | 'update'` +- `getArray: (state) => TItem[]` +- `setArray: (state, array) => Partial | TState` +- `optimisticItem?: (state, variables) => TItem` +- `matchItem?: (item, variables) => boolean` +- `updateItem?: (item, variables) => TItem` + +## Usage Analysis + +### Import Search Results +**No imports found** - The utility file exists but appears to be **unused** in the current codebase. + +### Related Files + +#### `apps/web/src/utils/optimisticUpdates.ts` +This file contains React Query-based optimistic update utilities: +- `createOptimisticUpdate` - For React Query mutations +- `createArrayOptimisticUpdate` - For array operations with React Query +- `createToggleOptimisticUpdate` - For toggle operations with React Query + +**Note**: The codebase appears to have already migrated to React Query optimistic updates (`optimisticUpdates.ts`), making `optimisticStoreUpdates.ts` potentially obsolete. + +## Migration Status + +### Current State +- ✅ React Query optimistic updates are implemented (`optimisticUpdates.ts`) +- ⚠️ Zustand optimistic updates utility exists but is **unused** (`optimisticStoreUpdates.ts`) + +### Recommendation +Since `optimisticStoreUpdates.ts` is not imported anywhere, it can be safely deleted as part of Action 4.4.1.3 after confirming no usage. + +## Patterns Identified + +### Pattern 1: Manual State Snapshot & Rollback +- Used in: `createOptimisticStoreUpdate`, `withOptimisticUpdate`, `withOptimisticArrayUpdate` +- Approach: Snapshot state before update, restore on error +- Complexity: Medium (manual state management) + +### Pattern 2: React Query Optimistic Updates (Current) +- Used in: `optimisticUpdates.ts` +- Approach: Uses React Query's `onMutate`, `onError`, `onSettled` +- Complexity: Low (framework-provided) + +## Next Steps + +1. ✅ **Action 4.4.1.1**: Audit complete - Documented all optimistic update utilities +2. **Action 4.4.1.2**: Migrate remaining Zustand stores to React Query (if any exist) +3. **Action 4.4.1.3**: Delete `optimisticStoreUpdates.ts` (safe - no imports found) +4. **Action 4.4.1.4**: Audit all mutations for optimistic updates (separate audit)