diff --git a/apps/web/docs/STATE_UTILITIES_CATEGORIZATION.md b/apps/web/docs/STATE_UTILITIES_CATEGORIZATION.md new file mode 100644 index 000000000..8a57ad1cd --- /dev/null +++ b/apps/web/docs/STATE_UTILITIES_CATEGORIZATION.md @@ -0,0 +1,166 @@ +# 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