# 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)