veza/apps/web/docs/OPTIMISTIC_STORE_UPDATES_AUDIT.md

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)