113 lines
4.6 KiB
Markdown
113 lines
4.6 KiB
Markdown
# 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<TState, TVariables>`
|
|
- **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<TState, TVariables, TResponse>`
|
|
- **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<TState, TItem, TVariables, TResponse>`
|
|
- **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<TState, TVariables>`
|
|
- `getState: () => TState`
|
|
- `setState: (updater) => void`
|
|
- `optimisticUpdate: (state, variables) => Partial<TState> | TState`
|
|
- `rollback?: (state, variables, error?) => Partial<TState> | TState`
|
|
- `applyResponse?: (state, variables, response) => Partial<TState> | TState`
|
|
|
|
#### `OptimisticUpdateResult<TState>`
|
|
- `previousState: TState`
|
|
- `rollback: () => void`
|
|
- `applyResponse: (response: unknown) => void`
|
|
|
|
#### `OptimisticArrayUpdateOptions<TState, TItem, TVariables>`
|
|
- `getState: () => TState`
|
|
- `setState: (updater) => void`
|
|
- `operation: 'add' | 'remove' | 'update'`
|
|
- `getArray: (state) => TItem[]`
|
|
- `setArray: (state, array) => Partial<TState> | 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)
|