@push.rocks/smartstate 2.2.1 → 2.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartstate",
-  "version": "2.2.1",
+  "version": "2.3.1",
   "private": false,
   "description": "A TypeScript-first reactive state management library with middleware, computed state, batching, persistence, and Web Component Context Protocol support.",
   "main": "dist_ts/index.js",
@@ -10,23 +10,22 @@
   "license": "MIT",
   "scripts": {
     "test": "(tstest test/ --verbose)",
-    "build": "(tsbuild tsfolders --allowimplicitany && tsbundle npm)",
+    "build": "(tsbuild tsfolders && tsbundle npm)",
     "buildDocs": "tsdoc"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.1.2",
-    "@git.zone/tsbundle": "^2.9.0",
-    "@git.zone/tsrun": "^2.0.1",
-    "@git.zone/tstest": "^3.1.8",
-    "@push.rocks/tapbundle": "^6.0.3",
-    "@types/node": "^25.3.2"
+    "@git.zone/tsbuild": "^4.4.0",
+    "@git.zone/tsbundle": "^2.10.0",
+    "@git.zone/tsrun": "^2.0.2",
+    "@git.zone/tstest": "^3.6.3",
+    "@types/node": "^25.6.0"
   },
   "dependencies": {
-    "@push.rocks/smarthash": "^3.2.6",
-    "@push.rocks/smartjson": "^6.0.0",
+    "@push.rocks/smarthash": "^3.2.7",
+    "@push.rocks/smartjson": "^6.0.1",
     "@push.rocks/smartpromise": "^4.2.3",
     "@push.rocks/smartrx": "^3.0.10",
-    "@push.rocks/webstore": "^2.0.20"
+    "@push.rocks/webstore": "^2.0.21"
   },
   "files": [
     "ts/**/*",
@@ -37,7 +36,8 @@
     "dist_ts_web/**/*",
     "assets/**/*",
     "cli.js",
-    "npmextra.json",
+    ".smartconfig.json",
+    "license",
     "readme.md"
   ],
   "browserslist": [
@@ -66,5 +66,5 @@
     "type": "git",
     "url": "https://code.foss.global/push.rocks/smartstate.git"
   },
-  "packageManager": "pnpm@10.11.0+sha512.6540583f41cc5f628eb3d9773ecee802f4f9ef9923cc45b69890fb47991d4b092964694ec3a4f738a420c918a333062c8b925d312f42e4f0c263eb603551f977"
+  "packageManager": "pnpm@10.28.2"
 }

package/readme.md

@@ -1,6 +1,6 @@
 # @push.rocks/smartstate
 
-A TypeScript-first reactive state management library with middleware, computed state, batching, persistence, and Web Component Context Protocol support 🚀
+A TypeScript-first reactive state management library with processes, middleware, computed state, batching, persistence, and Web Component Context Protocol support 🚀
 
 ## Issue Reporting and Security
 
@@ -48,7 +48,7 @@ await userState.setState({ name: 'Alice', loggedIn: true });
 
 ### 🧩 State Parts & Init Modes
 
-State parts are isolated, typed units of state. They are the building blocks of your application's state tree. Create them via `getStatePart()`:
+State parts are isolated, typed units of state — the building blocks of your application's state tree. Create them via `getStatePart()`:
 
 ```typescript
 const part = await state.getStatePart<IMyState>(name, initialState, initMode);
@@ -58,10 +58,10 @@ const part = await state.getStatePart<IMyState>(name, initialState, initMode);
 |-----------|----------|
 | `'soft'` (default) | Returns existing if found, creates new otherwise |
 | `'mandatory'` | Throws if state part already exists — useful for ensuring single-initialization |
-| `'force'` | Always creates a new state part, overwriting any existing one |
+| `'force'` | Always creates a new state part, disposing and overwriting any existing one |
 | `'persistent'` | Like `'soft'` but automatically persists state to IndexedDB via WebStore |
 
-You can use either enums or string literal types for state part names:
+You can use either string literal union types or enums for state part names:
 
 ```typescript
 // String literal types (simpler)
@@ -82,12 +82,12 @@ const settings = await state.getStatePart('settings', { theme: 'dark', fontSize:
 
 // ✅ Automatically saved to IndexedDB on every setState()
 // ✅ On next app load, persisted values override defaults
-// ✅ Persistence writes complete before in-memory updates (atomic)
+// ✅ Persistence writes complete before in-memory updates
 ```
 
 ### 🔭 Selecting State
 
-`select()` returns an RxJS Observable that emits the current value immediately and on every subsequent change:
+`select()` returns an RxJS Observable that emits the current value immediately (via `BehaviorSubject`) and on every subsequent change:
 
 ```typescript
 // Full state
@@ -99,6 +99,8 @@ userState.select((s) => s.name).subscribe((name) => console.log(name));
 
 Selectors are **memoized** — calling `select(fn)` with the same function reference returns the same cached Observable, shared across all subscribers via `shareReplay`. This means you can call `select(mySelector)` in multiple places without creating duplicate subscriptions.
 
+**Change detection** is built in: `select()` uses `distinctUntilChanged` with deep JSON comparison, so subscribers only fire when the selected value actually changes. Selecting `s => s.name` won't re-emit when only `s.count` changes.
+
 #### ✂️ AbortSignal Support
 
 Clean up subscriptions without manual `.unsubscribe()` — the modern way:
@@ -125,7 +127,6 @@ interface ILoginPayload {
 }
 
 const loginAction = userState.createAction<ILoginPayload>(async (statePart, payload) => {
-  // You have access to the current state via statePart.getState()
   const current = statePart.getState();
   return { ...current, name: payload.username, loggedIn: true };
 });
@@ -136,7 +137,157 @@ await loginAction.trigger({ username: 'Alice', email: 'alice@example.com' });
 await userState.dispatchAction(loginAction, { username: 'Alice', email: 'alice@example.com' });
 ```
 
-Both `trigger()` and `dispatchAction()` return a Promise with the new state.
+Both `trigger()` and `dispatchAction()` return a Promise with the new state. All dispatches are serialized through a mutation queue, so concurrent dispatches never cause lost updates.
+
+#### 🔗 Nested Actions (Action Context)
+
+When you need to dispatch sub-actions from within an action, use the `context` parameter. This is critical because calling `dispatchAction()` directly from inside an action would deadlock (it tries to acquire the mutation queue that's already held). The context's `dispatch()` bypasses the queue and executes inline:
+
+```typescript
+const incrementAction = userState.createAction<number>(async (statePart, amount) => {
+  const current = statePart.getState();
+  return { ...current, count: current.count + amount };
+});
+
+const doubleIncrementAction = userState.createAction<number>(async (statePart, amount, context) => {
+  // ✅ Safe: uses context.dispatch() which bypasses the mutation queue
+  await context.dispatch(incrementAction, amount);
+  const current = statePart.getState();
+  return { ...current, count: current.count + amount };
+});
+
+// ❌ DON'T do this inside an action — it will deadlock:
+// await statePart.dispatchAction(someAction, payload);
+```
+
+A built-in depth limit (10 levels) prevents infinite circular dispatch chains, throwing a clear error if exceeded.
+
+### 🔄 Processes (Polling, Streams & Scheduled Tasks)
+
+Processes are managed, pausable observable-to-state bridges — the "side effects" layer. They tie an ongoing data source (polling, WebSockets, event streams) to state updates with full lifecycle control and optional auto-pause.
+
+#### Basic Process: Polling an API
+
+```typescript
+import { interval, switchMap, from } from 'rxjs';
+
+const metricsPoller = dashboard.createProcess<{ cpu: number; memory: number }>({
+  // Producer: an Observable factory — called on start and each resume
+  producer: () => interval(5000).pipe(
+    switchMap(() => from(fetch('/api/metrics').then(r => r.json()))),
+  ),
+  // Reducer: folds each produced value into state (runs through middleware & validation)
+  reducer: (currentState, metrics) => ({
+    ...currentState,
+    metrics,
+    lastUpdated: Date.now(),
+  }),
+  autoPause: 'visibility',  // ⏸️ Stop polling when the tab is hidden
+  autoStart: true,           // ▶️ Start immediately
+});
+
+// Full lifecycle control
+metricsPoller.pause();    // Unsubscribes from producer
+metricsPoller.resume();   // Re-subscribes (fresh subscription)
+metricsPoller.dispose();  // Permanent cleanup
+
+// Observe status reactively
+metricsPoller.status;     // 'idle' | 'running' | 'paused' | 'disposed'
+metricsPoller.status$.subscribe(s => console.log('Process:', s));
+```
+
+#### Scheduled Actions
+
+Dispatch an existing action on a recurring interval — syntactic sugar over `createProcess`:
+
+```typescript
+const refreshAction = dashboard.createAction<void>(async (sp) => {
+  const data = await fetch('/api/dashboard').then(r => r.json());
+  return { ...sp.getState()!, ...data, lastUpdated: Date.now() };
+});
+
+// Dispatches refreshAction every 30 seconds, auto-pauses when tab is hidden
+const scheduled = dashboard.createScheduledAction({
+  action: refreshAction,
+  payload: undefined,
+  intervalMs: 30000,
+  autoPause: 'visibility',
+});
+
+// It's a full StateProcess — pause, resume, dispose all work
+scheduled.dispose();
+```
+
+#### Custom Auto-Pause Signals
+
+Pass any `Observable<boolean>` as the auto-pause signal — `true` means active, `false` means pause:
+
+```typescript
+import { fromEvent, map, startWith } from 'rxjs';
+
+// Pause when offline, resume when online
+const onlineSignal = fromEvent(window, 'online').pipe(
+  startWith(null),
+  map(() => navigator.onLine),
+);
+
+const syncProcess = userPart.createProcess<SyncPayload>({
+  producer: () => interval(10000).pipe(
+    switchMap(() => from(syncWithServer())),
+  ),
+  reducer: (state, result) => ({ ...state, ...result }),
+  autoPause: onlineSignal,
+});
+syncProcess.start();
+```
+
+#### WebSocket / Live Streams
+
+Pause disconnects; resume creates a fresh connection:
+
+```typescript
+const liveProcess = tickerPart.createProcess<TradeEvent>({
+  producer: () => new Observable<TradeEvent>(subscriber => {
+    const ws = new WebSocket('wss://trades.example.com');
+    ws.onmessage = (e) => subscriber.next(JSON.parse(e.data));
+    ws.onerror = (e) => subscriber.error(e);
+    ws.onclose = () => subscriber.complete();
+    return () => ws.close();  // Teardown: close WebSocket on unsubscribe
+  }),
+  reducer: (state, trade) => ({
+    ...state,
+    lastPrice: trade.price,
+    trades: [...state.trades.slice(-99), trade],
+  }),
+  autoPause: 'visibility',
+});
+liveProcess.start();
+```
+
+#### Error Recovery
+
+If a producer errors, the process gracefully transitions to `'paused'` instead of dying. Call `resume()` to retry with a fresh subscription:
+
+```typescript
+process.start();
+// Producer errors → status becomes 'paused'
+process.resume(); // Creates a fresh subscription — retry
+```
+
+#### Process Cleanup Cascades
+
+Disposing a `StatePart` or `Smartstate` instance automatically disposes all attached processes:
+
+```typescript
+const p1 = part.createProcess({ ... });
+const p2 = part.createProcess({ ... });
+p1.start();
+p2.start();
+
+part.dispose();
+console.log(p1.status); // 'disposed'
+console.log(p2.status); // 'disposed'
+```
 
 ### 🛡️ Middleware
 
@@ -171,7 +322,7 @@ const remove = userState.addMiddleware(myMiddleware);
 remove(); // middleware no longer runs
 ```
 
-Middleware runs **sequentially** in insertion order. If any middleware throws, the state remains unchanged — the operation is **atomic**.
+Middleware runs **sequentially** in insertion order. If any middleware throws, the state remains unchanged — the operation is **atomic**. Process-driven state updates go through middleware too.
 
 ### 🧮 Computed / Derived State
 
@@ -199,7 +350,7 @@ const greeting2$ = state.computed(
 );
 ```
 
-Computed observables are **lazy** — they only subscribe to their sources when someone subscribes to them, and they automatically unsubscribe when all subscribers disconnect.
+Computed observables are **lazy** — they only subscribe to their sources when someone subscribes to them, and they automatically unsubscribe when all subscribers disconnect. They also use `distinctUntilChanged` to avoid redundant emissions when the derived value hasn't actually changed.
 
 ### 📦 Batch Updates
 
@@ -322,15 +473,31 @@ await userState.stateSetup(async (statePart) => {
 // Any dispatchAction() calls will automatically wait for stateSetup() to finish
 ```
 
+### 🧹 Disposal & Cleanup
+
+Both `Smartstate` and individual `StatePart` instances support disposal for proper cleanup:
+
+```typescript
+// Dispose a single state part — completes the BehaviorSubject, clears middleware, caches,
+// and disposes all attached processes
+userState.dispose();
+
+// Dispose the entire Smartstate instance — disposes all state parts and clears internal maps
+state.dispose();
+```
+
+After disposal, `setState()` and `dispatchAction()` will throw if called on a disposed `StatePart`. Calling `start()`, `pause()`, or `resume()` on a disposed `StateProcess` also throws.
+
 ### 🏎️ Performance
 
 Smartstate is built with performance in mind:
 
 - **🔒 SHA256 Change Detection** — Uses content hashing to detect actual changes. Identical state values don't trigger notifications, even with different object references.
+- **🎯 distinctUntilChanged on Selectors** — Sub-selectors only fire when the selected slice actually changes. `select(s => s.name)` won't emit when `s.count` changes.
 - **♻️ Selector Memoization** — `select(fn)` caches observables by function reference and shares them via `shareReplay({ refCount: true })`. Multiple subscribers share one upstream subscription.
 - **📦 Cumulative Notifications** — `notifyChangeCumulative()` debounces rapid changes into a single notification at the end of the call stack.
-- **🔐 Concurrent Safety** — Simultaneous `getStatePart()` calls for the same name return the same promise, preventing duplicate creation or race conditions.
-- **💾 Atomic Persistence** — WebStore writes complete before in-memory state updates, ensuring consistency even if the process crashes mid-write.
+- **🔐 Concurrent Safety** — Simultaneous `getStatePart()` calls for the same name return the same promise, preventing duplicate creation. All `setState()` and `dispatchAction()` calls are serialized through a mutation queue. Process values are serialized through their own internal queue.
+- **💾 Atomic Persistence** — WebStore writes complete before in-memory state updates, ensuring consistency.
 - **⏸️ Batch Deferred Notifications** — `batch()` suppresses all subscriber notifications until every update in the batch completes.
 
 ## API Reference
@@ -342,23 +509,26 @@ Smartstate is built with performance in mind:
 | `getStatePart(name, initial?, initMode?)` | Get or create a typed state part |
 | `batch(fn)` | Batch state updates, defer all notifications until complete |
 | `computed(sources, fn)` | Create a computed observable from multiple state parts |
+| `dispose()` | Dispose all state parts and clear internal state |
 | `isBatching` | `boolean` — whether a batch is currently active |
-| `statePartMap` | Registry of all created state parts |
 
 ### `StatePart<TName, TPayload>`
 
 | Method | Description |
 |--------|-------------|
-| `getState()` | Get current state (returns `TPayload \| undefined`) |
+| `getState()` | Get current state synchronously (`TPayload \| undefined`) |
 | `setState(newState)` | Set state — runs middleware → validates → persists → notifies |
-| `select(selectorFn?, options?)` | Returns an Observable of state or derived values. Options: `{ signal?: AbortSignal }` |
+| `select(selectorFn?, options?)` | Observable of state or derived values. Options: `{ signal?: AbortSignal }` |
 | `createAction(actionDef)` | Create a reusable, typed state action |
 | `dispatchAction(action, payload)` | Dispatch an action and return the new state |
 | `addMiddleware(fn)` | Add a middleware interceptor. Returns a removal function |
 | `waitUntilPresent(selectorFn?, opts?)` | Wait for a state condition. Opts: `number` (timeout) or `{ timeoutMs?, signal? }` |
+| `createProcess(options)` | Create a managed, pausable process tied to this state part |
+| `createScheduledAction(options)` | Create a process that dispatches an action on a recurring interval |
 | `notifyChange()` | Manually trigger a change notification (with hash dedup) |
 | `notifyChangeCumulative()` | Debounced notification — fires at end of call stack |
 | `stateSetup(fn)` | Async state initialization with action serialization |
+| `dispose()` | Complete the BehaviorSubject, dispose processes, clear middleware and caches |
 
 ### `StateAction<TState, TPayload>`
 
@@ -366,6 +536,23 @@ Smartstate is built with performance in mind:
 |--------|-------------|
 | `trigger(payload)` | Dispatch the action on its associated state part |
 
+### `StateProcess<TName, TPayload, TProducerValue>`
+
+| Method / Property | Description |
+|-------------------|-------------|
+| `start()` | Start the process (subscribes to producer, sets up auto-pause) |
+| `pause()` | Pause the process (unsubscribes from producer) |
+| `resume()` | Resume a paused process (fresh subscription to producer) |
+| `dispose()` | Permanently stop the process and clean up |
+| `status` | Current status: `'idle' \| 'running' \| 'paused' \| 'disposed'` |
+| `status$` | Observable of status transitions |
+
+### `IActionContext<TState>`
+
+| Method | Description |
+|--------|-------------|
+| `dispatch(action, payload)` | Dispatch a sub-action inline (bypasses mutation queue). Available as the third argument to action definitions |
+
 ### Standalone Functions
 
 | Function | Description |
@@ -379,8 +566,13 @@ Smartstate is built with performance in mind:
 |------|-------------|
 | `TInitMode` | `'soft' \| 'mandatory' \| 'force' \| 'persistent'` |
 | `TMiddleware<TPayload>` | `(newState, oldState) => TPayload \| Promise<TPayload>` |
-| `IActionDef<TState, TPayload>` | Action definition function signature |
+| `IActionDef<TState, TPayload>` | Action definition function signature (receives statePart, payload, context?) |
+| `IActionContext<TState>` | Context for safe nested dispatch within actions |
 | `IContextProviderOptions<TPayload>` | Options for `attachContextProvider` |
+| `IProcessOptions<TPayload, TValue>` | Options for `createProcess` (producer, reducer, autoPause, autoStart) |
+| `IScheduledActionOptions<TPayload, TActionPayload>` | Options for `createScheduledAction` (action, payload, intervalMs, autoPause) |
+| `TProcessStatus` | `'idle' \| 'running' \| 'paused' \| 'disposed'` |
+| `TAutoPause` | `'visibility' \| Observable<boolean> \| false` |
 
 ## License and Legal Information
 
@@ -396,7 +588,7 @@ Use of these trademarks must comply with Task Venture Capital GmbH's Trademark G
 
 ### Company Information
 
-Task Venture Capital GmbH  
+Task Venture Capital GmbH
 Registered at District Court Bremen HRB 35230 HB, Germany
 
 For any legal inquiries or further information, please contact us via email at hello@task.vc.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartstate',
-  version: '2.2.1',
+  version: '2.3.1',
   description: 'A TypeScript-first reactive state management library with middleware, computed state, batching, persistence, and Web Component Context Protocol support.'
 }

package/ts/index.ts

@@ -3,3 +3,4 @@ export * from './smartstate.classes.statepart.js';
 export * from './smartstate.classes.stateaction.js';
 export * from './smartstate.classes.computed.js';
 export * from './smartstate.contextprovider.js';
+export * from './smartstate.classes.stateprocess.js';

package/ts/smartstate.classes.computed.ts

@@ -1,5 +1,5 @@
 import * as plugins from './smartstate.plugins.js';
-import { combineLatest, map } from 'rxjs';
+import { combineLatest, map, distinctUntilChanged } from 'rxjs';
 import type { StatePart } from './smartstate.classes.statepart.js';
 
 /**
@@ -12,5 +12,6 @@ export function computed<TResult>(
 ): plugins.smartrx.rxjs.Observable<TResult> {
   return combineLatest(sources.map((sp) => sp.select())).pipe(
     map((states) => computeFn(...states)),
+    distinctUntilChanged((a, b) => JSON.stringify(a) === JSON.stringify(b)),
   ) as plugins.smartrx.rxjs.Observable<TResult>;
 }

package/ts/smartstate.classes.smartstate.ts

@@ -49,7 +49,11 @@ export class Smartstate<StatePartNameType extends string> {
             const pending = [...this.pendingNotifications];
             this.pendingNotifications.clear();
             for (const sp of pending) {
-              await sp.notifyChange();
+              try {
+                await sp.notifyChange();
+              } catch (err) {
+                console.error(`Error flushing notification for state part:`, err);
+              }
             }
           }
         } finally {
@@ -69,6 +73,21 @@ export class Smartstate<StatePartNameType extends string> {
     return computed(sources, computeFn);
   }
 
+  /**
+   * disposes all state parts and clears internal state
+   */
+  public dispose(): void {
+    for (const key of Object.keys(this.statePartMap)) {
+      const part = this.statePartMap[key as StatePartNameType];
+      if (part) {
+        part.dispose();
+      }
+    }
+    this.statePartMap = {} as any;
+    this.pendingStatePartCreation.clear();
+    this.pendingNotifications.clear();
+  }
+
   /**
    * Allows getting and initializing a new statepart
    */
@@ -107,7 +126,7 @@ export class Smartstate<StatePartNameType extends string> {
       }
     }
 
-    const creationPromise = this.createStatePart<PayloadType>(statePartNameArg, initialArg, initMode);
+    const creationPromise = this.createStatePart<PayloadType>(statePartNameArg, initialArg!, initMode);
     this.pendingStatePartCreation.set(statePartNameArg, creationPromise);
 
     try {
@@ -133,7 +152,7 @@ export class Smartstate<StatePartNameType extends string> {
             dbName: 'smartstate',
             storeName: statePartName,
           }
-        : null
+        : undefined
     );
     newState.smartstateRef = this;
     await newState.init();

package/ts/smartstate.classes.stateaction.ts

@@ -10,7 +10,7 @@ export interface IActionContext<TStateType> {
 }
 
 export interface IActionDef<TStateType, TActionPayloadType> {
-  (stateArg: StatePart<any, TStateType>, actionPayload: TActionPayloadType, context?: IActionContext<TStateType>): Promise<TStateType>;
+  (stateArg: StatePart<any, TStateType>, actionPayload: TActionPayloadType, context: IActionContext<TStateType>): Promise<TStateType>;
 }
 
 /**
@@ -18,8 +18,8 @@ export interface IActionDef<TStateType, TActionPayloadType> {
  */
 export class StateAction<TStateType, TActionPayloadType> {
   constructor(
-    public statePartRef: StatePart<any, any>,
-    public actionDef: IActionDef<TStateType, TActionPayloadType>
+    public readonly statePartRef: StatePart<any, any>,
+    public readonly actionDef: IActionDef<TStateType, TActionPayloadType>
   ) {}
 
   public trigger(payload: TActionPayloadType): Promise<TStateType> {