Files

Juergen Kunz 575477df09 feat(smartstate): Add middleware, computed, batching, selector memoization, AbortSignal support, and Web Component Context Protocol provider

2026-02-27 11:40:07 +00:00

11 KiB

Raw Permalink Blame History

@push.rocks/smartstate

A TypeScript-first reactive state management library with middleware, computed state, batching, persistence, and Web Component Context Protocol support 🚀

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

pnpm install @push.rocks/smartstate --save

Or with npm:

npm install @push.rocks/smartstate --save

Usage

Quick Start

import { Smartstate } from '@push.rocks/smartstate';

// 1. Define your state part names
type AppParts = 'user' | 'settings';

// 2. Create the root instance
const state = new Smartstate<AppParts>();

// 3. Create state parts with initial values
const userState = await state.getStatePart<{ name: string; loggedIn: boolean }>('user', {
  name: '',
  loggedIn: false,
});

// 4. Subscribe to changes
userState.select((s) => s.name).subscribe((name) => {
  console.log('Name changed:', name);
});

// 5. Update state
await userState.setState({ name: 'Alice', loggedIn: true });

State Parts & Init Modes

State parts are isolated, typed units of state. Create them with getStatePart():

const part = await state.getStatePart<IMyState>(name, initialState, initMode);

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

Persistent State

const settings = await state.getStatePart('settings', { theme: 'dark' }, 'persistent');
// Automatically saved to IndexedDB. On next app load, persisted values override defaults.

Selecting State

select() returns an RxJS Observable that emits the current value immediately and on every change:

// Full state
userState.select().subscribe((state) => console.log(state));

// Derived value via selector
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.

AbortSignal Support

Clean up subscriptions without manual unsubscribe():

const controller = new AbortController();

userState.select((s) => s.name, { signal: controller.signal }).subscribe((name) => {
  console.log(name); // stops receiving when aborted
});

// Later: clean up
controller.abort();

Actions

Actions provide controlled, named state mutations:

const login = userState.createAction<{ name: string }>(async (statePart, payload) => {
  return { ...statePart.getState(), name: payload.name, loggedIn: true };
});

// Two equivalent ways to dispatch:
await login.trigger({ name: 'Alice' });
await userState.dispatchAction(login, { name: 'Alice' });

Middleware

Intercept every setState() call to transform, validate, or reject state changes:

// Logging middleware
userState.addMiddleware((newState, oldState) => {
  console.log('State changing from', oldState, 'to', 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() };
});

// Removal — addMiddleware returns a dispose function
const remove = userState.addMiddleware(myMiddleware);
remove(); // middleware no longer runs

Middleware runs sequentially in insertion order. If any middleware throws, the state is unchanged (atomic).

Computed / Derived State

Derive reactive values from one or more state parts:

import { computed } from '@push.rocks/smartstate';

const userState = await state.getStatePart('user', { firstName: 'Jane', lastName: 'Doe' });
const settingsState = await state.getStatePart('settings', { locale: 'en' });

// Standalone function
const greeting$ = computed(
  [userState, settingsState],
  (user, settings) => `Hello, ${user.firstName} (${settings.locale})`,
);

greeting$.subscribe((msg) => console.log(msg));
// => "Hello, Jane (en)"

// Also available as a method on Smartstate:
const greeting2$ = state.computed([userState, settingsState], (user, settings) => /* ... */);

Computed observables are lazy — they only subscribe to sources when someone subscribes to them.

Batch Updates

Update multiple state parts without intermediate notifications:

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

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

Waiting for State

Wait for a specific state condition to be met:

// Wait for any truthy state
const currentState = await userState.waitUntilPresent();

// Wait for a specific condition
const name = await userState.waitUntilPresent((s) => s.name || undefined);

// With timeout (backward compatible)
const name = await userState.waitUntilPresent((s) => s.name || undefined, 5000);

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

Expose state parts to web components via the W3C Context Protocol:

import { attachContextProvider } from '@push.rocks/smartstate';

// 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
});

// 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
    },
  }),
);

// Cleanup when done
cleanup();

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:

class ValidatedPart<T> extends StatePart<string, T> {
  protected validateState(stateArg: any): stateArg is T {
    return super.validateState(stateArg) && typeof stateArg.name === 'string';
  }
}

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

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the 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.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

11 KiB Raw Permalink Blame History