Skip to main content

The Centralized Reactive Store

The Store is the fundamental unit of SoulState. Unlike atomic state managers where state is fragmented across many small units, SoulState uses a Centralized Reactive Tree—a single, predictable source of truth for your entire application or a major domain.

The Store as a Runtime​

In SoulState, a store is not just a container for data; it is an active Reactive Runtime. When you create a store via createStore, you are initializing a systems-grade engine that manages:

  1. State Settlement: Immutable reconciliation of incoming updates.
  2. Invalidation Logic: Mapping state changes to affected listeners.
  3. Propagation Scheduling: Coordinating the execution of computeds and React renders in deterministic order.

Store Lifecycle​

A SoulState store follows a clear, predictable lifecycle:

1. Initialization​

The store is created with an initial state or a creator function. At this stage, the Invalidation Graph is empty.

2. Registration​

As components mount and call useStore, or as computed nodes are defined, the store's engine builds a dependency map. This is the Building Phase, which involves topological level calculation for each new node.

3. Transition​

When setState is called, the store enters a Settlement Phase. The next state is applied, changed keys are detected, and a flush is scheduled in the microtask queue.

4. Propagation​

During the Flush Phase, the propagation engine traverses the graph. Affected nodes are executed in order of their topological depth. This ensures that no "glitches" (inconsistent views) are possible.

5. Settlement​

Once the flush is complete, the store returns to a settled state, waiting for the next user interaction or network event.

Deterministic Updates​

The defining characteristic of a SoulState store is Determinism.

  • Repeatability: Given the same initial state and sequence of setState calls, a SoulState store will always result in the same final state and notify listeners in the same topological order.
  • Microtask Stability: Updates are never lost or interleaved in ways that could cause UI tearing, thanks to the microtask-based batching.
✅

Systems-Grade Philosophy

By treating the store as a centralized reactive tree rather than a loose collection of atoms, SoulState provides the architectural clarity needed for large-scale enterprise applications while maintaining the performance of a granular runtime.