Introduction to SoulState
The Deterministic Systems-Grade Granular Reactive Runtime.
SoulState is a high-performance state management engine specialized for sparse updates, deep dependency propagation, and enterprise-scale subscription graphs. It is designed to bridge the gap between the structured simplicity of centralized stores (like Zustand) and the surgical precision of atomic runtimes (like Jotai).
Unlike minimalist wrappers, SoulState is a graph-oriented reactive runtime that provides deterministic execution and irrelevant update elimination at extreme scale.
Core Mission
SoulState is engineered to handle 10,000 to 100,000+ active subscribers with predictable latency, ensuring that only the components truly affected by a state change ever execute.
Why SoulState?
Modern enterprise applications often suffer from "subscription bloat," where a single change in a large store triggers thousands of irrelevant checks. SoulState solves this through a systems-grade approach:
- Sparse Update Supremacy: Using a Directed Acyclic Graph (DAG), SoulState skips unrelated subscribers entirely. In a 100,000-subscriber store, if you change a key used by only 1% of listeners, SoulState notifies 1,000 nodes and ignores the other 99,000.
- Deep Propagation Performance: SoulState's level-based propagation engine guarantees glitch-free, topological ordering for deeply nested computed state, ensuring consistent views across complex dependency chains.
- Deterministic Execution: Updates are batched via a deterministic microtask scheduler, ensuring repeatable execution order and preventing "glitches" or recursive propagation explosions.
- Proxy-Based Tracking: A reusable tracking proxy detects dependencies with minimal garbage collection pressure, critical for high-frequency update loops.
Real-World Use Cases
SoulState excels in scenarios where data density and subscriber volume are high:
- Financial Dashboards: Real-time price feeds where thousands of UI widgets subscribe to specific subsets of a massive global state.
- Collaborative Editors: Massive document states where users only care about their local viewport or specific shared fragments.
- Complex Data Grids: Grids with 10,000+ cells where each cell subscribes to its specific coordinate or row data.
- Systems-Level UIs: Operating system shells, IDEs, or design tools where UI consistency and deterministic re-renders are paramount.
Honest Comparison
| Library | Architecture | Best For | Sparse Performance (100k) |
|---|---|---|---|
| SoulState | Granular DAG | Large-scale sparse updates | ~2,500 hz |
| Zustand | Global Broadcast | Simple stores, broad updates | ~320 hz |
| Jotai | Atomic | Component-local state | ~1,200 hz |
SoulState is not the "fastest global store" for every use case—it is a specialized tool for applications where granularity, scalability, and deterministic behavior are non-negotiable.