veza/apps/web/docs/STATE_UTILITIES_AUDIT.md

# State Utilities Audit

**Date**: 2026-01-11  
**Action**: 4.6.1.1 - List all state utility files  
**Status**: ✅ Complete

## Summary

This document lists all state utility files found in `apps/web/src/utils/` and documents their purposes, usage, and status.

## State Utility Files Found

### 1. `stateMiddleware.ts`
- **Purpose**: Zustand middleware for analytics tracking and error handling
- **Exports**:
  - `setAnalyticsHandler()` - Set analytics handler
  - `setErrorHandler()` - Set error handler
  - `stateMiddleware()` - Middleware function
- **Key Features**:
  - Tracks state changes for analytics
  - Handles errors in state updates
  - Provides context for debugging
- **Used By**: Library Store (`stores/library.ts`)
- **Status**: ⚠️ **Used by Library Store** (may be unnecessary complexity)
- **Test File**: `stateMiddleware.test.ts` ✅

### 2. `stateNormalization.ts`
- **Purpose**: Utilities for normalized state management (entities by ID)
- **Exports**:
  - `normalize()` - Convert array to normalized state
  - `denormalize()` - Convert normalized state to array
  - `addToNormalized()` - Add item to normalized state
  - `updateInNormalized()` - Update item in normalized state
  - `removeFromNormalized()` - Remove item from normalized state
  - `replaceNormalized()` - Replace normalized state
  - `mergeNormalized()` - Merge normalized states
  - `getById()` - Get item by ID
  - `getByIds()` - Get items by IDs
- **Key Features**:
  - Normalized state structure: `{ byId: Record<string, T>, allIds: string[] }`
  - Efficient lookups and updates
- **Used By**: Library Store (`stores/library.ts`)
- **Status**: ⚠️ **Used by Library Store** (will become obsolete when Library Store migrates to React Query)
- **Test File**: None ❌

### 3. `stateInvalidation.ts`
- **Purpose**: Unified state invalidation for Zustand stores and React Query
- **Exports**:
  - `invalidateState()` - Invalidate state by resource type
  - `invalidateStateAfterMutation()` - Invalidate after mutation
- **Key Features**:
  - Invalidates both Zustand stores and React Query cache
  - Supports resource-based invalidation
  - Integrates with response cache
- **Used By**: Various mutation handlers
- **Status**: ✅ **Active** (useful for migration period)
- **Test File**: None ❌

### 4. `stateHydration.ts`
- **Purpose**: Hydrate Zustand stores from API on app load
- **Exports**:
  - `hydrateState()` - Hydrate stores from API
  - `useStateHydration()` - React hook for hydration
- **Key Features**:
  - Loads initial state from API
  - Hydrates Auth, Library, and Chat stores
  - Handles errors and loading states
- **Used By**: App initialization, store hydration
- **Status**: ⚠️ **Used for Zustand stores** (will become obsolete when stores migrate to React Query)
- **Test File**: None ❌

### 5. `stateCleanup.ts`
- **Purpose**: Cleanup utilities for Zustand stores (size/age-based)
- **Exports**:
  - `applyCleanup()` - Apply cleanup strategy to store
- **Key Features**:
  - Size-based cleanup (keep N items)
  - Age-based cleanup (remove old items)
  - Normalized state cleanup support
- **Used By**: Potentially Library Store
- **Status**: ⚠️ **May be unused** (needs verification)
- **Test File**: `stateCleanup.test.ts` ✅

### 6. `stateVersioning.ts`
- **Purpose**: State versioning and migration utilities for Zustand stores
- **Exports**:
  - `applyMigrations()` - Apply migrations to state
  - `versionState()` - Add version to state
  - `unversionState()` - Remove version from state
  - `createVersionedStorage()` - Create versioned storage adapter
- **Key Features**:
  - Supports state schema migrations
  - Version tracking for persisted state
  - Migration functions for breaking changes
- **Used By**: Potentially for store migrations
- **Status**: ⚠️ **May be unused** (needs verification)
- **Test Files**: `stateVersioning.test.ts` ✅, `stateVersioning.example.ts` ✅

### 7. `statePersistence.ts`
- **Purpose**: Persistence utilities for Zustand stores
- **Exports**: (needs inspection)
- **Key Features**: (needs inspection)
- **Used By**: (needs inspection)
- **Status**: ⚠️ **Needs inspection**
- **Test File**: None ❌

### 8. `broadcastSync.ts`
- **Purpose**: Synchronize Zustand stores across browser tabs/windows
- **Exports**:
  - `broadcastSync()` - Middleware for tab synchronization
  - `createSynchronizedStore()` - Create synchronized store
- **Key Features**:
  - Uses BroadcastChannel API
  - Syncs state changes across tabs
  - Handles conflicts and race conditions
- **Used By**: UI Store (`stores/ui.ts`), Auth Store (`features/auth/store/authStore.ts`)
- **Status**: ✅ **Active** (useful for multi-tab sync)
- **Test File**: None ❌

### 9. `undoRedo.ts`
- **Purpose**: Undo/redo functionality for Zustand stores
- **Exports**:
  - `undoRedo()` - Middleware for undo/redo
  - `useUndoRedo()` - React hook for undo/redo
  - `UndoRedoManager` - Class for managing history
  - `undoRedoManager` - Singleton instance
- **Key Features**:
  - History tracking for state changes
  - Undo/redo operations
  - Configurable history size
- **Used By**: Library Store (`stores/library.ts`)
- **Status**: ⚠️ **Used by Library Store** (will become obsolete when Library Store migrates to React Query)
- **Test File**: None ❌

### 10. `storeSelectors.ts`
- **Purpose**: Optimized selectors for Zustand stores to prevent unnecessary re-renders
- **Exports**:
  - `useAuthUser()` - Get user from auth store
  - `useAuthStatus()` - Get auth status
  - `useStoreSelector()` - Generic store selector
- **Key Features**:
  - Uses `useShallow` for shallow comparison
  - Prevents unnecessary re-renders
  - Type-safe selectors
- **Used By**: Various components
- **Status**: ✅ **Active** (useful optimization)
- **Test File**: None ❌

## File Statistics

- **Total State Utility Files**: 10
- **With Tests**: 3 (30%)
- **Without Tests**: 7 (70%)
- **Actively Used**: 6
- **Potentially Unused**: 2 (stateCleanup, stateVersioning - needs verification)
- **Will Become Obsolete**: 4 (stateMiddleware, stateNormalization, stateHydration, undoRedo - when stores migrate)

## Usage Analysis

### Utilities Used by Stores
- **Library Store**: `stateMiddleware`, `stateNormalization`, `undoRedo`
- **UI Store**: `broadcastSync`
- **Auth Store**: `broadcastSync`
- **Chat Store**: None (uses Immer middleware)

### Utilities Used by Components
- **storeSelectors**: Used by various components for optimized selectors
- **stateInvalidation**: Used by mutation handlers
- **stateHydration**: Used for app initialization

## Migration Impact

### Will Become Obsolete (After Store Migration)
1. **stateMiddleware** - Only used by Library Store
2. **stateNormalization** - Only used by Library Store
3. **stateHydration** - Only hydrates Zustand stores
4. **undoRedo** - Only used by Library Store

### Will Remain Useful
1. **broadcastSync** - Useful for UI state sync across tabs
2. **storeSelectors** - Useful for optimized Zustand selectors
3. **stateInvalidation** - Useful during migration period

### Needs Investigation
1. **stateCleanup** - Verify if actually used
2. **stateVersioning** - Verify if actually used
3. **statePersistence** - Inspect purpose and usage

## Recommendations

### High Priority
1. ✅ **Action 4.6.1.1**: Audit complete - 10 utilities documented
2. **Action 4.6.1.2**: Verify usage of `stateCleanup`, `stateVersioning`, `statePersistence`
3. **Action 4.6.1.3**: Add tests for utilities without tests (7 files)

### Medium Priority
1. Plan removal of obsolete utilities after store migration
2. Document migration path for utilities that will become obsolete

### Low Priority
1. Consider consolidating similar utilities
2. Review if `stateMiddleware` complexity is justified

## Next Steps

1. ✅ **Action 4.6.1.1**: List complete - 10 state utilities documented
2. **Action 4.6.1.2**: Verify usage of potentially unused utilities
3. **Action 4.6.1.3**: Add missing tests