smartstate/readme.hints.md

Smartstate Implementation Notes

Current API (as of analysis)

State Part Initialization

• State parts can be created with different init modes: 'soft', 'mandatory', 'force', 'persistent'
• Persistent mode automatically calls init() internally - no need to call it manually
• WebStore integration for persistent state uses IndexedDB

Actions

• Actions are created with createAction() method
• Two ways to dispatch actions:
  1. stateAction.trigger(payload) - returns Promise
  2. await statePart.dispatchAction(stateAction, payload) - returns Promise
• Both methods now return the same Promise, providing flexibility in usage

State Management Methods

• select() - returns Observable with startWith current state
• waitUntilPresent() - waits for specific state condition
• stateSetup() - async state initialization with cumulative defer
• notifyChangeCumulative() - defers notification to end of call stack (no callback parameter)

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

Type System

• Can use either enums or string literal types for state part names
• Test uses simple string types: type TMyStateParts = 'testStatePart'

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