@push.rocks/smartstate 2.0.23 → 2.0.25

package/dist_ts/smartstate.classes.smartstate.d.ts

@@ -10,9 +10,10 @@ export declare class Smartstate<StatePartNameType extends string> {
     constructor();
     /**
      * Allows getting and initializing a new statepart
-     * initMode === 'soft' it will allow existing stateparts
-     * initMode === 'mandatory' will fail if there is an existing statepart
-     * initMode === 'force' will overwrite any existing statepart
+     * initMode === 'soft' (default) - returns existing statepart if exists, creates new if not
+     * initMode === 'mandatory' - requires statepart to not exist, fails if it does
+     * initMode === 'force' - always creates new statepart, overwriting any existing
+     * initMode === 'persistent' - like 'soft' but with webstore persistence
      * @param statePartNameArg
      * @param initialArg
      * @param initMode
@@ -22,6 +23,7 @@ export declare class Smartstate<StatePartNameType extends string> {
      * Creates a statepart
      * @param statePartName
      * @param initialPayloadArg
+     * @param initMode
      */
     private createStatePart;
 }

package/dist_ts/smartstate.classes.smartstate.js

@@ -9,23 +9,34 @@ export class Smartstate {
     }
     /**
      * Allows getting and initializing a new statepart
-     * initMode === 'soft' it will allow existing stateparts
-     * initMode === 'mandatory' will fail if there is an existing statepart
-     * initMode === 'force' will overwrite any existing statepart
+     * initMode === 'soft' (default) - returns existing statepart if exists, creates new if not
+     * initMode === 'mandatory' - requires statepart to not exist, fails if it does
+     * initMode === 'force' - always creates new statepart, overwriting any existing
+     * initMode === 'persistent' - like 'soft' but with webstore persistence
      * @param statePartNameArg
      * @param initialArg
      * @param initMode
      */
-    async getStatePart(statePartNameArg, initialArg, initMode) {
-        if (this.statePartMap[statePartNameArg]) {
-            if (initialArg && (!initMode || initMode !== 'soft')) {
-                throw new Error(`${statePartNameArg} already exists, yet you try to set an initial state again`);
+    async getStatePart(statePartNameArg, initialArg, initMode = 'soft') {
+        const existingStatePart = this.statePartMap[statePartNameArg];
+        if (existingStatePart) {
+            switch (initMode) {
+                case 'mandatory':
+                    throw new Error(`State part '${statePartNameArg}' already exists, but initMode is 'mandatory'`);
+                case 'force':
+                    // Force mode: create new state part
+                    return this.createStatePart(statePartNameArg, initialArg, initMode);
+                case 'soft':
+                case 'persistent':
+                default:
+                    // Return existing state part
+                    return existingStatePart;
             }
-            return this.statePartMap[statePartNameArg];
         }
         else {
+            // State part doesn't exist
             if (!initialArg) {
-                throw new Error(`${statePartNameArg} does not yet exist, yet you don't provide an initial state`);
+                throw new Error(`State part '${statePartNameArg}' does not exist and no initial state provided`);
             }
             return this.createStatePart(statePartNameArg, initialArg, initMode);
         }
@@ -34,8 +45,9 @@ export class Smartstate {
      * Creates a statepart
      * @param statePartName
      * @param initialPayloadArg
+     * @param initMode
      */
-    async createStatePart(statePartName, initialPayloadArg, initMode) {
+    async createStatePart(statePartName, initialPayloadArg, initMode = 'soft') {
         const newState = new StatePart(statePartName, initMode === 'persistent'
             ? {
                 dbName: 'smartstate',
@@ -45,11 +57,11 @@ export class Smartstate {
         await newState.init();
         const currentState = newState.getState();
         await newState.setState({
-            ...initialPayloadArg,
             ...currentState,
+            ...initialPayloadArg,
         });
         this.statePartMap[statePartName] = newState;
         return newState;
     }
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRzdGF0ZS5jbGFzc2VzLnNtYXJ0c3RhdGUuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9zbWFydHN0YXRlLmNsYXNzZXMuc21hcnRzdGF0ZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLHlCQUF5QixDQUFDO0FBQ25ELE9BQU8sRUFBRSxTQUFTLEVBQUUsTUFBTSxtQ0FBbUMsQ0FBQztBQUk5RDs7R0FFRztBQUNILE1BQU0sT0FBTyxVQUFVO0lBR3JCO1FBRk8saUJBQVksR0FBdUUsRUFBRSxDQUFDO0lBRTlFLENBQUM7SUFFaEI7Ozs7Ozs7O09BUUc7SUFDSSxLQUFLLENBQUMsWUFBWSxDQUN2QixnQkFBbUMsRUFDbkMsVUFBd0IsRUFDeEIsUUFBb0I7UUFFcEIsSUFBSSxJQUFJLENBQUMsWUFBWSxDQUFDLGdCQUFnQixDQUFDLEVBQUUsQ0FBQztZQUN4QyxJQUFJLFVBQVUsSUFBSSxDQUFDLENBQUMsUUFBUSxJQUFJLFFBQVEsS0FBSyxNQUFNLENBQUMsRUFBRSxDQUFDO2dCQUNyRCxNQUFNLElBQUksS0FBSyxDQUNiLEdBQUcsZ0JBQWdCLDREQUE0RCxDQUNoRixDQUFDO1lBQ0osQ0FBQztZQUNELE9BQU8sSUFBSSxDQUFDLFlBQVksQ0FBQyxnQkFBZ0IsQ0FBOEMsQ0FBQztRQUMxRixDQUFDO2FBQU0sQ0FBQztZQUNOLElBQUksQ0FBQyxVQUFVLEVBQUUsQ0FBQztnQkFDaEIsTUFBTSxJQUFJLEtBQUssQ0FDYixHQUFHLGdCQUFnQiw2REFBNkQsQ0FDakYsQ0FBQztZQUNKLENBQUM7WUFDRCxPQUFPLElBQUksQ0FBQyxlQUFlLENBQWMsZ0JBQWdCLEVBQUUsVUFBVSxFQUFFLFFBQVEsQ0FBQyxDQUFDO1FBQ25GLENBQUM7SUFDSCxDQUFDO0lBRUQ7Ozs7T0FJRztJQUNLLEtBQUssQ0FBQyxlQUFlLENBQzNCLGFBQWdDLEVBQ2hDLGlCQUE4QixFQUM5QixRQUFvQjtRQUVwQixNQUFNLFFBQVEsR0FBRyxJQUFJLFNBQVMsQ0FDNUIsYUFBYSxFQUNiLFFBQVEsS0FBSyxZQUFZO1lBQ3ZCLENBQUMsQ0FBQztnQkFDRSxNQUFNLEVBQUUsWUFBWTtnQkFDcEIsU0FBUyxFQUFFLGFBQWE7YUFDekI7WUFDSCxDQUFDLENBQUMsSUFBSSxDQUNULENBQUM7UUFDRixNQUFNLFFBQVEsQ0FBQyxJQUFJLEVBQUUsQ0FBQztRQUN0QixNQUFNLFlBQVksR0FBRyxRQUFRLENBQUMsUUFBUSxFQUFFLENBQUM7UUFDekMsTUFBTSxRQUFRLENBQUMsUUFBUSxDQUFDO1lBQ3RCLEdBQUcsaUJBQWlCO1lBQ3BCLEdBQUcsWUFBWTtTQUNoQixDQUFDLENBQUM7UUFDSCxJQUFJLENBQUMsWUFBWSxDQUFDLGFBQWEsQ0FBQyxHQUFHLFFBQVEsQ0FBQztRQUM1QyxPQUFPLFFBQVEsQ0FBQztJQUNsQixDQUFDO0NBQ0YifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRzdGF0ZS5jbGFzc2VzLnNtYXJ0c3RhdGUuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9zbWFydHN0YXRlLmNsYXNzZXMuc21hcnRzdGF0ZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLHlCQUF5QixDQUFDO0FBQ25ELE9BQU8sRUFBRSxTQUFTLEVBQUUsTUFBTSxtQ0FBbUMsQ0FBQztBQUk5RDs7R0FFRztBQUNILE1BQU0sT0FBTyxVQUFVO0lBR3JCO1FBRk8saUJBQVksR0FBdUUsRUFBRSxDQUFDO0lBRTlFLENBQUM7SUFFaEI7Ozs7Ozs7OztPQVNHO0lBQ0ksS0FBSyxDQUFDLFlBQVksQ0FDdkIsZ0JBQW1DLEVBQ25DLFVBQXdCLEVBQ3hCLFdBQXNCLE1BQU07UUFFNUIsTUFBTSxpQkFBaUIsR0FBRyxJQUFJLENBQUMsWUFBWSxDQUFDLGdCQUFnQixDQUFDLENBQUM7UUFFOUQsSUFBSSxpQkFBaUIsRUFBRSxDQUFDO1lBQ3RCLFFBQVEsUUFBUSxFQUFFLENBQUM7Z0JBQ2pCLEtBQUssV0FBVztvQkFDZCxNQUFNLElBQUksS0FBSyxDQUNiLGVBQWUsZ0JBQWdCLCtDQUErQyxDQUMvRSxDQUFDO2dCQUNKLEtBQUssT0FBTztvQkFDVixvQ0FBb0M7b0JBQ3BDLE9BQU8sSUFBSSxDQUFDLGVBQWUsQ0FBYyxnQkFBZ0IsRUFBRSxVQUFVLEVBQUUsUUFBUSxDQUFDLENBQUM7Z0JBQ25GLEtBQUssTUFBTSxDQUFDO2dCQUNaLEtBQUssWUFBWSxDQUFDO2dCQUNsQjtvQkFDRSw2QkFBNkI7b0JBQzdCLE9BQU8saUJBQThELENBQUM7WUFDMUUsQ0FBQztRQUNILENBQUM7YUFBTSxDQUFDO1lBQ04sMkJBQTJCO1lBQzNCLElBQUksQ0FBQyxVQUFVLEVBQUUsQ0FBQztnQkFDaEIsTUFBTSxJQUFJLEtBQUssQ0FDYixlQUFlLGdCQUFnQixnREFBZ0QsQ0FDaEYsQ0FBQztZQUNKLENBQUM7WUFDRCxPQUFPLElBQUksQ0FBQyxlQUFlLENBQWMsZ0JBQWdCLEVBQUUsVUFBVSxFQUFFLFFBQVEsQ0FBQyxDQUFDO1FBQ25GLENBQUM7SUFDSCxDQUFDO0lBRUQ7Ozs7O09BS0c7SUFDSyxLQUFLLENBQUMsZUFBZSxDQUMzQixhQUFnQyxFQUNoQyxpQkFBOEIsRUFDOUIsV0FBc0IsTUFBTTtRQUU1QixNQUFNLFFBQVEsR0FBRyxJQUFJLFNBQVMsQ0FDNUIsYUFBYSxFQUNiLFFBQVEsS0FBSyxZQUFZO1lBQ3ZCLENBQUMsQ0FBQztnQkFDRSxNQUFNLEVBQUUsWUFBWTtnQkFDcEIsU0FBUyxFQUFFLGFBQWE7YUFDekI7WUFDSCxDQUFDLENBQUMsSUFBSSxDQUNULENBQUM7UUFDRixNQUFNLFFBQVEsQ0FBQyxJQUFJLEVBQUUsQ0FBQztRQUN0QixNQUFNLFlBQVksR0FBRyxRQUFRLENBQUMsUUFBUSxFQUFFLENBQUM7UUFDekMsTUFBTSxRQUFRLENBQUMsUUFBUSxDQUFDO1lBQ3RCLEdBQUcsWUFBWTtZQUNmLEdBQUcsaUJBQWlCO1NBQ3JCLENBQUMsQ0FBQztRQUNILElBQUksQ0FBQyxZQUFZLENBQUMsYUFBYSxDQUFDLEdBQUcsUUFBUSxDQUFDO1FBQzVDLE9BQU8sUUFBUSxDQUFDO0lBQ2xCLENBQUM7Q0FDRiJ9

package/dist_ts/smartstate.classes.statepart.d.ts

@@ -3,7 +3,7 @@ import { StateAction, type IActionDef } from './smartstate.classes.stateaction.j
 export declare class StatePart<TStatePartName, TStatePayload> {
     name: TStatePartName;
     state: plugins.smartrx.rxjs.Subject<TStatePayload>;
-    stateStore: TStatePayload;
+    stateStore: TStatePayload | undefined;
     private cumulativeDeferred;
     private webStoreOptions;
     private webStore;
@@ -15,16 +15,21 @@ export declare class StatePart<TStatePartName, TStatePayload> {
     /**
      * gets the state from the state store
      */
-    getState(): TStatePayload;
+    getState(): TStatePayload | undefined;
     /**
      * sets the stateStore to the new state
      * @param newStateArg
      */
     setState(newStateArg: TStatePayload): Promise<TStatePayload>;
+    /**
+     * Validates state structure - can be overridden for custom validation
+     * @param stateArg
+     */
+    protected validateState(stateArg: any): stateArg is TStatePayload;
     /**
      * notifies of a change on the state
      */
-    notifyChange(): void;
+    notifyChange(): Promise<void>;
     private lastStateNotificationPayloadHash;
     /**
      * creates a cumulative notification by adding a change notification at the end of the call stack;

package/dist_ts/smartstate.classes.statepart.js

@@ -19,9 +19,9 @@ export class StatePart {
             this.webStore = new plugins.webstore.WebStore(this.webStoreOptions);
             await this.webStore.init();
             const storedState = await this.webStore.get(String(this.name));
-            if (storedState) {
+            if (storedState && this.validateState(storedState)) {
                 this.stateStore = storedState;
-                this.notifyChange();
+                await this.notifyChange();
             }
         }
     }
@@ -36,28 +36,44 @@ export class StatePart {
      * @param newStateArg
      */
     async setState(newStateArg) {
+        // Validate state structure
+        if (!this.validateState(newStateArg)) {
+            throw new Error(`Invalid state structure for state part '${this.name}'`);
+        }
         this.stateStore = newStateArg;
-        this.notifyChange();
+        await this.notifyChange();
         // Save state to WebStore if initialized
         if (this.webStore) {
             await this.webStore.set(String(this.name), newStateArg);
         }
         return this.stateStore;
     }
+    /**
+     * Validates state structure - can be overridden for custom validation
+     * @param stateArg
+     */
+    validateState(stateArg) {
+        // Basic validation - ensure state is not null/undefined
+        // Subclasses can override for more specific validation
+        return stateArg !== null && stateArg !== undefined;
+    }
     /**
      * notifies of a change on the state
      */
-    notifyChange() {
-        const createStateHash = (stateArg) => {
-            return plugins.smarthashWeb.sha256FromString(plugins.smartjson.stringify(stateArg));
+    async notifyChange() {
+        if (!this.stateStore) {
+            return;
+        }
+        const createStateHash = async (stateArg) => {
+            return await plugins.smarthashWeb.sha256FromString(plugins.smartjson.stringify(stateArg));
         };
-        if (this.stateStore &&
-            this.lastStateNotificationPayloadHash &&
-            createStateHash(this.stateStore) === this.lastStateNotificationPayloadHash) {
+        const currentHash = await createStateHash(this.stateStore);
+        if (this.lastStateNotificationPayloadHash &&
+            currentHash === this.lastStateNotificationPayloadHash) {
             return;
         }
         else {
-            this.lastStateNotificationPayloadHash = this.stateStore;
+            this.lastStateNotificationPayloadHash = currentHash;
         }
         this.state.next(this.stateStore);
     }
@@ -66,7 +82,11 @@ export class StatePart {
      */
     notifyChangeCumulative() {
         // TODO: check viability
-        setTimeout(() => this.state.next(this.stateStore), 0);
+        setTimeout(async () => {
+            if (this.stateStore) {
+                await this.notifyChange();
+            }
+        }, 0);
     }
     /**
      * selects a state or a substate
@@ -75,7 +95,7 @@ export class StatePart {
         if (!selectorFn) {
             selectorFn = (state) => state;
         }
-        const mapped = this.state.pipe(plugins.smartrx.rxjs.ops.startWith(this.getState()), plugins.smartrx.rxjs.ops.map((stateArg) => {
+        const mapped = this.state.pipe(plugins.smartrx.rxjs.ops.startWith(this.getState()), plugins.smartrx.rxjs.ops.filter((stateArg) => stateArg !== undefined), plugins.smartrx.rxjs.ops.map((stateArg) => {
             try {
                 return selectorFn(stateArg);
             }
@@ -125,4 +145,4 @@ export class StatePart {
         this.setState(await resultPromise);
     }
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRzdGF0ZS5jbGFzc2VzLnN0YXRlcGFydC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3NtYXJ0c3RhdGUuY2xhc3Nlcy5zdGF0ZXBhcnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSx5QkFBeUIsQ0FBQztBQUNuRCxPQUFPLEVBQUUsV0FBVyxFQUFtQixNQUFNLHFDQUFxQyxDQUFDO0FBRW5GLE1BQU0sT0FBTyxTQUFTO0lBU3BCLFlBQVksT0FBdUIsRUFBRSxrQkFBc0Q7UUFQcEYsVUFBSyxHQUFHLElBQUksT0FBTyxDQUFDLE9BQU8sQ0FBQyxJQUFJLENBQUMsT0FBTyxFQUFpQixDQUFDO1FBRXpELHVCQUFrQixHQUFHLE9BQU8sQ0FBQyxZQUFZLENBQUMsZUFBZSxFQUFFLENBQUM7UUFHNUQsYUFBUSxHQUFvRCxJQUFJLENBQUMsQ0FBQyx3QkFBd0I7UUFHaEcsSUFBSSxDQUFDLElBQUksR0FBRyxPQUFPLENBQUM7UUFFcEIsc0RBQXNEO1FBQ3RELElBQUksa0JBQWtCLEVBQUUsQ0FBQztZQUN2QixJQUFJLENBQUMsZUFBZSxHQUFHLGtCQUFrQixDQUFDO1FBQzVDLENBQUM7SUFDSCxDQUFDO0lBRUQ7O09BRUc7SUFDSSxLQUFLLENBQUMsSUFBSTtRQUNmLElBQUksSUFBSSxDQUFDLGVBQWUsRUFBRSxDQUFDO1lBQ3pCLElBQUksQ0FBQyxRQUFRLEdBQUcsSUFBSSxPQUFPLENBQUMsUUFBUSxDQUFDLFFBQVEsQ0FBZ0IsSUFBSSxDQUFDLGVBQWUsQ0FBQyxDQUFDO1lBQ25GLE1BQU0sSUFBSSxDQUFDLFFBQVEsQ0FBQyxJQUFJLEVBQUUsQ0FBQztZQUMzQixNQUFNLFdBQVcsR0FBRyxNQUFNLElBQUksQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFDLE1BQU0sQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLENBQUMsQ0FBQztZQUMvRCxJQUFJLFdBQVcsRUFBRSxDQUFDO2dCQUNoQixJ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
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRzdGF0ZS5jbGFzc2VzLnN0YXRlcGFydC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3NtYXJ0c3RhdGUuY2xhc3Nlcy5zdGF0ZXBhcnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSx5QkFBeUIsQ0FBQztBQUNuRCxPQUFPLEVBQUUsV0FBVyxFQUFtQixNQUFNLHFDQUFxQyxDQUFDO0FBRW5GLE1BQU0sT0FBTyxTQUFTO0lBU3BCLFlBQVksT0FBdUIsRUFBRSxrQkFBc0Q7UUFQcEYsVUFBSyxHQUFHLElBQUksT0FBTyxDQUFDLE9BQU8sQ0FBQyxJQUFJLENBQUMsT0FBTyxFQUFpQixDQUFDO1FBRXpELHVCQUFrQixHQUFHLE9BQU8sQ0FBQyxZQUFZLENBQUMsZUFBZSxFQUFFLENBQUM7UUFHNUQsYUFBUSxHQUFvRCxJQUFJLENBQUMsQ0FBQyx3QkFBd0I7UUFHaEcsSUFBSSxDQUFDLElBQUksR0FBRyxPQUFPLENBQUM7UUFFcEIsc0RBQXNEO1FBQ3RELElBQUksa0JBQWtCLEVBQUUsQ0FBQztZQUN2QixJQUFJLENBQUMsZUFBZSxHQUFHLGtCQUFrQixDQUFDO1FBQzVDLENBQUM7SUFDSCxDQUFDO0lBRUQ7O09BRUc7SUFDSSxLQUFLLENBQUMsSUFBSTtRQUNmLElBQUksSUFBSSxDQUFDLGVBQWUsRUFBRSxDQUFDO1lBQ3pCLElBQUksQ0FBQyxRQUFRLEdBQUcsSUFBSSxPQUFPLENBQUMsUUFBUSxDQUFDLFFBQVEsQ0FBZ0IsSUFBSSxDQUFDLGVBQWUsQ0FBQyxDQUFDO1lBQ25GLE1BQU0sSUFBSSxDQUFDLFFBQVEsQ0FBQyxJQUFJLEVBQUUsQ0FBQztZQUMzQixNQUFNLFdBQVcsR0FBRyxNQUFNLElBQUksQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFDLE1BQU0sQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLENBQUMsQ0FBQztZQUMvRCxJQUFJLFdBQVcsSUFBSSxJQUFJLENBQUMsYUFB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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartstate",
-  "version": "2.0.23",
+  "version": "2.0.25",
   "private": false,
   "description": "A package for handling and managing state in applications.",
   "main": "dist_ts/index.js",
@@ -8,6 +8,11 @@
   "type": "module",
   "author": "Lossless GmbH",
   "license": "MIT",
+  "scripts": {
+    "test": "(tstest test/ --verbose)",
+    "build": "(tsbuild tsfolders --allowimplicitany && tsbundle npm)",
+    "buildDocs": "tsdoc"
+  },
   "devDependencies": {
     "@git.zone/tsbuild": "^2.6.4",
     "@git.zone/tsbundle": "^2.4.0",
@@ -56,9 +61,5 @@
     "type": "git",
     "url": "https://code.foss.global/push.rocks/smartstate.git"
   },
-  "scripts": {
-    "test": "(tstest test/ --verbose)",
-    "build": "(tsbuild tsfolders --allowimplicitany && tsbundle npm)",
-    "buildDocs": "tsdoc"
-  }
-}
+  "packageManager": "pnpm@10.11.0+sha512.6540583f41cc5f628eb3d9773ecee802f4f9ef9923cc45b69890fb47991d4b092964694ec3a4f738a420c918a333062c8b925d312f42e4f0c263eb603551f977"
+}

package/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

package/readme.md

@@ -1,12 +1,19 @@
 # @push.rocks/smartstate
-A package for handling and managing state in applications
+A powerful TypeScript library for elegant state management using RxJS and reactive programming patterns
 
 ## Install
 
-To install `@push.rocks/smartstate`, you can use pnpm (Performant Node Package Manager). Run the following command in your terminal:
+To install `@push.rocks/smartstate`, you can use pnpm, npm, or yarn:
 
 ```bash
+# Using pnpm (recommended)
 pnpm install @push.rocks/smartstate --save
+
+# Using npm
+npm install @push.rocks/smartstate --save
+
+# Using yarn
+yarn add @push.rocks/smartstate
 ```
 
 This will add `@push.rocks/smartstate` to your project's dependencies.
@@ -35,10 +42,10 @@ const myAppSmartState = new Smartstate<YourStatePartNamesEnum>();
 
 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
+- **`'soft'`** (default) - Returns existing state part if it 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 one
+- **`'persistent'`** - Like 'soft' but with WebStore persistence using IndexedDB
 
 ### Defining State Parts
 
@@ -79,6 +86,7 @@ const userStatePart = await myAppSmartState.getStatePart<IUserState>(
 You can subscribe to changes in a state part to perform actions accordingly:
 
 ```typescript
+// The select() method automatically filters out undefined states
 userStatePart.select().subscribe((currentState) => {
   console.log(`User Logged In: ${currentState.isLoggedIn}`);
 });
@@ -134,6 +142,12 @@ Both methods return a Promise with the new state, giving you flexibility in how
 `StatePart` provides several useful methods for state management:
 
 ```typescript
+// Get current state (may be undefined initially)
+const currentState = userStatePart.getState();
+if (currentState) {
+  console.log('Current user:', currentState.username);
+}
+
 // Wait for a specific state condition
 await userStatePart.waitUntilPresent();
 
@@ -170,13 +184,33 @@ Persistent state automatically:
 - Restores state on application restart
 - Manages storage with configurable database and store names
 
+### State Validation
+
+`Smartstate` includes built-in state validation to ensure data integrity:
+
+```typescript
+// Basic validation (built-in)
+// Ensures state is not null or undefined
+await userStatePart.setState(null); // Throws error: Invalid state structure
+
+// Custom validation by extending StatePart
+class ValidatedStatePart<T> extends StatePart<string, T> {
+  protected validateState(stateArg: any): stateArg is T {
+    // Add your custom validation logic
+    return super.validateState(stateArg) && /* your validation */;
+  }
+}
+```
+
 ### Performance Optimization
 
-`Smartstate` includes built-in performance optimizations:
+`Smartstate` includes advanced performance optimizations:
 
-- **State Change Detection**: Detects actual state changes to prevent unnecessary notifications when state values haven't truly changed
+- **Async State Hash Detection**: Uses SHA256 hashing to detect actual state changes, preventing unnecessary notifications when state values haven't truly changed
+- **Duplicate Prevention**: Identical state updates are automatically filtered out
 - **Cumulative Notifications**: Batch multiple state changes into a single notification using `notifyChangeCumulative()`
 - **Selective Subscriptions**: Use selectors to subscribe only to specific state properties
+- **Undefined State Filtering**: The `select()` method automatically filters out undefined states
 
 ### RxJS Integration
 
@@ -202,19 +236,75 @@ userStatePart.select(state => state.username)
   });
 ```
 
-### Comprehensive Usage
+### Complete Example
+
+Here's a comprehensive example showcasing the power of `@push.rocks/smartstate`:
+
+```typescript
+import { Smartstate, StatePart, StateAction } from '@push.rocks/smartstate';
+
+// Define your state structure
+type AppStateParts = 'user' | 'settings' | 'cart';
+
+interface IUserState {
+  isLoggedIn: boolean;
+  username?: string;
+  email?: string;
+}
+
+interface ICartState {
+  items: Array<{ id: string; quantity: number }>;
+  total: number;
+}
+
+// Create the smartstate instance
+const appState = new Smartstate<AppStateParts>();
+
+// Initialize state parts
+const userState = await appState.getStatePart<IUserState>('user', {
+  isLoggedIn: false
+});
+
+const cartState = await appState.getStatePart<ICartState>('cart', {
+  items: [],
+  total: 0
+}, 'persistent'); // Persists across sessions
+
+// Create actions
+const loginAction = userState.createAction<{ username: string; email: string }>(
+  async (statePart, payload) => {
+    // Simulate API call
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    
+    return {
+      isLoggedIn: true,
+      username: payload.username,
+      email: payload.email
+    };
+  }
+);
+
+// Subscribe to changes
+userState.select(state => state.isLoggedIn).subscribe(isLoggedIn => {
+  console.log('Login status changed:', isLoggedIn);
+});
+
+// Dispatch actions
+await loginAction.trigger({ username: 'john', email: 'john@example.com' });
+```
 
-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.
+### Key Features
 
-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
+`@push.rocks/smartstate` provides a robust foundation for state management:
 
-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.
+- **🎯 Type-safe** - Full TypeScript support with intelligent type inference
+- **⚡ Performance optimized** - Async state hash detection prevents unnecessary re-renders
+- **💾 Persistent state** - Built-in IndexedDB support for state persistence
+- **🔄 Reactive** - Powered by RxJS for elegant async handling
+- **🧩 Modular** - Organize state into logical, reusable parts
+- **✅ Validated** - Built-in state validation with extensible validation logic
+- **🎭 Flexible init modes** - Choose how state parts are initialized
+- **📦 Zero config** - Works out of the box with sensible defaults
 
 ## License and Legal Information
 

package/ts/smartstate.classes.smartstate.ts

@@ -13,9 +13,10 @@ export class Smartstate<StatePartNameType extends string> {
 
   /**
    * Allows getting and initializing a new statepart
-   * initMode === 'soft' it will allow existing stateparts
-   * initMode === 'mandatory' will fail if there is an existing statepart
-   * initMode === 'force' will overwrite any existing statepart
+   * initMode === 'soft' (default) - returns existing statepart if exists, creates new if not
+   * initMode === 'mandatory' - requires statepart to not exist, fails if it does
+   * initMode === 'force' - always creates new statepart, overwriting any existing
+   * initMode === 'persistent' - like 'soft' but with webstore persistence
    * @param statePartNameArg
    * @param initialArg
    * @param initMode
@@ -23,19 +24,30 @@ export class Smartstate<StatePartNameType extends string> {
   public async getStatePart<PayloadType>(
     statePartNameArg: StatePartNameType,
     initialArg?: PayloadType,
-    initMode?: TInitMode
+    initMode: TInitMode = 'soft'
   ): Promise<StatePart<StatePartNameType, PayloadType>> {
-    if (this.statePartMap[statePartNameArg]) {
-      if (initialArg && (!initMode || initMode !== 'soft')) {
-        throw new Error(
-          `${statePartNameArg} already exists, yet you try to set an initial state again`
-        );
+    const existingStatePart = this.statePartMap[statePartNameArg];
+    
+    if (existingStatePart) {
+      switch (initMode) {
+        case 'mandatory':
+          throw new Error(
+            `State part '${statePartNameArg}' already exists, but initMode is 'mandatory'`
+          );
+        case 'force':
+          // Force mode: create new state part
+          return this.createStatePart<PayloadType>(statePartNameArg, initialArg, initMode);
+        case 'soft':
+        case 'persistent':
+        default:
+          // Return existing state part
+          return existingStatePart as StatePart<StatePartNameType, PayloadType>;
       }
-      return this.statePartMap[statePartNameArg] as StatePart<StatePartNameType, PayloadType>;
     } else {
+      // State part doesn't exist
       if (!initialArg) {
         throw new Error(
-          `${statePartNameArg} does not yet exist, yet you don't provide an initial state`
+          `State part '${statePartNameArg}' does not exist and no initial state provided`
         );
       }
       return this.createStatePart<PayloadType>(statePartNameArg, initialArg, initMode);
@@ -46,11 +58,12 @@ export class Smartstate<StatePartNameType extends string> {
    * Creates a statepart
    * @param statePartName
    * @param initialPayloadArg
+   * @param initMode
    */
   private async createStatePart<PayloadType>(
     statePartName: StatePartNameType,
     initialPayloadArg: PayloadType,
-    initMode?: TInitMode
+    initMode: TInitMode = 'soft'
   ): Promise<StatePart<StatePartNameType, PayloadType>> {
     const newState = new StatePart<StatePartNameType, PayloadType>(
       statePartName,
@@ -64,8 +77,8 @@ export class Smartstate<StatePartNameType extends string> {
     await newState.init();
     const currentState = newState.getState();
     await newState.setState({
-      ...initialPayloadArg,
       ...currentState,
+      ...initialPayloadArg,
     });
     this.statePartMap[statePartName] = newState;
     return newState;