Architecting a Hybrid
State Management Library

Leveraging the industry's best to build a unified, powerful, and developer-friendly state solution in Vanilla JS.

The Core Philosophy

The library is founded on three key architectural pillars designed for flexibility and power.

🔄

Dual-Store Architecture

A powerful global store for application-wide state, paired with lightweight, private scoped states for individual components.

💎

Guaranteed Immutability

Enforcing data integrity and predictable state changes in the global store, preventing side-effects and enabling advanced features.

🧩

Native Enhancement

Designed to augment, not replace, native platform features like Web Component state and the DOM event model.

A Tale of Two Stores

The architecture provides two distinct but connected state management models to fit any use case.

The Global Store

For centralized, predictable application-wide state.

UI Event
`store.dispatch(action)`
Middleware Chain
Pure Reducer
New Immutable State

Scoped State

For localized, reactive component-level state.

Component Initialized
`createScopedState(value)`
`state.val = newValue`
Direct DOM Update
UI Reflects Change

The Power of Synergy

The library's initial strength comes from unifying the best features of established tools.

Redux

Provides the predictable state container pattern.

VanJS

Powers the reactive, lightweight scoped states.

Immutable.js

Ensures data integrity and performance.

Killa.js

Inspires the flexible state persistence layer.

The Bridge: Connecting Worlds

A controlled interface allows scoped components to safely read from or dispatch actions to the global store.

Scoped Component

`getGlobalState(selector)`
`dispatchGlobal(action)`

Global Store

API Inspiration

The library's API design is a synthesis of familiar and powerful patterns.

This chart illustrates the proportional influence of source libraries on the design of the core public API, showcasing the "piece-meal" approach to creating a comprehensive and intuitive developer experience.

Roadmap to Independence

A phased approach ensures a stable evolution towards a fully dependency-free library.

Phase 1: Core Functionality

Implement the dual-store architecture, the bridge API, and establish comprehensive testing.

Phase 2: Enhancements & DX

Integrate Redux DevTools, implement the middleware system, and add state persistence.

Phase 3: Expansion & Refinement

Create a full build system and begin incrementally replacing dependencies with custom code.