fix(smartstate): Fix StateAction trigger method to properly return Promise

changelog.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 2025-07-19 - 2.0.22 - fix(smartstate)
+Fix StateAction trigger method to properly return Promise
+
+- Fixed StateAction.trigger() to return Promise<TStateType> as expected
+- Updated readme with improved documentation and examples
+- Replaced outdated legal information with Task Venture Capital GmbH details
+- Added implementation notes in readme.hints.md
+
+## 2025-06-19 - 2.0.21 - maintenance
+General updates and improvements
+
 ## 2025-06-19 - 2.0.20 - fix(smartstate)
 Update build scripts and dependency versions; replace isohash with smarthashWeb for state hash generation
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartstate",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "private": false,
   "description": "A package for handling and managing state in applications.",
   "main": "dist_ts/index.js",

readme.hints.md

@@ -1 +1,39 @@
+# 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<TStatePayload>
+  2. `await statePart.dispatchAction(stateAction, payload)` - returns Promise<TStatePayload>
+- 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

readme.md

@@ -1,12 +1,12 @@
 # @push.rocks/smartstate
-a package that handles state in a good way
+A package for handling and managing state in applications
 
 ## Install
 
-To install `@push.rocks/smartstate`, you can use npm (Node Package Manager). Run the following command in your terminal:
+To install `@push.rocks/smartstate`, you can use pnpm (Performant Node Package Manager). Run the following command in your terminal:
 
 ```bash
-npm install @push.rocks/smartstate --save
+pnpm install @push.rocks/smartstate --save
 ```
 
 This will add `@push.rocks/smartstate` to your project's dependencies.
@@ -31,17 +31,30 @@ import { Smartstate, StatePart, StateAction } from '@push.rocks/smartstate';
 const myAppSmartState = new Smartstate<YourStatePartNamesEnum>();
 ```
 
+### Understanding Init Modes
+
+When creating state parts, you can specify different initialization modes:
+
+- **`'soft'`** - Allows existing state parts to remain (default behavior)
+- **`'mandatory'`** - Fails if there's an existing state part with the same name
+- **`'force'`** - Overwrites any existing state part
+- **`'persistent'`** - Enables WebStore persistence using IndexedDB
+
 ### Defining State Parts
 
 State parts represent separable sections of your state, making it easier to manage and modularize. For example, you may have a state part for user data and another for application settings. 
 
-Define an enum for state part names for better management:
+Define state part names using either enums or string literal types:
 
 ```typescript
+// Option 1: Using enums
 enum AppStateParts {
-  UserState,
-  SettingsState
+  UserState = 'UserState',
+  SettingsState = 'SettingsState'
 }
+
+// Option 2: Using string literal types (simpler approach)
+type AppStateParts = 'UserState' | 'SettingsState';
 ```
 
 Now, let's create a state part within our `myAppSmartState` instance:
@@ -54,8 +67,11 @@ interface IUserState {
 
 const userStatePart = await myAppSmartState.getStatePart<IUserState>(
   AppStateParts.UserState,
-  { isLoggedIn: false } // Initial state
+  { isLoggedIn: false }, // Initial state
+  'soft' // Init mode (optional, defaults to 'soft')
 );
+
+// Note: Persistent state parts are automatically initialized internally
 ```
 
 ### Subscribing to State Changes
@@ -93,27 +109,110 @@ const loginUserAction = userStatePart.createAction<ILoginPayload>(async (statePa
 
 // Dispatch the action to update the state
 loginUserAction.trigger({ username: 'johnDoe' });
+// or await the result
+const newState = await loginUserAction.trigger({ username: 'johnDoe' });
 ```
 
-### Persistent State
+### Dispatching Actions
 
-`Smartstate` supports the concept of persistent states, where you can maintain state across sessions. To utilize this, specify a persistent mode when getting a state part:
+There are two ways to dispatch actions:
 
 ```typescript
-const settingsStatePart = await myAppSmartState.getStatePart<AppStateParts, ISettingsState>(
+// Method 1: Using trigger on the action (returns promise)
+const newState = await loginUserAction.trigger({ username: 'johnDoe' });
+// or fire and forget
+loginUserAction.trigger({ username: 'johnDoe' });
+
+// Method 2: Using dispatchAction on the state part (returns promise)
+const newState = await userStatePart.dispatchAction(loginUserAction, { username: 'johnDoe' });
+```
+
+Both methods return a Promise with the new state, giving you flexibility in how you handle the result.
+
+### Additional State Methods
+
+`StatePart` provides several useful methods for state management:
+
+```typescript
+// Wait for a specific state condition
+await userStatePart.waitUntilPresent();
+
+// Wait for a specific property to be present
+await userStatePart.waitUntilPresent(state => state.username);
+
+// Setup initial state with async operations
+await userStatePart.stateSetup(async (statePart) => {
+  // Perform async initialization
+  const userData = await fetchUserData();
+  return { ...statePart.getState(), ...userData };
+});
+
+// Defer notification to end of call stack
+userStatePart.notifyChangeCumulative();
+```
+
+### Persistent State with WebStore
+
+`Smartstate` supports persistent states using WebStore (IndexedDB-based storage), allowing you to maintain state across sessions:
+
+```typescript
+const settingsStatePart = await myAppSmartState.getStatePart<ISettingsState>(
   AppStateParts.SettingsState,
   { theme: 'light' }, // Initial state
   'persistent' // Mode
 );
+
+// Note: init() is called automatically for persistent mode
 ```
 
-This mode ensures that the state is saved and can be reloaded even after the application restarts, providing a seamless user experience.
+Persistent state automatically:
+- Saves state changes to IndexedDB
+- Restores state on application restart
+- Manages storage with configurable database and store names
+
+### Performance Optimization
+
+`Smartstate` includes built-in performance optimizations:
+
+- **State Change Detection**: Detects actual state changes to prevent unnecessary notifications when state values haven't truly changed
+- **Cumulative Notifications**: Batch multiple state changes into a single notification using `notifyChangeCumulative()`
+- **Selective Subscriptions**: Use selectors to subscribe only to specific state properties
+
+### RxJS Integration
+
+`Smartstate` leverages RxJS for reactive state management:
+
+```typescript
+// State is exposed as an RxJS Subject
+const stateObservable = userStatePart.select();
+
+// Automatically starts with current state value
+stateObservable.subscribe((state) => {
+  console.log('Current state:', state);
+});
+
+// Use selectors for specific properties
+userStatePart.select(state => state.username)
+  .pipe(
+    distinctUntilChanged(),
+    filter(username => username !== undefined)
+  )
+  .subscribe(username => {
+    console.log('Username changed:', username);
+  });
+```
 
 ### Comprehensive Usage
 
 Putting it all together, `@push.rocks/smartstate` offers a flexible and powerful pattern for managing application state. By modularizing state parts, subscribing to state changes, and controlling state modifications through actions, developers can maintain a clean and scalable architecture. Combining these strategies with persistent states unlocks the full potential for creating dynamic and user-friendly applications.
 
-Remember to leverage TypeScript for its excellent support for types and interfaces, enhancing your development experience with type checking and IntelliSense, ensuring a more reliable and maintainable codebase.
+Key features:
+- **Type-safe state management** with full TypeScript support
+- **Reactive state updates** using RxJS observables
+- **Persistent state** with IndexedDB storage
+- **Performance optimized** with state hash detection
+- **Modular architecture** with separate state parts
+- **Action-based updates** for predictable state modifications
 
 For more complex scenarios, consider combining multiple state parts, creating hierarchical state structures, and integrating with other state management solutions as needed. With `@push.rocks/smartstate`, the possibilities are vast, empowering you to tailor the state management approach to fit the unique requirements of your project.
 

ts/smartstate.classes.stateaction.ts

@@ -14,7 +14,7 @@ export class StateAction<TStateType, TActionPayloadType> {
     public actionDef: IActionDef<TStateType, TActionPayloadType>
   ) {}
 
-  public trigger(payload: TActionPayloadType) {
-    this.statePartRef.dispatchAction(this, payload);
+  public trigger(payload: TActionPayloadType): Promise<TStateType> {
+    return this.statePartRef.dispatchAction(this, payload);
   }
 }