veza/apps/web/docs/STATE_UTILITIES_CATEGORIZATION.md

# State Utilities Categorization

**Date**: 2026-01-11  
**Action**: 4.6.1.2 - Determine which utilities are still needed  
**Status**: ✅ Complete

## Summary

This document categorizes all state utility files into: **Needed**, **Redundant**, and **Obsolete** based on actual usage analysis.

## Categorization Results

### ✅ **NEEDED** - Actively Used (6 utilities)

#### 1. `broadcastSync.ts`
- **Category**: ✅ **NEEDED** - Will remain useful
- **Usage**: Used by UI Store (`stores/ui.ts`), Auth Store (`features/auth/store/authStore.ts`)
- **Purpose**: Synchronize Zustand stores across browser tabs/windows
- **Future**: Will remain useful for UI state synchronization
- **Action**: Keep

#### 2. `storeSelectors.ts`
- **Category**: ✅ **NEEDED** - Will remain useful
- **Usage**: Used by various components (`DashboardPage.tsx`, etc.)
- **Purpose**: Optimized selectors for Zustand stores to prevent unnecessary re-renders
- **Future**: Will remain useful for optimized Zustand selectors
- **Action**: Keep

#### 3. `stateInvalidation.ts`
- **Category**: ✅ **NEEDED** - Useful during migration period
- **Usage**: Used by `api/client.ts` for mutation invalidation
- **Purpose**: Unified state invalidation for Zustand stores and React Query
- **Future**: Useful during migration period, may need updates for React Query
- **Action**: Keep, update for React Query (Action 4.6.1.5)

#### 4. `stateMiddleware.ts`
- **Category**: ⚠️ **NEEDED** - Will become obsolete after Library Store migration
- **Usage**: Used by Library Store (`stores/library.ts`)
- **Purpose**: Zustand middleware for analytics tracking and error handling
- **Future**: Will become obsolete when Library Store migrates to React Query
- **Action**: Keep until Library Store migration, then remove

#### 5. `stateNormalization.ts`
- **Category**: ⚠️ **NEEDED** - Will become obsolete after Library Store migration
- **Usage**: Used by Library Store (`stores/library.ts`), storeSelectors (`utils/storeSelectors.ts`)
- **Purpose**: Utilities for normalized state management (entities by ID)
- **Future**: Will become obsolete when Library Store migrates to React Query
- **Action**: Keep until Library Store migration, then remove

#### 6. `undoRedo.ts`
- **Category**: ⚠️ **NEEDED** - Will become obsolete after Library Store migration
- **Usage**: Used by Library Store (`stores/library.ts`)
- **Purpose**: Undo/redo functionality for Zustand stores
- **Future**: Will become obsolete when Library Store migrates to React Query
- **Action**: Keep until Library Store migration, then remove

#### 7. `stateHydration.ts`
- **Category**: ⚠️ **NEEDED** - Will become obsolete after store migrations
- **Usage**: Used by `App.tsx` for app initialization
- **Purpose**: Hydrate Zustand stores from API on app load
- **Future**: Will become obsolete when stores migrate to React Query (React Query handles hydration)
- **Action**: Keep until store migrations complete, then remove

### ❌ **OBSOLETE** - Not Used (3 utilities)

#### 8. `stateCleanup.ts`
- **Category**: ❌ **OBSOLETE** - Not used in codebase
- **Usage**: Only imported in test file (`stateCleanup.test.ts`), NOT used in actual code
- **Purpose**: Cleanup utilities for Zustand stores (size/age-based)
- **Future**: Not needed
- **Action**: **DELETE** (Action 4.6.1.3)

#### 9. `stateVersioning.ts`
- **Category**: ❌ **OBSOLETE** - Not used in codebase
- **Usage**: Only imported in test file (`stateVersioning.test.ts`) and example file (`stateVersioning.example.ts`), NOT used in actual code
- **Purpose**: State versioning and migration utilities for Zustand stores
- **Future**: Not needed (Zustand persist middleware handles versioning)
- **Action**: **DELETE** (Action 4.6.1.3)

#### 10. `statePersistence.ts`
- **Category**: ❌ **OBSOLETE** - Not used in codebase
- **Usage**: `createPersistentStorage` function exists but is NOT imported anywhere
- **Purpose**: Persistence utilities for Zustand stores
- **Future**: Not needed (Zustand's `persist` middleware is used directly)
- **Action**: **DELETE** (Action 4.6.1.3)

## Summary Statistics

- **Total Utilities**: 10
- **Needed (Active)**: 7 (70%)
  - Will remain useful: 2 (broadcastSync, storeSelectors)
  - Useful during migration: 1 (stateInvalidation)
  - Will become obsolete after migrations: 4 (stateMiddleware, stateNormalization, undoRedo, stateHydration)
- **Obsolete (Unused)**: 3 (30%)
  - stateCleanup
  - stateVersioning
  - statePersistence

## Migration Timeline

### Phase 1: Immediate Cleanup (Now)
- Delete obsolete utilities: `stateCleanup.ts`, `stateVersioning.ts`, `statePersistence.ts`
- **Risk**: LOW (not used)

### Phase 2: After Library Store Migration
- Delete: `stateMiddleware.ts`, `stateNormalization.ts`, `undoRedo.ts`
- **Risk**: MEDIUM (verify Library Store fully migrated)

### Phase 3: After All Store Migrations
- Delete: `stateHydration.ts`
- Update: `stateInvalidation.ts` to work with React Query only
- **Risk**: MEDIUM (verify all stores migrated)

### Phase 4: Long-term Keepers
- Keep: `broadcastSync.ts` (for UI state sync)
- Keep: `storeSelectors.ts` (for optimized selectors)
- Keep: `stateInvalidation.ts` (updated for React Query)

## Recommendations

### High Priority
1. ✅ **Action 4.6.1.2**: Categorization complete
2. **Action 4.6.1.3**: Delete obsolete utilities (`stateCleanup`, `stateVersioning`, `statePersistence`)
3. **Action 4.6.1.4**: Simplify `stateMiddleware` (or plan removal after Library Store migration)

### Medium Priority
1. Plan removal of utilities after Library Store migration
2. Update `stateInvalidation` for React Query (Action 4.6.1.5)

### Low Priority
1. Document migration path for utilities that will become obsolete
2. Add tests for utilities that will remain (if missing)

## Files to Delete (Action 4.6.1.3)

1. `apps/web/src/utils/stateCleanup.ts` - Not used
2. `apps/web/src/utils/stateCleanup.test.ts` - Test for unused utility
3. `apps/web/src/utils/stateVersioning.ts` - Not used
4. `apps/web/src/utils/stateVersioning.test.ts` - Test for unused utility
5. `apps/web/src/utils/stateVersioning.example.ts` - Example for unused utility
6. `apps/web/src/utils/statePersistence.ts` - Not used

**Total files to delete**: 6

## Verification

### Obsolete Utilities - Import Check Results
- ✅ `stateCleanup` - Only in test file
- ✅ `stateVersioning` - Only in test and example files
- ✅ `statePersistence` - No imports found

### Needed Utilities - Import Check Results
- ✅ `broadcastSync` - Used by 2 stores
- ✅ `storeSelectors` - Used by multiple components
- ✅ `stateInvalidation` - Used by api/client.ts
- ✅ `stateMiddleware` - Used by Library Store
- ✅ `stateNormalization` - Used by Library Store and storeSelectors
- ✅ `undoRedo` - Used by Library Store
- ✅ `stateHydration` - Used by App.tsx

## Next Steps

1. ✅ **Action 4.6.1.2**: Categorization complete
2. **Action 4.6.1.3**: Delete obsolete utilities (6 files)
3. **Action 4.6.1.4**: Simplify or plan removal of stateMiddleware
4. **Action 4.6.1.5**: Update stateInvalidation for React Query