Skip to main content

Systems-Grade Best Practices

SoulState is engineered for high-density reactive environments. Following these best practices ensures that your application remains deterministic, scalable, and easy to maintain.

1. Embrace Surgical Selectors​

The most fundamental rule of SoulState: Select only what you need.

// ❌ Bad: Component re-renders on ANY change to user
const user = useStore(store, s => s.user);

// ✅ Good: Component re-renders only when user.id changes
const userId = useStore(store, s => s.user.id);

By being surgical with your selectors, you align your UI with the Invalidation Graph, maximizing throughput and minimizing re-render churn.

2. Co-locate Logic with computed​

Avoid putting complex data transformations inside your React components or standard selectors. Use computed nodes to build a cached, topologically stable derived state tree.

// Layering computeds builds a robust reactive pipeline
const activeUsers = store.computed(s => s.users.filter(u => u.active));
const adminCount = store.computed(() => activeUsers.value.filter(u => u.role === 'admin').length);

3. Use Transactions for Atomic Ingestion​

When performing multiple related updates (e.g., after a WebSocket message or API response), always use the Transaction API. This treats the multi-step update as a single systems-grade event.

store.beginTransaction();
store.setState({ items: newItems });
store.setState({ lastSync: Date.now() });
store.commitTransaction(); // Atomic propagation

4. Respect the Immutable Contract​

SoulState relies on strict immutability for its change detection. Never mutate state directly.

// ❌ Never do this
const { items } = store.getState();
items.push(newItem);

// ✅ Always do this
store.setState(s => ({ items: [...s.items, newItem] }));

When NOT to use SoulState​

While SoulState is a powerful systems-grade runtime, it is not always the right choice:

  1. Simple To-Do Apps: If your app has fewer than 50 components and 10 state keys, the initialization overhead of SoulState's Invalidation Graph is unnecessary. Use Zustand instead.
  2. Highly Volatile Atoms: If your state consists of thousands of independent atoms that never interact, a pure atomic library like Jotai may be more idiomatic.
  3. One-Time Global Broadcasts: If your updates always affect 100% of your subscribers (e.g., a "Reset All" action in a simple app), SoulState's surgical overhead makes it slower than a simple global event emitter.

Production Checklist​

  • Instrumentation: Enable onFlush profiling in staging to detect slow propagation paths.
  • Granularity: Verify that no component is subscribing to the entire root state object.
  • Error Boundaries: Use try...catch with rollbackTransaction to ensure store consistency during complex updates.
  • Destruction: Call store.destroy() when the store instance is no longer needed (e.g., on feature unmount) to free graph memory.
✅

Systems-Grade Philosophy

SoulState is designed for complexity at scale. By following these patterns, you treat state management as a systems engineering task, resulting in a predictable, high-performance runtime for your enterprise application.