State Management

Last Updated: May 19, 2025

This document provides an overview of the state management system in the frontend architecture of the Typus Development Framework.

Introduction

State management is a critical aspect of any modern frontend application. The Typus framework implements a layered approach to state management, combining the power of Pinia with custom abstractions for persistence and specialized use cases.

Architecture Overview

The state management architecture in Typus follows a multi-layered approach:

This layered approach provides:

• Separation of concerns: Each layer has a specific responsibility
• Flexibility: Different state management strategies for different needs
• Persistence: Automatic state persistence where needed
• Type safety: Full TypeScript support throughout the stack

Core Components

Pinia Stores

At the foundation of the state management system is Pinia, the official state management library for Vue.js. Pinia provides:

• TypeScript support
• Devtools integration
• Hot module replacement
• Plugin extensibility

The framework initializes Pinia in the application bootstrap process:

// Core Pinia instance
export const pinia = createPinia()

Store Types

The framework provides several specialized store types:

Application Store

The Application Store (appStore) manages global application state:

• Application version
• Loading states
• User credentials (for "remember me" functionality)

Authentication Store

The Authentication Store (authStore) handles user authentication:

• Login/logout functionality
• Token management
• User profile data
• Permission management

Persistence Store

The Persistence Store (persistStore) provides a unified API for storing data in browser storage:

• Automatic serialization/deserialization
• Support for nested data structures
• Configurable storage backends (localStorage, sessionStorage)

Using State Management

Store Composables

The framework provides composable functions to access stores with a clean API:

// Access the application store
const appStore = useAppStore()

// Access the authentication store
const authStore = useAuthStore()

// Access the persistence store directly
const persistStore = usePersistStore()

Generic Store Access

For simpler use cases, the framework provides a generic useStore composable:

const store = useStore()

// Get a value with a default fallback
const theme = store.get('user_theme', 'light')

// Set a value
store.set('user_theme', 'dark')

// Remove a value
store.remove('user_theme')

// Clear all stored values
store.clear()

Nested Data Access

The persistence system supports dot notation for accessing nested data:

// Set nested data
store.set('user.preferences.theme', 'dark')

// Get nested data
const theme = store.get('user.preferences.theme', 'light')

Integration with Other Systems

Context System Integration

The state management system integrates with the context system:

• Contexts can access stores for global state
• Stores can be injected into contexts
• Context-specific state can be persisted through stores

DSX Integration

DSX components can interact with the state management system:

• DSX blocks can access store data
• Store updates can trigger DSX UI updates
• DSX actions can modify store state

DSL Integration

The state management system works seamlessly with the DSL system:

• DSL model data can be cached in stores
• Stores can track DSL operation status
• Authentication state controls DSL access

Best Practices

When to Use Each Approach

• Pinia Stores: For complex, application-wide state that requires structure and actions
• Context System: For component-specific or page-specific state
• Persistence Store: For data that needs to survive page reloads or browser sessions
• Local Component State: For UI-specific state that doesn't need to be shared

Performance Considerations

• Use selective imports to avoid loading unnecessary stores
• Be mindful of what data is persisted to storage
• Consider using computed properties for derived state
• Use shallowRef for large objects that don't need deep reactivity

Security Considerations

• Never store sensitive information in localStorage
• Use sessionStorage for session-specific data
• Clear authentication data on logout
• Validate data retrieved from storage before use

Conclusion

The state management system in the Typus frontend provides a flexible, layered approach to managing application state. By combining the power of Pinia with custom abstractions for persistence and specialized use cases, it enables developers to build complex, stateful applications while maintaining clean, maintainable code.

The integration with other systems like contexts, DSX, and DSL creates a cohesive development experience where state management feels natural and intuitive.