Context-Action Framework

Revolutionary TypeScript state management with document-centric context separation and MVVM architecture.

🎯 Perfect separation of concerns • 🔒 Full type safety • ⚡ Zero boilerplate • 🏗️ Scalable architecture

📚 Documentation • 🇰🇷 한국어 문서 • 🎮 Live Demo • 🚀 Quick Start

---

⚡ Quick Start

Installation

npm install @context-action/react
# or
npm install @context-action/core  # Pure TypeScript

30-Second Example

import { createStoreContext, useStoreValue } from '@context-action/react';
import { useCallback } from 'react';

// 1. Create context
const { Provider, useStore } = createStoreContext('User', {
  profile: { name: 'John', email: 'john@example.com' }
});

// 2. Use in component  
function UserProfile() {
  const profileStore = useStore('profile');
  const profile = useStoreValue(profileStore);
  
  return <h1>Welcome, {profile.name}!</h1>;
}

// 3. Wrap with provider
function App() {
  return (
    <Provider>
      <UserProfile />
    </Provider>
  );
}

That's it! 🎉 Full type safety, reactive updates, and clean architecture.

---

🎯 Why Context-Action?

❌ Problems with Existing Libraries

• High React Coupling → Difficult component modularization
• Binary State Approach → Poor scope-based separation
• Complex Boilerplate → Verbose setup and maintenance

✅ Context-Action's Solution

• 🎯 Document-Centric Design → Context separation based on domain boundaries
• 🏗️ MVVM Architecture → Perfect separation: Model, ViewModel, View layers
• 🔒 Type-First Approach → Zero runtime errors with full TypeScript support
• ⚡ Zero Boilerplate → Minimal code, maximum functionality

🚀 Key Benefits

// Before: Complex setup with multiple libraries
const store = createStore(reducer);
const dispatch = useDispatch();
const selector = useSelector(state => state.user);
const actions = bindActionCreators(userActions, dispatch);

// After: One line with Context-Action
const { profile, updateProfile } = useUserPage(); // All logic in hook

---

🏗️ Core Patterns

🏪 Store Pattern

Pure state management with reactive subscriptions

const { Provider: UserStoreProvider, useStore: useUserStore } = createStoreContext('User', {
  profile: { name: '', email: '' },
  settings: { theme: 'light' }
});

function UserComponent() {
  const profileStore = useUserStore('profile');
  const profile = useStoreValue(profileStore);

  return <div>{profile.name}</div>;
}

🎯 Action Pattern

Pure action dispatching with business logic separation

interface UserActions extends ActionPayloadMap {
  updateProfile: { name: string; email: string };
  logout: void;
}

const { Provider, useActionDispatch, useActionHandler } =
  createActionContext<UserActions>('UserActions');

function UserLogic() {
  const updateProfileHandler = useCallback(async (payload) => {
    // Business logic here
    await updateUserAPI(payload);
  }, []);

  useActionHandler('updateProfile', updateProfileHandler);
  
  return null; // Logic component
}

🔗 Pattern Composition

Combine patterns for complex applications

// MVVM Architecture
function App() {
  return (
    <UserActionProvider>     {/* ViewModel */}
      <UserStoreProvider>    {/* Model */}
        <UserLogic>          {/* Business Logic */}
          <UserProfile />    {/* View */}
        </UserLogic>
      </UserStoreProvider>
    </UserActionProvider>
  );
}

🏗️ 5-Layer Hooks Architecture

Context-Action implements a sophisticated 5-layer hooks architecture that provides perfect separation of concerns and optimal performance through delayed evaluation.

graph TD
    %% Context Share Layer
    subgraph ContextShare["Context Share Layer Provider"]
        Store[Store]
        subgraph ActionsContainer["Actions"]
            Actions[Actions]
            Pipeline[Pipeline<br/>- Business logic registration<br/>- Execution order management<br/>- Middleware processing]
        end
        Ref[Ref<br/>- Singleton instance management]
    end

    %% 6-Layer Hooks Structure
    subgraph Hooks["6-Layer Hooks Consumer"]
        ContextDef[contexts<br/>Resource type definitions]
        Business[business<br/>Pure business logic<br/>functions]
        Handlers[handlers<br/>Handler injection pattern<br/>implementation]
        Actions[actions<br/>Action dispatch<br/>callback functions]
        Subscriptions[hooks<br/>Store subscriptions<br/>computed values]
        Views[views<br/>Pure UI components]
    end

    %% UI Layer
    subgraph UI["UI Layer - views"]
        Page[Page - route]
        Layout[Layout - device Layer]
        Widget[Widget - design system]
    end

    %% Data Flow
    Store -->|State management| ContextDef
    ContextDef -->|Type definitions| Business
    Business -->|Pure functions| Handlers
    Handlers -->|Handler injection| Actions
    Actions -->|Action execution| Pipeline
    Pipeline -->|Pipeline execution| Store
    Store -->|Subscription| Subscriptions
    Subscriptions -->|Data transfer| Views
    Views -->|UI rendering| UI
    Actions -->|Action dispatch| Pipeline

    %% UI Mount Order
    Page -->|Mount| Layout
    Layout -->|Mount| Widget

Loading

🔄 Data Flow Principles

1. Context Share Layer (Provider)

   • Store: Centralized state management with reactive subscriptions
   • Actions/Pipeline: Business logic registration and execution order management
   • Ref: Singleton instance management for performance optimization

2. 6-Layer Hooks Structure (Consumer)

   • contexts: Resource type definitions and context access
   • business: Pure business logic functions separated from side effects
   • handlers: Handler injection pattern implementation with latest value access
   • actions: Action dispatch functions and callback management
   • hooks: Store subscriptions and computed values for reactive data
   • views: Pure UI components with minimal coupling

3. UI Layer (Views)

   • Page: Route-level components
   • Layout: Device-specific layout components
   • Widget: Design system components

⚡ Performance Benefits

• Delayed Evaluation: Handlers access latest state via store.getValue()
• Selective Subscriptions: Components subscribe only to needed state slices
• Minimal Re-renders: Optimized dependency tracking prevents unnecessary updates
• Singleton Management: Ref layer ensures efficient resource sharing

// 6-Layer Implementation Example
function UserPage() {
  // Layer 1: contexts - Resource type definitions
  const userStore = useUserStore('profile');

  // Layer 2: handlers - Internal function definitions
  const updateUserHandler = useCallback(async (payload) => {
    const currentUser = userStore.getValue(); // Delayed evaluation
    const updatedUser = { ...currentUser, ...payload };
    userStore.setValue(updatedUser);
  }, [userStore]);

  // Layer 3: subscriptions - Selective state subscriptions
  const user = useStoreValue(userStore);

  // Layer 4: registries - Handler registration
  useActionHandler('updateUser', updateUserHandler);

  // Layer 5: dispatchers - View-oriented action dispatchers
  const onUpdateUser = useActionDispatch('updateUser');

  return (
    <div>
      <h1>{user.name}</h1>
      <button onClick={() => onUpdateUser({ name: 'New Name' })}>
        Update User
      </button>
    </div>
  );
}

---

🔗 Type System Guidelines

Context-Action implements a sophisticated type system that provides full TypeScript safety across Action, Store, and Ref connections with zero runtime overhead.

🎯 Type Declaration Architecture

graph TB
    %% Type Declaration Layer
    subgraph TypeDeclarations["🔤 Type Declaration Layer"]
        PayloadMap[ActionPayloadMap<br/>Action payload type map]
        StoreTypes[StoreDefinitions<br/>Store type definitions]
        RefTypes[Ref Types<br/>Singleton reference types]
    end

    %% Context Creation Layer
    subgraph ContextCreation["⚙️ Context Creation Layer"]
        ActionContext[createActionContext&lt;T&gt;<br/>Action context creation]
        StoreContext[createStoreContext&lt;T&gt;<br/>Store context creation]
        RefManager[RefManager&lt;T&gt;<br/>Reference manager]
    end

    %% Hook Layer
    subgraph HookLayer["🪝 Hook Layer"]
        ActionHooks[useActionDispatch<br/>useActionHandler]
        StoreHooks[useStore<br/>useStoreValue]
        RefHooks[useRef<br/>useCallback]
    end

    %% Type Flow Connections
    PayloadMap -->|extends| ActionContext
    StoreTypes -->|initialStores| StoreContext
    RefTypes -->|singleton| RefManager

    ActionContext -->|typed hooks| ActionHooks
    StoreContext -->|typed hooks| StoreHooks
    RefManager -->|stable refs| RefHooks

    %% Type Safety Flow
    ActionHooks -->|type-safe dispatch| PayloadMap
    StoreHooks -->|reactive types| StoreTypes
    RefHooks -->|stable references| RefTypes

Loading

⚡ Type Connection Patterns

1. Action Type Declaration & Connection

// 1️⃣ Define Action Payload Types
interface UserActions extends ActionPayloadMap {
  updateProfile: { name: string; email: string; avatar?: File };
  deleteAccount: { confirmPassword: string };
  logout: void; // No payload
}

// 2️⃣ Create Typed Action Context
const {
  Provider: UserActionProvider,
  useActionDispatch: useUserAction,
  useActionHandler: useUserActionHandler
} = createActionContext<UserActions>('UserActions');

// 3️⃣ Type-Safe Handler Registration
function UserLogic() {
  // ✅ Payload automatically typed as { name: string; email: string; avatar?: File }
  useUserActionHandler('updateProfile', useCallback(async (payload) => {
    // payload.name ✅ string
    // payload.email ✅ string
    // payload.avatar ✅ File | undefined
    await updateUserAPI(payload);
  }, []));

  // ✅ Payload automatically typed as void
  useUserActionHandler('logout', useCallback(async () => {
    await clearSession();
  }, []));
}

// 4️⃣ Type-Safe Action Dispatching
function UserComponent() {
  const dispatch = useUserAction();

  return (
    <button onClick={() =>
      dispatch('updateProfile', {
        name: 'John',
        email: 'john@example.com'
        // ✅ TypeScript enforces correct payload shape
      })
    }>
      Update Profile
    </button>
  );
}

2. Store Type Declaration & Connection

// 1️⃣ Define Store Types (Two Approaches)

// Approach A: Simple Object Types
const { Provider, useStore } = createStoreContext('User', {
  profile: { name: '', email: '', isOnline: false }, // ✅ Type inferred
  settings: { theme: 'light' as const, notifications: true }, // ✅ const assertions
  preferences: { language: 'en', timezone: 'UTC' }
});

// Approach B: Explicit Store Configuration
interface UserStoreConfig {
  profile: StoreConfig<UserProfile>;
  settings: StoreConfig<UserSettings>;
  cache: StoreConfig<CacheData>; // ✅ With strategy configuration
}

const { Provider, useStore } = createStoreContext('User', {
  profile: { initialValue: { name: '', email: '' } },
  settings: { initialValue: { theme: 'light' }, strategy: 'shallow' },
  cache: { initialValue: new Map(), strategy: 'reference' }
} satisfies UserStoreConfig);

// 2️⃣ Type-Safe Store Access & Subscription
function UserProfile() {
  const profileStore = useStore('profile'); // ✅ Store<UserProfile>
  const profile = useStoreValue(profileStore); // ✅ UserProfile type

  // ✅ Type-safe store operations
  profileStore.setValue({ name: 'John', email: 'john@example.com', isOnline: true });
  profileStore.update(prev => ({ ...prev, isOnline: !prev.isOnline }));

  return <div>{profile.name}</div>; // ✅ profile.name is string
}

3. Ref Type Declaration & Singleton Management

// 1️⃣ Ref Type Declarations for Singleton Resources
interface AppRefs {
  apiClient: ApiClient;
  eventBus: EventBus;
  cache: LRUCache<string, any>;
}

// 2️⃣ Context with Ref Management
const {
  Provider: AppProvider,
  useStore,
  useRef: useAppRef
} = createStoreContext('App', {
  user: { name: '', email: '' },
  // ✅ Ref types managed alongside stores
}, {
  refs: {
    apiClient: () => new ApiClient(),
    eventBus: () => new EventBus(),
    cache: () => new LRUCache(1000)
  } as AppRefs
});

// 3️⃣ Type-Safe Ref Access
function ApiComponent() {
  const apiClient = useAppRef('apiClient'); // ✅ ApiClient type
  const userStore = useStore('user');

  const fetchUser = useCallback(async (id: string) => {
    // ✅ apiClient.get is typed method
    const userData = await apiClient.get(`/users/${id}`);
    userStore.setValue(userData);
  }, [apiClient, userStore]);

  return <button onClick={() => fetchUser('123')}>Fetch User</button>;
}

🛡️ Type Safety Benefits

Compile-Time Validation

• ✅ Action Payload Validation: Incorrect payload shapes caught at compile time
• ✅ Store Type Consistency: Store value types enforced across components
• ✅ Ref Type Stability: Singleton reference types maintained across re-renders
• ✅ Hook Return Types: All hooks return properly typed values and functions

IntelliSense & Developer Experience

• 🔍 Auto-completion: Full IntelliSense for action names, payload properties, store keys
• 🏷️ Type Hints: Hover information shows exact payload and store types
• ⚠️ Error Prevention: TypeScript prevents runtime errors before they happen
• 🔄 Refactoring Safety: Type-safe refactoring across the entire codebase

Zero Runtime Overhead

• ⚡ Compile-Time Only: All type information removed in production builds
• 📦 No Type Libraries: No runtime type checking dependencies
• 🎯 Direct Performance: Types guide optimization without runtime cost

📚 Detailed Type System Documentation

For comprehensive type system coverage, see our dedicated guides:

English Documentation

• 📖 TypeScript Type Inference Guide - Complete type inference overview
• 🎯 Action Type System - ActionPayloadMap, pipeline controllers, and handler types
• 🔧 Advanced Type Features - Branded types, conditional processing, and utilities
• 🛡️ Type Safety Best Practices - Essential recommendations and patterns

Korean Documentation

• 🎯 Action Type System - ActionPayloadMap, type safety, TypeScript integration

Core Type System Features

• Action Type Safety: Complete ActionPayloadMap interface with pipeline controller types
• Store Type Inference: Automatic type inference from initial values with strategy support
• Handler Configuration: Type-safe handler registration with comprehensive options
• Integration Patterns: Store integration, async handling, and error management
• Advanced Features: Conditional types, branded types, and generic utilities

---

📋 API Reference

Core Functions

createStoreContext(name, stores)

Create typed store context with reactive subscriptions.

const { Provider, useStore } = createStoreContext('App', {
  user: { name: '', email: '' },
  settings: { theme: 'light' }
});

createActionContext<T>(name)

Create typed action context with pipeline processing.

interface Actions extends ActionPayloadMap {
  update: { id: string };
}
const { Provider, useActionDispatch } = createActionContext<Actions>('App');

Essential Hooks

useStoreValue(store)

Subscribe to store changes with automatic re-renders.

const userStore = useStore('user');
const user = useStoreValue(userStore); // Reactive subscription

useActionHandler(action, handler)

Register business logic handlers for actions.

const updateProfileHandler = useCallback(async (payload) => {
  // Business logic here
}, []);

useActionHandler('updateProfile', updateProfileHandler);

useActionDispatch()

Dispatch actions to the pipeline.

const dispatch = useActionDispatch();
dispatch('updateProfile', { name: 'John', email: 'john@example.com' });

---

🎮 Examples & Demos

🚀 Live Interactive Examples

Explore 20+ working examples →

🏪 Store System

• Store Basics - Fundamental operations
• Store Full Demo - Complex state management
• Declarative Pattern - Type-safe patterns

🎯 Action System

• Core Features - Pipeline fundamentals
• Action Guards - Advanced filtering
• Priority System - Performance optimization

🔗 MVVM Architecture

• Unified Pattern - Complete MVVM demo
• Enhanced Context - Advanced patterns

📖 Real-World Examples

// E-commerce Cart System
const CartStores = createStoreContext('Cart', {
  items: [] as CartItem[],
  total: 0,
  shipping: { method: 'standard', cost: 0 }
});

// User Management System  
interface UserActions extends ActionPayloadMap {
  login: { email: string; password: string };
  updateProfile: Partial<UserProfile>;
  logout: void;
}

🔍 New in v0.7.0: Enhanced LogMonitor Documentation

• 📊 Logger System Demo - Interactive LogMonitor showcase
• Real-time log collection - Live demo with practical examples
• Integration patterns - Parent/Child handler implementations
• Dependency warnings - Avoid infinite loops with best practices

---

🏗️ Architecture

Context-Action Framework implements multiple architectural approaches for different application needs:

📐 Context-Driven Architecture

Context-Driven Architecture - Core frontend architecture for clear document-based separation

Philosophy: "The document is the architecture" - Each context exists as a unit for managing documents and deliverables of its domain.

Key Features:

• Document-Centric Context Separation: Clear boundaries between domain contexts
• 6-Layer Hooks Architecture: Provider/Consumer pattern with delayed evaluation
• Domain Context Isolation: Business, UI, Validation, Design, Architecture contexts
• Effective Artifact Management: State management supporting document-deliverable relationships

🔧 Implementation Guides

• Context-Layered Architecture - Practical 6-layer implementation guide
• Folder Structure Guide - Organized project structure
• Handler Registry Management - ID and priority management

---

📚 Documentation

📖 Complete Guides

• 📚 Official Documentation - Complete API reference
• 🚀 Getting Started Guide - 5-minute setup
• 🏗️ MVVM Core Architecture - Practical MVVM implementation guide
• 📋 Architecture Overview - Framework concepts
• ⚡ Best Practices - Production patterns

🌏 Multi-Language Support

• 🇺🇸 English Documentation - Complete English guides
• 🇰🇷 Korean Documentation - Complete Korean guide

---

📦 Packages

@context-action/core

Pure TypeScript action pipeline - Framework agnostic core

npm install @context-action/core

• 🔒 Full TypeScript support
• ⚡ Action pipeline system
• 🛡️ Advanced action guards
• 🚫 Zero dependencies

@context-action/react

React integration - Complete MVVM architecture

npm install @context-action/react

• 🏪 Declarative store patterns
• 🎯 Action context integration
• 🪝 Advanced React hooks
• 🏗️ HOC support

---

🛠️ Development

Quick Development Setup

git clone https://github.com/mineclover/context-action.git
cd context-action
pnpm install
pnpm dev  # Start example app

Project Resources

• 🤝 Contributing Guide - How to contribute
• 🌐 Ecosystem - Tools and generators
• 🛠️ Development Guide - Detailed development setup

---

📄 License

Apache-2.0 © mineclover

---

Built with ❤️ for modern TypeScript applications

⭐ Star on GitHub • 🐛 Report Bug • 💡 Request Feature