react-state-custom 1.0.16 → 1.0.19

package/README.md

@@ -1,197 +1,320 @@
-# React State Custom - Documentation
+# React State Custom
 
-Welcome to the comprehensive documentation for the `react-state-custom` library!
+**Simple. Powerful. TypeScript-first.**
 
-## 📚 Documentation Files
-
-- **[API_DOCUMENTATION.md](./API_DOCUMENTATION.md)** - Complete API reference with examples for all exported functions, hooks, and classes
-
-## 🚀 Quick Start
+A lightweight React state management library that combines the simplicity of React hooks with the power of event-driven subscriptions. No boilerplate, no complexity—just pure, performant state management.
 
 ```bash
 npm install react-state-custom
 ```
 
-## 📖 What's Inside
+## Why React State Custom?
 
-The `react-state-custom` library provides a powerful set of tools for managing shared state in React applications:
+**Zero Boilerplate** • **Type-Safe** • **Selective Re-renders** • **Hook-Based** • **~10KB Bundle**
 
-### Core Features
+React State Custom lets you write state management code that feels natural—because it **is** just React hooks. Use the same hooks you already know (`useState`, `useEffect`, etc.) to create powerful, shared state without learning new paradigms.
 
-- **Context System** - Type-safe context management with event-driven subscriptions
-- **Root Context Factory** - Automated context lifecycle management
-- **Auto Context System** - Self-managing context instances
-- **Utility Hooks** - Performance optimization tools
+## ⚡ Quick Example
 
-### Key Benefits
+```typescript
+import { createRootCtx, createAutoCtx, useQuickSubscribe, AutoRootCtx } from 'react-state-custom';
 
-- ✅ **Type Safety** - Full TypeScript support with strong typing
-- ✅ **Performance** - Only re-renders when subscribed data changes
-- ✅ **Flexibility** - Works with any data structure
-- ✅ **Developer Experience** - Rich debugging and error checking
-- ✅ **Minimal Boilerplate** - Automated context management
+// 1. Write your state logic using familiar React hooks
+function useCounterState() {
+  const [count, setCount] = useState(0);
+  const increment = () => setCount(c => c + 1);
+  const decrement = () => setCount(c => c - 1);
+  
+  return { count, increment, decrement };
+}
 
-## 📝 Documentation Structure
+// 2. Create shared context (one line!)
+const { useCtxState } = createAutoCtx(createRootCtx('counter', useCounterState));
 
-The [API Documentation](./API_DOCUMENTATION.md) is organized into the following sections:
+// 3. Add AutoRootCtx to your app root
+function App() {
+  return (
+    <>
+      <AutoRootCtx />
+      <Counter />
+    </>
+  );
+}
 
-1. **Core Context System** - Basic context functionality
-2. **Data Source Hooks** - Publishing data to contexts
-3. **Data Subscription Hooks** - Subscribing to context changes
-4. **Root Context Factory** - Advanced context patterns
-5. **Auto Context System** - Automated context management
-6. **Utility Hooks** - Performance and utility functions
-7. **Usage Patterns** - Common implementation patterns
-8. **Examples** - Complete application examples
+// 4. Use anywhere in your app
+function Counter() {
+  const ctx = useCtxState();
+  const { count, increment, decrement } = useQuickSubscribe(ctx);
+  
+  return (
+    <div>
+      <h1>{count}</h1>
+      <button onClick={increment}>+</button>
+      <button onClick={decrement}>-</button>
+    </div>
+  );
+}
+```
 
-## 🎯 Common Use Cases
+**That's it!** No reducers, no actions, no providers to wrap—just hooks.
 
-- **Global State Management** - Application-wide state without Redux complexity
-- **Component Communication** - Share data between distant components
-- **Performance Optimization** - Minimize unnecessary re-renders
-- **Context Composition** - Combine multiple contexts efficiently
+## 🎯 Key Features
 
-## 🔧 Quick Example
+### 1. **Just React Hooks**
+Use `useState`, `useEffect`, `useMemo`, and any other React hooks you already know. No new concepts to learn.
 
 ```typescript
-import { useDataContext, useDataSource, useDataSubscribe } from 'react-state-custom';
-
-interface AppState {
-  user: User | null;
-  theme: 'light' | 'dark';
-}
-
-// Provider component
-function AppProvider({ children }) {
-  const ctx = useDataContext<AppState>('app-state');
-  const user = useCurrentUser();
-  const theme = useTheme();
+function useUserState({ userId }: { userId: string }) {
+  const [user, setUser] = useState(null);
+  const [loading, setLoading] = useState(true);
   
-  useDataSource(ctx, 'user', user);
-  useDataSource(ctx, 'theme', theme);
+  useEffect(() => {
+    fetchUser(userId).then(setUser).finally(() => setLoading(false));
+  }, [userId]);
   
-  return <>{children}</>;
+  return { user, loading };
 }
+```
 
-// Consumer component
-function UserProfile() {
-  const ctx = useDataContext<AppState>('app-state');
-  const user = useDataSubscribe(ctx, 'user');
-  
-  return <div>Hello, {user?.name}</div>;
-}
+### 2. **Selective Re-renders**
+Components only re-render when the **specific data they subscribe to** changes—not when anything in the state changes.
+
+```typescript
+// Only re-renders when 'user' changes, not when 'loading' changes
+const { user } = useDataSubscribeMultiple(ctx, 'user');
+
+// Or subscribe to multiple fields
+const { user, loading } = useDataSubscribeMultiple(ctx, 'user', 'loading');
 ```
 
-## 🔧 Additional Examples
+### 3. **Automatic Context Management**
+With `AutoRootCtx`, state contexts are automatically created and destroyed as needed. No manual provider management.
 
-### Using createRootCtx for Advanced State Management
+### 4. **TypeScript First**
+Full type inference and type safety throughout. Your IDE knows exactly what's in your state.
 
-```typescript
-import { createRootCtx, useDataSubscribeMultiple } from 'react-state-custom';
+### 5. **Tiny Bundle Size**
+~10KB gzipped. No dependencies except React.
 
-interface UserState {
-  user: User | null;
-  loading: boolean;
-  error: string | null;
-}
+## 🆚 Comparison with Redux & Zustand
+
+| Feature | React State Custom | Redux | Zustand |
+|---------|-------------------|-------|---------|
+| **Bundle Size** | ~10KB | ~50KB (with toolkit) | ~1KB |
+| **Learning Curve** | ✅ Minimal (just hooks) | ❌ High (actions, reducers, middleware) | ✅ Low |
+| **Boilerplate** | ✅ None | ❌ Heavy | ✅ Minimal |
+| **Type Safety** | ✅ Full inference | ⚠️ Requires setup | ✅ Good |
+| **Selective Re-renders** | ✅ Built-in | ⚠️ Requires selectors | ✅ Built-in |
+| **DevTools** | ⚠️ Console logging | ✅ Redux DevTools | ✅ DevTools support |
+| **Async Support** | ✅ Native (hooks) | ⚠️ Requires middleware | ✅ Native |
+| **Context Composition** | ✅ Automatic | ❌ Manual | ⚠️ Manual store combination |
+
+### When to Use React State Custom
+
+✅ **Choose React State Custom if you:**
+- Want to use React hooks for state management without learning new patterns
+- Need fine-grained control over component re-renders
+- Prefer minimal boilerplate and configuration
+- Want automatic context lifecycle management
+- Need multiple independent state contexts that don't interfere
+
+❌ **Consider Redux if you:**
+- Need powerful time-travel debugging (Redux DevTools)
+- Have a very large team that benefits from strict architectural patterns
+- Already have significant Redux investment
+
+❌ **Consider Zustand if you:**
+- Want the absolute smallest bundle size
+- Need a simple global store without context isolation
+- Don't need automatic context lifecycle management
 
-// Create a state hook
-function useUserState(props: { userId: string }) {
+## 🔥 Real-World Example: User Authentication
+
+```typescript
+// authState.ts
+function useAuthState() {
   const [user, setUser] = useState<User | null>(null);
   const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
   
   useEffect(() => {
-    fetchUser(props.userId).then(setUser).catch(setError).finally(() => setLoading(false));
-  }, [props.userId]);
+    // Check authentication on mount
+    checkAuth().then(setUser).finally(() => setLoading(false));
+  }, []);
+  
+  const login = async (email: string, password: string) => {
+    setLoading(true);
+    try {
+      const user = await authService.login(email, password);
+      setUser(user);
+    } finally {
+      setLoading(false);
+    }
+  };
   
-  return { user, loading, error };
+  const logout = async () => {
+    await authService.logout();
+    setUser(null);
+  };
+  
+  return { user, loading, login, logout };
 }
 
-// Create root context factory
-const { Root: UserRoot, useCtxState: useUserCtxState } = createRootCtx(
-  'user-state',
-  useUserState
+export const { useCtxState: useAuthState } = createAutoCtx(
+  createRootCtx('auth', useAuthState)
 );
 
-// Provider component
-function UserProvider({ userId, children }: { userId: string; children: React.ReactNode }) {
+// App.tsx
+function App() {
   return (
     <>
-      <UserRoot userId={userId} />
-      {children}
+      <AutoRootCtx />
+      <Router>
+        <Header />
+        <Routes />
+      </Router>
     </>
   );
 }
 
-// Consumer component using useDataSubscribeMultiple
-function UserProfile({ userId }: { userId: string }) {
-  const ctx = useUserCtxState({ userId });
-  const { user, loading, error } = useDataSubscribeMultiple(ctx, 'user', 'loading', 'error');
+// Header.tsx - Only re-renders when user changes
+function Header() {
+  const ctx = useAuthState();
+  const { user, logout } = useQuickSubscribe(ctx);
   
-  if (loading) return <div>Loading user...</div>;
-  if (error) return <div>Error: {error}</div>;
+  return (
+    <header>
+      {user ? (
+        <>
+          <span>Welcome, {user.name}</span>
+          <button onClick={logout}>Logout</button>
+        </>
+      ) : (
+        <Link to="/login">Login</Link>
+      )}
+    </header>
+  );
+}
+
+// ProtectedRoute.tsx - Only re-renders when loading or user changes
+function ProtectedRoute({ children }) {
+  const ctx = useAuthState();
+  const { user, loading } = useDataSubscribeMultiple(ctx, 'user', 'loading');
+  
+  if (loading) return <Spinner />;
+  if (!user) return <Navigate to="/login" />;
   
-  return <div>Welcome, {user?.name}!</div>;
+  return children;
 }
 ```
 
-### Using useQuickSubscribe for Simplified Access
+**Compare with Redux:**
+```typescript
+// Redux requires: action types, action creators, reducers, thunks/sagas
+// React State Custom: just write a hook! ✨
+```
 
+## 📚 Core Concepts
+
+### 1. **Context** - Event-driven state container
+```typescript
+const ctx = useDataContext<MyState>('my-state');
+```
+
+### 2. **Data Source** - Publish values to context
+```typescript
+useDataSource(ctx, 'count', count);
+```
+
+### 3. **Data Subscription** - Subscribe to specific values
+```typescript
+const count = useDataSubscribe(ctx, 'count');
+const { count, name } = useDataSubscribeMultiple(ctx, 'count', 'name');
+```
+
+### 4. **Root Context** - Lifecycle-managed context
+```typescript
+const { Root, useCtxState } = createRootCtx('my-state', useMyState);
+```
+
+### 5. **Auto Context** - Automatic instance management
 ```typescript
-import { useDataContext, useQuickSubscribe } from 'react-state-custom';
+const { useCtxState } = createAutoCtx(rootContext);
+```
 
-interface SettingsState {
-  theme: 'light' | 'dark';
-  language: string;
-  notifications: boolean;
-  updateSetting: (key: string, value: any) => void;
+## 🚀 Advanced Features
+
+### Parameterized Contexts
+Create multiple instances of the same state with different parameters:
+
+```typescript
+function useUserState({ userId }: { userId: string }) {
+  // State logic here
 }
 
-// Component using useQuickSubscribe for easy property access
-function SettingsPanel() {
-  const ctx = useDataContext<SettingsState>('settings');
-  
-  // useQuickSubscribe automatically subscribes to accessed properties
-  const { theme, language, notifications, updateSetting } = useQuickSubscribe(ctx);
-  
-  return (
-    <div className={`settings-panel ${theme}`}>
-      <h2>Settings</h2>
-      
-      <label>
-        Theme:
-        <select value={theme} onChange={(e) => updateSetting('theme', e.target.value)}>
-          <option value="light">Light</option>
-          <option value="dark">Dark</option>
-        </select>
-      </label>
-      
-      <label>
-        Language:
-        <input 
-          value={language} 
-          onChange={(e) => updateSetting('language', e.target.value)} 
-        />
-      </label>
-      
-      <label>
-        <input 
-          type="checkbox" 
-          checked={notifications} 
-          onChange={(e) => updateSetting('notifications', e.target.checked)} 
-        />
-        Enable notifications
-      </label>
-    </div>
-  );
+const { useCtxState: useUserState } = createAutoCtx(
+  createRootCtx('user', useUserState)
+);
+
+// Different instances for different users
+function UserProfile({ userId }) {
+  const ctx = useUserState({ userId }); // Automatic instance per userId
+  const { user } = useQuickSubscribe(ctx);
+  return <div>{user?.name}</div>;
 }
 ```
 
+### Debounced Subscriptions
+Optimize performance for frequently changing values:
+
+```typescript
+// Re-render at most once per 300ms
+const searchQuery = useDataSubscribe(ctx, 'searchQuery', 300);
+```
+
+### Transformed Subscriptions
+Transform data before using it:
+
+```typescript
+const userStats = useDataSubscribeWithTransform(
+  ctx,
+  'user',
+  (user) => ({
+    fullName: `${user?.firstName} ${user?.lastName}`,
+    isAdmin: user?.role === 'admin'
+  })
+);
+```
+
+## 📖 Documentation
+
+For complete API documentation, examples, and advanced patterns, see:
+- **[API_DOCUMENTATION.md](./API_DOCUMENTATION.md)** - Complete API reference
+
+## 🎓 Learning Path
+
+1. **Start Simple** - Use `createRootCtx` + `createAutoCtx` for basic state
+2. **Add Subscriptions** - Use `useDataSubscribeMultiple` for selective re-renders
+3. **Optimize** - Add debouncing and transformations as needed
+4. **Scale** - Create parameterized contexts for dynamic instances
+
+## 📦 Installation
+
+```bash
+npm install react-state-custom
+# or
+yarn add react-state-custom
+# or
+pnpm add react-state-custom
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
 ## 📄 License
 
-MIT License - see the main repository for details.
+MIT License - feel free to use in any project.
 
 ---
 
-For the complete API reference with detailed examples, see [API_DOCUMENTATION.md](./API_DOCUMENTATION.md).
+**Made with ❤️ for developers who love React hooks**