stateman-cli - Architectural Deep Dive

# Architecting a Hybrid State Management Library

This interactive report explores the architecture for a comprehensive, vanilla JavaScript state management library. The core strategy is a hybrid approach, leveraging the strengths of battle-tested dependencies for rapid, robust development, with a long-term vision for a fully self-reliant solution.

Dual-Store Architecture

A flexible model featuring a powerful global store for application-wide state and lightweight scoped states for localized, component-level logic.

Enforced Immutability

Data integrity is paramount. The global store mandates the use of immutable data structures, preventing side effects and enabling powerful features.

Native Enhancement

Designed to augment, not replace, native platform capabilities like Web Component state and the DOM event model, providing a seamless developer experience.

# Core Architecture: A Tale of Two Stores

The library's power lies in its dual-store model, providing the right tool for every state management challenge. This section breaks down the two core pillars—the Global Store and Scoped State—and shows how they connect to form a cohesive system.

The Global Store: Predictable & Centralized

Inspired by Redux, the global store acts as the single source of truth for the entire application. It ensures that data flow is predictable and changes are traceable through a structured action/reducer pattern. This robust foundation is ideal for managing complex, shared state and is built for extensibility with middleware and dev tools.

✓Single Source of Truth: Centralizes application state.
✓Immutable State: Enforced by Immutable.js for data integrity.
✓Traceable Updates: All changes occur via dispatched actions.

                                    graph TD
                                        A["UI Event (e.g., Button Click)"]
                                        B["store.dispatch(...)"]
                                        C["Reducer: (state, action) => newState"]
                                        D["New Immutable State Tree"]
                                        E["UI Updates (via store.subscribe())"]
                                        A --> B --> C --> D --> E

Scoped State: Reactive & UI-Bound

Leveraging the minimalism of VanJS, scoped states are designed for localized, component-level state. They are lightweight, reactive, and bind directly to DOM elements without a virtual DOM. This makes them incredibly efficient for managing UI-specific state like input values, hover effects, or the open/closed status of a component.

✓Lightweight & Performant: Minimal overhead for many instances.
✓Direct DOM Binding: State changes automatically update the UI.
✓Encapsulated: Naturally isolated within the component that creates it.

                                    graph TD
                                        A["Component Initialized"]
                                        B["createScopedState('World')"]
                                        C["DOM Element Bound: 
 <h1>Hello, {name}</h1>"]
                                        D["Update state: 
 name.val = 'Developer'"]
                                        E["DOM Automatically Updates"]
                                        A --> B --> C --> D --> E

The Bridge: Connecting the Worlds

A critical feature is the seamless bridge, allowing scoped components to safely interact with the global store. This provides controlled access for reading global data or dispatching global actions without creating tight coupling.

Scoped Component

e.g., A User Profile Card

Global Store

Single Source of Truth

# API

Explore the proposed public API. The design prioritizes developer experience by drawing from familiar patterns while integrating the unique capabilities of each dependency.

Visualizing API Influences

This chart shows which foundational libraries inspire the core API methods, illustrating the "piece-meal" approach to building a comprehensive solution.

# Future Roadmap

The initial release is just the beginning. The library is designed for evolution, with a clear path towards advanced features and eventual dependency freedom.