Skip to main content

Subscriptions & Surgical Propagation

The heart of SoulState's performance identity is its Subscription Engine. Unlike global broadcast systems that notify all listeners on every change, SoulState uses an Invalidation Graph to achieve surgical precision.

Granular Propagation​

When you create a subscription (via useStore or store.subscribe), it is registered in a Directed Acyclic Graph (DAG).

  1. State Change: An update is applied to the store.
  2. Graph Query: The engine identifies only the nodes that explicitly depend on the changed keys.
  3. Topological Dispatch: Nodes are notified in a deterministic order based on their level in the graph.

Sparse Updates​

SoulState is optimized for Sparse Updates—scenarios where a large store exists, but most updates only affect a tiny fraction of the components.

// 100,000 subscribers are registered across various keys.
// We update ONLY the 'user' key.
store.setState({ user: { name: 'Bob' } });

Execution Profile:

  • SoulState: Directly identifies the ~1,000 listeners watching user. Skips the other 99,000 completely.
  • Complexity: $O(M)$ where $M$ is the number of affected nodes.

Irrelevant Update Elimination​

Irrelevant updates are the silent performance killer in large React apps. SoulState eliminates them at three levels:

  1. Graph Filtering: If your key didn't change, your listener is not even considered for execution.
  2. Equality Suppression: If a computed dependency recomputes but returns the same value, propagation stops at that node and never reaches downstream subscribers.
  3. No-Op Bypassing: If setState is called with identical data, the entire propagation engine is bypassed.

Subscription Scalability​

SoulState's internal data structures are designed for enterprise-scale subscription graphs:

  • O(1) Teardown: Removing a subscription is a simple pointer update in a doubly linked list, preventing "unmount lag" in dynamic UIs.
  • Sparse Memory Map: Nodes are only created for active subscribers, keeping the memory footprint proportional to the active UI state.
  • Topological Leveling: Prevents "glitches" or redundant re-renders in complex dependency diamonds.
✅

Systems-Grade Scaling

By moving from O(N) broadcast to O(M) surgical propagation, SoulState ensures that your application remains responsive at 100,000 subscribers, providing predictable latency even under heavy state load.