@push.rocks/smartstate 2.0.31 → 2.1.1

package/readme.md

@@ -1,6 +1,6 @@
 # @push.rocks/smartstate
 
-A powerful TypeScript library for elegant state management using RxJS and reactive programming patterns 🚀
+A TypeScript-first reactive state management library with middleware, computed state, batching, persistence, and Web Component Context Protocol support 🚀
 
 ## Issue Reporting and Security
 
@@ -8,310 +8,383 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 
 ## Install
 
-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
+Or with npm:
 
-# Using yarn
-yarn add @push.rocks/smartstate
+```bash
+npm install @push.rocks/smartstate --save
 ```
 
 ## Usage
 
-The `@push.rocks/smartstate` library provides an elegant way to handle state within your JavaScript or TypeScript projects, leveraging the power of Reactive Extensions (RxJS) and a structured state management strategy.
+### Quick Start
 
-### Getting Started
+```typescript
+import { Smartstate } from '@push.rocks/smartstate';
 
-Import the necessary components from the library:
+// 1. Define your state part names
+type AppParts = 'user' | 'settings';
 
-```typescript
-import { Smartstate, StatePart, StateAction } from '@push.rocks/smartstate';
-```
+// 2. Create the root instance
+const state = new Smartstate<AppParts>();
 
-### Creating a SmartState Instance
+// 3. Create state parts with initial values
+const userState = await state.getStatePart<{ name: string; loggedIn: boolean }>('user', {
+  name: '',
+  loggedIn: false,
+});
 
-`Smartstate` acts as the container for your state parts. Think of it as the root of your state management structure:
+// 4. Subscribe to changes
+userState.select((s) => s.name).subscribe((name) => {
+  console.log('Name changed:', name);
+});
 
-```typescript
-const myAppSmartState = new Smartstate<YourStatePartNamesEnum>();
+// 5. Update state
+await userState.setState({ name: 'Alice', loggedIn: true });
 ```
 
-### Understanding Init Modes
+### 🧩 State Parts & Init Modes
 
-When creating state parts, you can specify different initialization modes:
+State parts are isolated, typed units of state. They are the building blocks of your application's state tree. Create them via `getStatePart()`:
 
-| Mode | Description |
-|------|-------------|
-| `'soft'` | Default. Returns existing state part if it exists, creates new if not |
-| `'mandatory'` | Requires state part to not exist, throws error if it does |
-| `'force'` | Always creates new state part, overwriting any existing one |
-| `'persistent'` | Like 'soft' but with WebStore persistence using IndexedDB |
+```typescript
+const part = await state.getStatePart<IMyState>(name, initialState, initMode);
+```
 
-### Defining State Parts
+| Init Mode | Behavior |
+|-----------|----------|
+| `'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 |
+| `'persistent'` | Like `'soft'` but automatically persists state to IndexedDB via WebStore |
 
-State parts represent separable sections of your state, making it easier to manage and modularize. Define state part names using either enums or string literal types:
+You can use either enums or string literal types for state part names:
 
 ```typescript
-// Option 1: Using enums
-enum AppStateParts {
-  UserState = 'UserState',
-  SettingsState = 'SettingsState'
+// String literal types (simpler)
+type AppParts = 'user' | 'settings' | 'cart';
+
+// Enums (more explicit)
+enum AppParts {
+  User = 'user',
+  Settings = 'settings',
+  Cart = 'cart',
 }
-
-// Option 2: Using string literal types (simpler approach)
-type AppStateParts = 'UserState' | 'SettingsState';
 ```
 
-Create a state part within your `Smartstate` instance:
+#### 💾 Persistent State
 
 ```typescript
-interface IUserState {
-  isLoggedIn: boolean;
-  username?: string;
-}
+const settings = await state.getStatePart('settings', { theme: 'dark', fontSize: 14 }, 'persistent');
 
-const userStatePart = await myAppSmartState.getStatePart<IUserState>(
-  AppStateParts.UserState,
-  { isLoggedIn: false }, // Initial state
-  'soft' // Init mode (optional, defaults to 'soft')
-);
+// ✅ Automatically saved to IndexedDB on every setState()
+// ✅ On next app load, persisted values override defaults
+// ✅ Persistence writes complete before in-memory updates (atomic)
 ```
 
-### Subscribing to State Changes
+### 🔭 Selecting State
 
-Subscribe to changes in a state part to perform actions accordingly:
+`select()` returns an RxJS Observable that emits the current value immediately and on every subsequent change:
 
 ```typescript
-// The select() method automatically filters out undefined states
-userStatePart.select().subscribe((currentState) => {
-  console.log(`User Logged In: ${currentState.isLoggedIn}`);
-});
+// Full state
+userState.select().subscribe((state) => console.log(state));
+
+// Derived value via selector function
+userState.select((s) => s.name).subscribe((name) => console.log(name));
 ```
 
-Select a specific part of your state with a selector function:
+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.
+
+#### ✂️ AbortSignal Support
+
+Clean up subscriptions without manual `.unsubscribe()` — the modern way:
 
 ```typescript
-userStatePart.select(state => state.username).subscribe((username) => {
-  if (username) {
-    console.log(`Current user: ${username}`);
-  }
+const controller = new AbortController();
+
+userState.select((s) => s.name, { signal: controller.signal }).subscribe((name) => {
+  console.log(name); // automatically stops receiving when aborted
 });
+
+// Later: clean up all subscriptions tied to this signal
+controller.abort();
 ```
 
-### Modifying State with Actions
+### ⚡ Actions
 
-Create actions to modify the state in a controlled manner:
+Actions provide controlled, named state mutations with full async support:
 
 ```typescript
 interface ILoginPayload {
   username: string;
+  email: string;
 }
 
-const loginUserAction = userStatePart.createAction<ILoginPayload>(async (statePart, payload) => {
-  return { ...statePart.getState(), isLoggedIn: true, username: payload.username };
+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 };
 });
 
-// Dispatch the action to update the state
-const newState = await loginUserAction.trigger({ username: 'johnDoe' });
+// Two equivalent ways to dispatch:
+await loginAction.trigger({ username: 'Alice', email: 'alice@example.com' });
+// or
+await userState.dispatchAction(loginAction, { username: 'Alice', email: 'alice@example.com' });
 ```
 
-### Dispatching Actions
+Both `trigger()` and `dispatchAction()` return a Promise with the new state.
 
-There are two ways to dispatch actions:
+### 🛡️ Middleware
+
+Intercept every `setState()` call to transform, validate, log, or reject state changes:
 
 ```typescript
-// Method 1: Using trigger on the action (returns promise)
-const newState = await loginUserAction.trigger({ username: 'johnDoe' });
+// Logging middleware
+userState.addMiddleware((newState, oldState) => {
+  console.log('State changing:', oldState, '→', newState);
+  return newState;
+});
+
+// Validation middleware — throw to reject the change
+userState.addMiddleware((newState) => {
+  if (!newState.name) throw new Error('Name is required');
+  return newState;
+});
+
+// Transform middleware
+userState.addMiddleware((newState) => {
+  return { ...newState, name: newState.name.trim() };
+});
+
+// Async middleware
+userState.addMiddleware(async (newState, oldState) => {
+  await auditLog('state-change', { from: oldState, to: newState });
+  return newState;
+});
 
-// Method 2: Using dispatchAction on the state part (returns promise)
-const newState = await userStatePart.dispatchAction(loginUserAction, { username: 'johnDoe' });
+// Removal — addMiddleware() returns a dispose function
+const remove = userState.addMiddleware(myMiddleware);
+remove(); // middleware no longer runs
 ```
 
-Both methods return a Promise with the new state payload.
+Middleware runs **sequentially** in insertion order. If any middleware throws, the state remains unchanged — the operation is **atomic**.
 
-### Additional State Methods
+### 🧮 Computed / Derived State
 
-`StatePart` provides several useful methods for state management:
+Derive reactive values from one or more state parts using `combineLatest` under the hood:
 
 ```typescript
-// Get current state (may be undefined initially)
-const currentState = userStatePart.getState();
-if (currentState) {
-  console.log('Current user:', currentState.username);
-}
-
-// Wait for state to be present
-await userStatePart.waitUntilPresent();
+import { computed } from '@push.rocks/smartstate';
 
-// Wait for a specific property to be present
-await userStatePart.waitUntilPresent(state => state.username);
+const userState = await state.getStatePart('user', { firstName: 'Jane', lastName: 'Doe' });
+const settingsState = await state.getStatePart('settings', { locale: 'en' });
 
-// Wait with a timeout (throws error if condition not met within timeout)
-try {
-  await userStatePart.waitUntilPresent(state => state.username, 5000); // 5 second timeout
-} catch (error) {
-  console.error('Timed out waiting for username');
-}
+// Standalone function
+const greeting$ = computed(
+  [userState, settingsState],
+  (user, settings) => `Hello, ${user.firstName} (${settings.locale})`,
+);
 
-// Setup initial state with async operations
-await userStatePart.stateSetup(async (statePart) => {
-  const userData = await fetchUserData();
-  return { ...statePart.getState(), ...userData };
-});
+greeting$.subscribe((msg) => console.log(msg));
+// => "Hello, Jane (en)"
 
-// Defer notification to end of call stack (debounced)
-userStatePart.notifyChangeCumulative();
+// Also available as a convenience method on the Smartstate instance:
+const greeting2$ = state.computed(
+  [userState, settingsState],
+  (user, settings) => `${user.firstName} - ${settings.locale}`,
+);
 ```
 
-### Persistent State with WebStore
+Computed observables are **lazy** — they only subscribe to their sources when someone subscribes to them, and they automatically unsubscribe when all subscribers disconnect.
+
+### 📦 Batch Updates
 
-`Smartstate` supports persistent states using WebStore (IndexedDB-based storage), allowing you to maintain state across sessions:
+Update multiple state parts at once while deferring all notifications until the entire batch completes:
 
 ```typescript
-const settingsStatePart = await myAppSmartState.getStatePart<ISettingsState>(
-  AppStateParts.SettingsState,
-  { theme: 'light' }, // Initial/default state
-  'persistent' // Mode
-);
-```
+const partA = await state.getStatePart('a', { value: 1 });
+const partB = await state.getStatePart('b', { value: 2 });
 
-Persistent state automatically:
-- Saves state changes to IndexedDB
-- Restores state on application restart
-- Merges persisted values with defaults (persisted values take precedence)
-- Ensures atomic writes (persistence happens before memory update)
+await state.batch(async () => {
+  await partA.setState({ value: 10 });
+  await partB.setState({ value: 20 });
+  // No notifications fire inside the batch
+});
+// Both subscribers now fire with their new values simultaneously
+
+// Nested batches are supported — flush happens at the outermost level only
+await state.batch(async () => {
+  await partA.setState({ value: 100 });
+  await state.batch(async () => {
+    await partB.setState({ value: 200 });
+  });
+  // Still deferred — inner batch doesn't trigger flush
+});
+// Now both fire
+```
 
-### State Validation
+### ⏳ Waiting for State
 
-`Smartstate` includes built-in state validation to ensure data integrity:
+Wait for a specific state condition to be met before proceeding:
 
 ```typescript
-// Basic validation (built-in) ensures state is not null or undefined
-await userStatePart.setState(null); // Throws error: Invalid state structure
+// Wait for any truthy state
+const currentState = await userState.waitUntilPresent();
 
-// Custom validation by extending StatePart
-class ValidatedStatePart<T> extends StatePart<string, T> {
-  protected validateState(stateArg: any): stateArg is T {
-    return super.validateState(stateArg) && /* your validation */;
-  }
+// Wait for a specific condition
+const name = await userState.waitUntilPresent((s) => s.name || undefined);
+
+// With timeout (milliseconds)
+const name = await userState.waitUntilPresent((s) => s.name || undefined, 5000);
+
+// With AbortSignal and/or timeout via options object
+const controller = new AbortController();
+try {
+  const name = await userState.waitUntilPresent(
+    (s) => s.name || undefined,
+    { timeoutMs: 5000, signal: controller.signal },
+  );
+} catch (e) {
+  // e.message is 'Aborted' or 'waitUntilPresent timed out after 5000ms'
 }
 ```
 
-### Performance Optimization
+### 🌐 Context Protocol Bridge (Web Components)
+
+Expose state parts to web components via the [W3C Context Protocol](https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md). This lets any web component framework (Lit, FAST, Stencil, or vanilla) consume your state without coupling:
+
+```typescript
+import { attachContextProvider } from '@push.rocks/smartstate';
+
+// Define a context key (use Symbol for uniqueness)
+const themeContext = Symbol('theme');
 
-`Smartstate` includes advanced performance optimizations:
+// Attach a provider to a DOM element — any descendant can consume it
+const cleanup = attachContextProvider(document.body, {
+  context: themeContext,
+  statePart: settingsState,
+  selectorFn: (s) => s.theme, // optional: provide a derived value instead of full state
+});
+
+// A consumer dispatches a context-request event:
+myComponent.dispatchEvent(
+  new CustomEvent('context-request', {
+    bubbles: true,
+    composed: true,
+    detail: {
+      context: themeContext,
+      callback: (theme) => console.log('Got theme:', theme),
+      subscribe: true, // receive updates whenever the state changes
+    },
+  }),
+);
 
-- **🔒 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()` with automatic debouncing
-- **🎯 Selective Subscriptions**: Use selectors to subscribe only to specific state properties
-- **✨ Undefined State Filtering**: The `select()` method automatically filters out undefined states
-- **⚡ Concurrent Access Safety**: Prevents race conditions when multiple calls request the same state part simultaneously
+// Works seamlessly with Lit's @consume() decorator, FAST's context, etc.
+
+// Cleanup when the provider is no longer needed
+cleanup();
+```
 
-### RxJS Integration
+### ✅ State Validation
 
-`Smartstate` leverages RxJS for reactive state management:
+Built-in validation prevents `null` and `undefined` from being set as state. For custom validation, extend `StatePart`:
 
 ```typescript
-// State is exposed as an RxJS Subject
-const stateObservable = userStatePart.select();
+import { StatePart } from '@push.rocks/smartstate';
+
+class ValidatedUserPart extends StatePart<string, IUserState> {
+  protected validateState(stateArg: any): stateArg is IUserState {
+    return (
+      super.validateState(stateArg) &&
+      typeof stateArg.name === 'string' &&
+      typeof stateArg.loggedIn === 'boolean'
+    );
+  }
+}
+```
+
+If validation fails, `setState()` throws and the state remains unchanged.
+
+### ⚙️ Async State Setup
 
-// Automatically starts with current state value
-stateObservable.subscribe((state) => {
-  console.log('Current state:', state);
+Initialize state with async operations while ensuring actions wait for setup to complete:
+
+```typescript
+await userState.stateSetup(async (statePart) => {
+  const userData = await fetchUserFromAPI();
+  return { ...statePart.getState(), ...userData };
 });
 
-// Use selectors for specific properties
-userStatePart.select(state => state.username)
-  .pipe(
-    distinctUntilChanged(),
-    filter(username => username !== undefined)
-  )
-  .subscribe(username => {
-    console.log('Username changed:', username);
-  });
+// Any dispatchAction() calls will automatically wait for stateSetup() to finish
 ```
 
-### Complete Example
+### 🏎️ Performance
 
-Here's a comprehensive example showcasing the power of `@push.rocks/smartstate`:
+Smartstate is built with performance in mind:
 
-```typescript
-import { Smartstate, StatePart, StateAction } from '@push.rocks/smartstate';
+- **🔒 SHA256 Change Detection** — Uses content hashing to detect actual changes. Identical state values don't trigger notifications, even with different object references.
+- **♻️ 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.
+- **⏸️ Batch Deferred Notifications** — `batch()` suppresses all subscriber notifications until every update in the batch completes.
 
-// Define your state structure
-type AppStateParts = 'user' | 'settings' | 'cart';
+## API Reference
 
-interface IUserState {
-  isLoggedIn: boolean;
-  username?: string;
-  email?: string;
-}
+### `Smartstate<T>`
 
-interface ICartState {
-  items: Array<{ id: string; quantity: number }>;
-  total: number;
-}
+| Method / Property | Description |
+|-------------------|-------------|
+| `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 |
+| `isBatching` | `boolean` — whether a batch is currently active |
+| `statePartMap` | Registry of all created state parts |
 
-// Create the smartstate instance
-const appState = new Smartstate<AppStateParts>();
+### `StatePart<TName, TPayload>`
 
-// Initialize state parts
-const userState = await appState.getStatePart<IUserState>('user', {
-  isLoggedIn: false
-});
+| Method | Description |
+|--------|-------------|
+| `getState()` | Get current state (returns `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 }` |
+| `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? }` |
+| `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 |
 
-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
-    };
-  }
-);
+### `StateAction<TState, TPayload>`
 
-// Subscribe to changes
-userState.select(state => state.isLoggedIn).subscribe(isLoggedIn => {
-  console.log('Login status changed:', isLoggedIn);
-});
+| Method | Description |
+|--------|-------------|
+| `trigger(payload)` | Dispatch the action on its associated state part |
 
-// Dispatch actions
-await loginAction.trigger({ username: 'john', email: 'john@example.com' });
-```
+### Standalone Functions
+
+| Function | Description |
+|----------|-------------|
+| `computed(sources, fn)` | Create a computed observable from multiple state parts |
+| `attachContextProvider(element, options)` | Bridge a state part to the W3C Context Protocol |
 
-## Key Features
-
-| Feature | Description |
-|---------|-------------|
-| 🎯 **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 |
-| 🛡️ **Race condition safe** | Concurrent state part creation is handled safely |
-| ⏱️ **Timeout support** | `waitUntilPresent` supports optional timeouts |
+### Exported Types
+
+| Type | Description |
+|------|-------------|
+| `TInitMode` | `'soft' \| 'mandatory' \| 'force' \| 'persistent'` |
+| `TMiddleware<TPayload>` | `(newState, oldState) => TPayload \| Promise<TPayload>` |
+| `IActionDef<TState, TPayload>` | Action definition function signature |
+| `IContextProviderOptions<TPayload>` | Options for `attachContextProvider` |
 
 ## License and Legal Information
 
-This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
@@ -323,7 +396,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.0.31',
-  description: 'A package for handling and managing state in applications.'
+  version: '2.1.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

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

package/ts/smartstate.classes.computed.ts

@@ -0,0 +1,16 @@
+import * as plugins from './smartstate.plugins.js';
+import { combineLatest, map } from 'rxjs';
+import type { StatePart } from './smartstate.classes.statepart.js';
+
+/**
+ * creates a computed observable derived from multiple state parts.
+ * the observable is lazy — it only subscribes to sources when subscribed to.
+ */
+export function computed<TResult>(
+  sources: StatePart<any, any>[],
+  computeFn: (...states: any[]) => TResult,
+): plugins.smartrx.rxjs.Observable<TResult> {
+  return combineLatest(sources.map((sp) => sp.select())).pipe(
+    map((states) => computeFn(...states)),
+  ) as plugins.smartrx.rxjs.Observable<TResult>;
+}