veza/apps/web/src/docs/STATENORMALIZATION_UTILITY_AUDIT.md

StateNormalization Utility Audit

Date: 2025-01-27
Action: 4.6.1.11
Status: ✅ Complete

Summary

The stateNormalization utility (apps/web/src/utils/stateNormalization.ts) is only used in an outdated test file that tests obsolete Library Store functionality. The Library Store no longer uses normalized state structure (migrated to React Query in Action 4.1.2.6).

Usage Analysis

Imports

• ✅ One import found: apps/web/src/test/stores.test.ts (line 7)
  • Imports createEmptyNormalized function
  • Used in tests for Library Store (lines 158-159)
  • Tests are outdated - they test state.items and state.favorites which no longer exist

Functions Exported

1. normalize<T>() - Normalize array to normalized state
2. denormalize<T>() - Convert normalized state back to array
3. addToNormalized<T>() - Add item to normalized state
4. updateInNormalized<T>() - Update item in normalized state
5. removeFromNormalized<T>() - Remove item from normalized state
6. replaceNormalized<T>() - Replace all items
7. mergeNormalized<T>() - Merge items into normalized state
8. getById<T>() - Get item by ID
9. getByIds<T>() - Get multiple items by IDs
10. hasId<T>() - Check if item exists
11. getCount<T>() - Get count of items
12. createEmptyNormalized<T>() - Create empty normalized state
13. reorderNormalized<T>() - Reorder items

Only createEmptyNormalized is used, and only in outdated tests.

Other "normalize" Matches

The grep found many other "normalize" functions, but they are different utilities:

• normalizeId() / normalizeObjectIds() - ID normalization (different utility, still used)
• normalizeUrl() - URL normalization (different utility, still used)
• normalizeDate() - Date normalization (different utility, still used)
• normalizeError() - Error normalization (different utility, still used)
• normalizeEndpoint() - API endpoint normalization (different utility, still used)

These are not related to stateNormalization.ts.

Historical Context

• Previously used by Library Store to normalize items and favorites arrays into { byId, allIds } structure
• Removed in Action 4.1.2.6 when Library Store domain data was migrated to React Query
• React Query handles data fetching and caching, making normalization unnecessary

Current State

The Library Store now only contains UI state (filters):

export interface LibraryState {
  filters: {
    type?: string;
    search?: string;
  };
}

Domain data (items, favorites) is managed by React Query hooks.

Recommendation

✅ Safe to remove - The utility is only used in outdated tests. However:

1. Option A (Recommended): Update apps/web/src/test/stores.test.ts to remove outdated Library Store tests, then delete the utility
2. Option B: Delete the utility and fix the test file (it will fail, but tests are already outdated)

Next Steps

• Action 4.6.1.12: Remove stateNormalization if unused ✅ (confirmed unused, but test file needs update)