state-ownership: categorize state utilities as needed, redundant, or obsolete (Action 4.6.1.2)
This commit is contained in:
senke
parent
42ef9898b2
commit
8721555b76
1 changed files with 166 additions and 0 deletions
166
apps/web/docs/STATE_UTILITIES_CATEGORIZATION.md
Normal file
166
apps/web/docs/STATE_UTILITIES_CATEGORIZATION.md
Normal file
|
|
@ -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
|
||||
Loading…
Reference in a new issue