@push.rocks/smartstate 2.0.31 → 2.1.0

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,306 +8,311 @@ 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.
-
-### Getting Started
-
-Import the necessary components from the library:
+### Quick Start
 
 ```typescript
-import { Smartstate, StatePart, StateAction } from '@push.rocks/smartstate';
-```
-
-### Creating a SmartState Instance
+import { Smartstate } from '@push.rocks/smartstate';
 
-`Smartstate` acts as the container for your state parts. Think of it as the root of your state management structure:
+// 1. Define your state part names
+type AppParts = 'user' | 'settings';
 
-```typescript
-const myAppSmartState = new Smartstate<YourStatePartNamesEnum>();
-```
+// 2. Create the root instance
+const state = new Smartstate<AppParts>();
 
-### Understanding Init Modes
+// 3. Create state parts with initial values
+const userState = await state.getStatePart<{ name: string; loggedIn: boolean }>('user', {
+  name: '',
+  loggedIn: false,
+});
 
-When creating state parts, you can specify different initialization modes:
+// 4. Subscribe to changes
+userState.select((s) => s.name).subscribe((name) => {
+  console.log('Name changed:', name);
+});
 
-| 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 |
+// 5. Update state
+await userState.setState({ name: 'Alice', loggedIn: true });
+```
 
-### Defining State Parts
+### State Parts & Init Modes
 
-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:
+State parts are isolated, typed units of state. Create them with `getStatePart()`:
 
 ```typescript
-// Option 1: Using enums
-enum AppStateParts {
-  UserState = 'UserState',
-  SettingsState = 'SettingsState'
-}
-
-// Option 2: Using string literal types (simpler approach)
-type AppStateParts = 'UserState' | 'SettingsState';
+const part = await state.getStatePart<IMyState>(name, initialState, initMode);
 ```
 
-Create a state part within your `Smartstate` instance:
+| Init Mode | Behavior |
+|-----------|----------|
+| `'soft'` (default) | Returns existing if found, creates new otherwise |
+| `'mandatory'` | Throws if state part already exists |
+| `'force'` | Always creates new, overwrites existing |
+| `'persistent'` | Like `'soft'` but persists to IndexedDB via WebStore |
 
-```typescript
-interface IUserState {
-  isLoggedIn: boolean;
-  username?: string;
-}
+#### Persistent State
 
-const userStatePart = await myAppSmartState.getStatePart<IUserState>(
-  AppStateParts.UserState,
-  { isLoggedIn: false }, // Initial state
-  'soft' // Init mode (optional, defaults to 'soft')
-);
+```typescript
+const settings = await state.getStatePart('settings', { theme: 'dark' }, 'persistent');
+// Automatically saved to IndexedDB. On next app load, persisted values override defaults.
 ```
 
-### 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 change:
 
 ```typescript
-// The select() method automatically filters out undefined states
-userStatePart.select().subscribe((currentState) => {
-  console.log(`User Logged In: ${currentState.isLoggedIn}`);
-});
-```
-
-Select a specific part of your state with a selector function:
+// Full state
+userState.select().subscribe((state) => console.log(state));
 
-```typescript
-userStatePart.select(state => state.username).subscribe((username) => {
-  if (username) {
-    console.log(`Current user: ${username}`);
-  }
-});
+// Derived value via selector
+userState.select((s) => s.name).subscribe((name) => console.log(name));
 ```
 
-### Modifying State with Actions
+Selectors are **memoized** — calling `select(fn)` with the same function reference returns the same cached Observable, shared across all subscribers.
+
+#### AbortSignal Support
 
-Create actions to modify the state in a controlled manner:
+Clean up subscriptions without manual `unsubscribe()`:
 
 ```typescript
-interface ILoginPayload {
-  username: string;
-}
+const controller = new AbortController();
 
-const loginUserAction = userStatePart.createAction<ILoginPayload>(async (statePart, payload) => {
-  return { ...statePart.getState(), isLoggedIn: true, username: payload.username };
+userState.select((s) => s.name, { signal: controller.signal }).subscribe((name) => {
+  console.log(name); // stops receiving when aborted
 });
 
-// Dispatch the action to update the state
-const newState = await loginUserAction.trigger({ username: 'johnDoe' });
+// Later: clean up
+controller.abort();
 ```
 
-### Dispatching Actions
+### Actions
 
-There are two ways to dispatch actions:
+Actions provide controlled, named state mutations:
 
 ```typescript
-// Method 1: Using trigger on the action (returns promise)
-const newState = await loginUserAction.trigger({ username: 'johnDoe' });
+const login = userState.createAction<{ name: string }>(async (statePart, payload) => {
+  return { ...statePart.getState(), name: payload.name, loggedIn: true };
+});
 
-// Method 2: Using dispatchAction on the state part (returns promise)
-const newState = await userStatePart.dispatchAction(loginUserAction, { username: 'johnDoe' });
+// Two equivalent ways to dispatch:
+await login.trigger({ name: 'Alice' });
+await userState.dispatchAction(login, { name: 'Alice' });
 ```
 
-Both methods return a Promise with the new state payload.
+### Middleware
 
-### Additional State Methods
-
-`StatePart` provides several useful methods for state management:
+Intercept every `setState()` call to transform, validate, or reject state changes:
 
 ```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();
-
-// Wait for a specific property to be present
-await userStatePart.waitUntilPresent(state => state.username);
+// Logging middleware
+userState.addMiddleware((newState, oldState) => {
+  console.log('State changing from', oldState, 'to', newState);
+  return newState;
+});
 
-// 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');
-}
+// Validation middleware — throw to reject the change
+userState.addMiddleware((newState) => {
+  if (!newState.name) throw new Error('Name is required');
+  return newState;
+});
 
-// Setup initial state with async operations
-await userStatePart.stateSetup(async (statePart) => {
-  const userData = await fetchUserData();
-  return { ...statePart.getState(), ...userData };
+// Transform middleware
+userState.addMiddleware((newState) => {
+  return { ...newState, name: newState.name.trim() };
 });
 
-// Defer notification to end of call stack (debounced)
-userStatePart.notifyChangeCumulative();
+// Removal — addMiddleware returns a dispose function
+const remove = userState.addMiddleware(myMiddleware);
+remove(); // middleware no longer runs
 ```
 
-### Persistent State with WebStore
+Middleware runs sequentially in insertion order. If any middleware throws, the state is unchanged (atomic).
 
-`Smartstate` supports persistent states using WebStore (IndexedDB-based storage), allowing you to maintain state across sessions:
+### Computed / Derived State
 
-```typescript
-const settingsStatePart = await myAppSmartState.getStatePart<ISettingsState>(
-  AppStateParts.SettingsState,
-  { theme: 'light' }, // Initial/default state
-  'persistent' // Mode
-);
-```
+Derive reactive values from one or more state parts:
 
-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)
+```typescript
+import { computed } from '@push.rocks/smartstate';
 
-### State Validation
+const userState = await state.getStatePart('user', { firstName: 'Jane', lastName: 'Doe' });
+const settingsState = await state.getStatePart('settings', { locale: 'en' });
 
-`Smartstate` includes built-in state validation to ensure data integrity:
+// Standalone function
+const greeting$ = computed(
+  [userState, settingsState],
+  (user, settings) => `Hello, ${user.firstName} (${settings.locale})`,
+);
 
-```typescript
-// Basic validation (built-in) ensures state is not null or undefined
-await userStatePart.setState(null); // Throws error: Invalid state structure
+greeting$.subscribe((msg) => console.log(msg));
+// => "Hello, Jane (en)"
 
-// 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 */;
-  }
-}
+// Also available as a method on Smartstate:
+const greeting2$ = state.computed([userState, settingsState], (user, settings) => /* ... */);
 ```
 
-### Performance Optimization
-
-`Smartstate` includes advanced performance optimizations:
+Computed observables are **lazy** — they only subscribe to sources when someone subscribes to them.
 
-- **🔒 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
+### Batch Updates
 
-### RxJS Integration
-
-`Smartstate` leverages RxJS for reactive state management:
+Update multiple state parts without intermediate notifications:
 
 ```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);
+const partA = await state.getStatePart('a', { value: 1 });
+const partB = await state.getStatePart('b', { value: 2 });
+
+// Subscribers see no updates during the batch — only after it completes
+await state.batch(async () => {
+  await partA.setState({ value: 10 });
+  await partB.setState({ value: 20 });
+  // Notifications are deferred here
 });
+// Both subscribers now fire with their new values
 
-// Use selectors for specific properties
-userStatePart.select(state => state.username)
-  .pipe(
-    distinctUntilChanged(),
-    filter(username => username !== undefined)
-  )
-  .subscribe(username => {
-    console.log('Username changed:', username);
+// Nested batches are supported — flush happens at the outermost level
+await state.batch(async () => {
+  await partA.setState({ value: 100 });
+  await state.batch(async () => {
+    await partB.setState({ value: 200 });
   });
+  // Still deferred
+});
+// Now both fire
 ```
 
-### Complete Example
+### Waiting for State
 
-Here's a comprehensive example showcasing the power of `@push.rocks/smartstate`:
+Wait for a specific state condition to be met:
 
 ```typescript
-import { Smartstate, StatePart, StateAction } from '@push.rocks/smartstate';
+// Wait for any truthy state
+const currentState = await userState.waitUntilPresent();
 
-// Define your state structure
-type AppStateParts = 'user' | 'settings' | 'cart';
+// Wait for a specific condition
+const name = await userState.waitUntilPresent((s) => s.name || undefined);
 
-interface IUserState {
-  isLoggedIn: boolean;
-  username?: string;
-  email?: string;
-}
+// With timeout (backward compatible)
+const name = await userState.waitUntilPresent((s) => s.name || undefined, 5000);
 
-interface ICartState {
-  items: Array<{ id: string; quantity: number }>;
-  total: number;
+// With AbortSignal
+const controller = new AbortController();
+try {
+  const name = await userState.waitUntilPresent(
+    (s) => s.name || undefined,
+    { timeoutMs: 5000, signal: controller.signal },
+  );
+} catch (e) {
+  // 'Aborted' or timeout error
 }
+```
+
+### Context Protocol Bridge (Web Components)
 
-// Create the smartstate instance
-const appState = new Smartstate<AppStateParts>();
+Expose state parts to web components via the [W3C Context Protocol](https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md):
+
+```typescript
+import { attachContextProvider } from '@push.rocks/smartstate';
 
-// Initialize state parts
-const userState = await appState.getStatePart<IUserState>('user', {
-  isLoggedIn: false
+// Define a context key
+const themeContext = Symbol('theme');
+
+// Attach a provider to a DOM element
+const cleanup = attachContextProvider(myElement, {
+  context: themeContext,
+  statePart: settingsState,
+  selectorFn: (s) => s.theme, // optional: provide derived value
 });
 
-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
-    };
-  }
+// Any descendant can request this context:
+myElement.dispatchEvent(
+  new CustomEvent('context-request', {
+    bubbles: true,
+    composed: true,
+    detail: {
+      context: themeContext,
+      callback: (theme) => console.log('Theme:', theme),
+      subscribe: true, // receive updates on state changes
+    },
+  }),
 );
 
-// Subscribe to changes
-userState.select(state => state.isLoggedIn).subscribe(isLoggedIn => {
-  console.log('Login status changed:', isLoggedIn);
-});
+// Cleanup when done
+cleanup();
+```
 
-// Dispatch actions
-await loginAction.trigger({ username: 'john', email: 'john@example.com' });
+This works with Lit's `@consume()` decorator, FAST, or any framework implementing the Context Protocol.
+
+### State Validation
+
+Built-in null/undefined validation. Extend for custom rules:
+
+```typescript
+class ValidatedPart<T> extends StatePart<string, T> {
+  protected validateState(stateArg: any): stateArg is T {
+    return super.validateState(stateArg) && typeof stateArg.name === 'string';
+  }
+}
 ```
 
-## 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 |
+### Performance Features
+
+- **SHA256 Change Detection** — identical state values don't trigger notifications, even with different object references
+- **Selector Memoization** — `select(fn)` caches observables by function reference, sharing one upstream subscription across all subscribers
+- **Cumulative Notifications** — `notifyChangeCumulative()` debounces rapid changes into a single notification
+- **Concurrent Safety** — simultaneous `getStatePart()` calls for the same name return the same promise, preventing duplicate creation
+- **Atomic Persistence** — WebStore writes complete before in-memory state updates, ensuring consistency
+- **Batch Deferred Notifications** — `batch()` suppresses all notifications until the batch completes
+
+## API Reference
+
+### `Smartstate<T>`
+
+| Method | Description |
+|--------|-------------|
+| `getStatePart(name, initial?, initMode?)` | Get or create a state part |
+| `batch(fn)` | Batch updates, defer notifications |
+| `computed(sources, fn)` | Create computed observable |
+| `isBatching` | Whether a batch is active |
+
+### `StatePart<TName, TPayload>`
+
+| Method | Description |
+|--------|-------------|
+| `getState()` | Get current state (or undefined) |
+| `setState(newState)` | Set state (runs middleware, validates, persists, notifies) |
+| `select(selectorFn?, options?)` | Subscribe to state changes |
+| `createAction(actionDef)` | Create a named action |
+| `dispatchAction(action, payload)` | Dispatch an action |
+| `addMiddleware(fn)` | Add middleware, returns removal function |
+| `waitUntilPresent(selectorFn?, options?)` | Wait for state condition |
+| `notifyChange()` | Manually trigger notification |
+| `notifyChangeCumulative()` | Debounced notification |
+| `stateSetup(fn)` | Async state initialization |
+
+### `StateAction<TState, TPayload>`
+
+| Method | Description |
+|--------|-------------|
+| `trigger(payload)` | Dispatch the action |
+
+### Standalone Functions
+
+| Function | Description |
+|----------|-------------|
+| `computed(sources, fn)` | Create computed observable from state parts |
+| `attachContextProvider(element, options)` | Bridge state to Context Protocol |
 
 ## License and Legal Information
 

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.0',
+  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>;
+}