fix(core): Fix state initialization, hash detection, and validation - v2.0.25

readme.hints.md

@@ -1,39 +1,52 @@
 # Smartstate Implementation Notes
 
-## Current API (as of analysis)
+## Current API (as of v2.0.24+)
 
 ### State Part Initialization
-- State parts can be created with different init modes: 'soft', 'mandatory', 'force', 'persistent'
+- State parts can be created with different init modes: 'soft' (default), 'mandatory', 'force', 'persistent'
+  - 'soft' - returns existing state part if exists, creates new if not
+  - 'mandatory' - requires state part to not exist, fails if it does
+  - 'force' - always creates new state part, overwriting any existing
+  - 'persistent' - like 'soft' but with WebStore persistence (IndexedDB)
 - Persistent mode automatically calls init() internally - no need to call it manually
-- WebStore integration for persistent state uses IndexedDB
+- State merge order fixed: initial state takes precedence over stored state
 
 ### Actions
 - Actions are created with `createAction()` method
 - Two ways to dispatch actions:
   1. `stateAction.trigger(payload)` - returns Promise<TStatePayload>
   2. `await statePart.dispatchAction(stateAction, payload)` - returns Promise<TStatePayload>
-- Both methods now return the same Promise, providing flexibility in usage
+- Both methods return the same Promise, providing flexibility in usage
 
 ### State Management Methods
-- `select()` - returns Observable with startWith current state
+- `select()` - returns Observable with startWith current state, filters undefined states
 - `waitUntilPresent()` - waits for specific state condition
 - `stateSetup()` - async state initialization with cumulative defer
-- `notifyChangeCumulative()` - defers notification to end of call stack (no callback parameter)
+- `notifyChangeCumulative()` - defers notification to end of call stack
+- `getState()` - returns current state or undefined
+- `setState()` - validates state before setting, notifies only on actual changes
 
 ### State Hash Detection
 - Uses SHA256 hash to detect actual state changes
-- Bug: Currently stores the state object itself as hash instead of the actual hash
-- This prevents proper duplicate notification prevention
+- Fixed: Hash comparison now properly awaits async hash calculation
+- Prevents duplicate notifications for identical state values
+- `notifyChange()` is now async to support proper hash comparison
+
+### State Validation
+- Basic validation ensures state is not null/undefined
+- `validateState()` method can be overridden in subclasses for custom validation
+- Validation runs on both setState() and when loading from persistent storage
 
 ### Type System
 - Can use either enums or string literal types for state part names
 - Test uses simple string types: `type TMyStateParts = 'testStatePart'`
+- State can be undefined initially, handled properly in select() and other methods
 
-## Fixed Issues in Documentation
-1. Updated trigger() to return Promise (API enhancement)
-2. Added dispatchAction as alternative method
-3. Corrected notifyChangeCumulative usage
-4. Clarified persistent mode auto-init
-5. Added stateSetup documentation
-6. Fixed state hash detection description
-7. Both trigger() and dispatchAction() now return Promise for consistency
+## Recent Fixes (v2.0.24+)
+1. Fixed state hash bug - now properly compares hash values instead of promises
+2. Fixed state initialization merge order - initial state now takes precedence
+3. Ensured stateStore is properly typed as potentially undefined
+4. Simplified init mode logic with clear behavior for each mode
+5. Added state validation with extensible validateState() method
+6. Made notifyChange() async to support proper hash comparison
+7. Updated select() to filter undefined states