native-document 1.0.15 → 1.0.16-8.1

package/docs/state-management.md

@@ -1,15 +1,15 @@
-# State Management
-
-NativeDocument's state management system provides tools for managing application-wide state that persists across components and route changes. The Store system enables shared state with reactive updates, while Observables handle local component state.
+---
+title: State Management
+description: Manage application-wide state with NativeDocument's Store system - groups, persistence, computed stores, and reactive updates
+---
 
-## Understanding State Management
+# State Management
 
-State management in NativeDocument operates on two levels: local component state using Observables, and global application state using the Store system. The Store allows multiple components to share and react to the same state changes.
+NativeDocument's state management operates on two levels: local component state using Observables, and global application state using the Store system. The Store allows multiple components to share and react to the same state changes.
 
 ```javascript
 import { Store, Observable } from 'native-document';
 
-// Create global state
 const userStore = Store.create('user', {
     id: null,
     name: '',
@@ -17,407 +17,314 @@ const userStore = Store.create('user', {
     isLoggedIn: false
 });
 
-// Components automatically update when store changes
 const UserGreeting = () => {
     const user = Store.use('user');
-    
-    return ShowIf(user.check(u => u.isLoggedIn),
+    return ShowIf(user.is(u => u.isLoggedIn),
         () => Div(['Welcome back, ', user.$value.name, '!'])
     );
 };
 ```
 
-## Store Creation
+---
 
-Create named stores that can be accessed from anywhere in your application:
+## Store Creation
 
-### Basic Store Creation
+### `Store.create(name, initialValue)`
 
 ```javascript
-// Create a simple store
-const themeStore = Store.create('theme', 'light');
+Store.create('theme', 'light');
 
-// Create an object store
-const appStore = Store.create('app', {
+Store.create('app', {
     currentPage: 'home',
     sidebarOpen: false,
     notifications: []
 });
-
-// Create with initial complex data
-const cartStore = Store.create('cart', {
-    items: [],
-    total: 0,
-    currency: 'USD',
-    discountCode: null
-});
 ```
 
-### Store with Computed Values
+### `Store.createResettable(name, initialValue)`
+
+Use when the store needs to return to its initial value - for example on logout or route change:
 
 ```javascript
-const cartStore = Store.create('cart', {
-    items: [],
-    taxRate: 0.08
+const userStore = Store.createResettable('user', {
+    id: null,
+    name: '',
+    email: '',
+    isLoggedIn: false
 });
 
-// Computed total that updates automatically
-const cartTotal = Observable.computed(() => {
-    const cart = cartStore.$value;
-    const subtotal = cart.items.reduce((sum, item) => sum + (item.price * item.quantity), 0);
-    const tax = subtotal * cart.taxRate;
-    return subtotal + tax;
-}, [cartStore]);
-```
+Store.reset('user');
+// -> { id: null, name: '', email: '', isLoggedIn: false }
+// -> all subscribers are notified automatically
 
-## Using Stores
+// Standard create() does not support reset
+Store.reset('theme'); // throws - this store is not resettable
+```
 
-Access and react to store changes using Store.use() or Store.follow():
+### `Store.createComposed(name, fn, deps)`
 
-### Store.use() - Primary Access Method
+For a computed value accessible globally via the Store registry:
 
 ```javascript
-const UserProfile = () => {
-    // Get reactive reference to store
-    const user = Store.use('user');
-    
-    return Div([
-        H1(['User Profile: ', user.check(u => u.name)]),
-        P(['Email: ', user.check(u => u.email)]),
-        P(['Status: ', user.check(u => u.isLoggedIn ? 'Online' : 'Offline')])
-    ]);
-};
-
-// Multiple components can use the same store
-const UserMenu = () => {
-    const user = Store.use('user');
-    
-    return Nav([
-        ShowIf(user.check(u => u.isLoggedIn), [
-            Link({ to: '/profile' }, 'My Profile'),
-            Button('Logout').nd.onClick(() => {
-                user.set({ ...user.$value, isLoggedIn: false });
-            })
-        ])
-    ]);
-};
+Store.create('products', [{ id: 1, price: 10 }]);
+Store.create('cart',     [{ productId: 1, quantity: 2 }]);
+
+Store.createComposed('total', () => {
+    const products = Store.get('products').val();
+    const cart     = Store.get('cart').val();
+    return cart.reduce((sum, item) => {
+        const product = products.find(p => p.id === item.productId);
+        return sum + (product.price * item.quantity);
+    }, 0);
+}, ['products', 'cart']);
+
+const total = Store.follow('total');
+total.val(); // 20
+
+// Store.use('total')  -> throws - composed stores are read-only
+// Store.reset('total') -> throws - composed stores cannot be reset
 ```
 
-### Store.follow() - Alternative Access
+For a computed value that stays local to a component, use `Observable.computed()` instead - see [Observables](./observables.md).
 
-```javascript
-const NotificationBadge = () => {
-    // Follow is alias for use
-    const notifications = Store.follow('notifications');
-    
-    return ShowIf(notifications.check(list => list.length > 0),
-        () => Span({ class: 'badge' }, notifications.$value.length)
-    );
-};
-```
+### `Store.createPersistent(name, initialValue, storageKey?)`
 
-## Updating Store State
+Automatically saved to localStorage on every change and restored on page load:
 
-Modify store state using the returned observable's methods:
+```javascript
+Store.createPersistent('theme', 'light');
+Store.get('theme').set('dark'); // saved automatically
 
-### Direct Updates
+// On next page load
+Store.get('theme').val(); // "dark" - restored
 
-```javascript
-const ThemeToggle = () => {
-    const theme = Store.use('theme');
-    
-    return Button('Toggle Theme').nd.onClick(() => {
-        const current = theme.$value;
-        theme.set(current === 'light' ? 'dark' : 'light');
-    });
-};
+// Optional custom localStorage key
+Store.createPersistent('theme', 'light', 'app:theme');
 ```
 
-### Object Store Updates
+### `Store.createPersistentResettable(name, initialValue, storageKey?)`
+
+Both persistent and resettable. Reset clears localStorage and restores the default:
 
 ```javascript
-const LoginForm = () => {
-    const user = Store.use('user');
-    const email = Observable('');
-    const password = Observable('');
-    
-    const handleLogin = () => {
-        // Update multiple properties
-        user.set({
-            ...user.$value,
-            email: email.$value,
-            isLoggedIn: true,
-            name: 'User Name' // This would come from API
-        });
-    };
-    
-    return Form([
-        Input({ type: 'email', value: email, placeholder: 'Email' }),
-        Input({ type: 'password', value: password, placeholder: 'Password' }),
-        Button('Login').nd.onClick(handleLogin)
-    ]);
-};
+const session = Store.createPersistentResettable('session', { id: null, name: '' });
+session.set({ id: 1, name: 'John' }); // saved
+
+Store.reset('session');
+// -> { id: null, name: '' }
+// -> localStorage entry removed
 ```
 
-### Partial Updates
+---
+
+## Store Groups
+
+`Store.group()` creates an isolated namespace. Each group is a fully independent `StoreFactory` instance - no key conflicts, no shared state with the parent store:
 
 ```javascript
-const UserSettings = () => {
-    const user = Store.use('user');
-    
-    const updateName = (newName) => {
-        // Only update specific fields
-        user.set({
-            ...user.$value,
-            name: newName
-        });
-    };
-    
-    const updatePreferences = (prefs) => {
-        user.set({
-            ...user.$value,
-            preferences: {
-                ...user.$value.preferences,
-                ...prefs
-            }
+const EventStore = Store.group('events', (group) => {
+    group.create('catalog', []);
+    group.create('filters', { category: null, date: null, city: null });
+    group.createResettable('selected', null);
+
+    group.createComposed('filtered', () => {
+        const catalog = EventStore.get('catalog').val();
+        const filters = EventStore.get('filters').val();
+        return catalog.filter(event => {
+            if (filters.category && event.category !== filters.category) return false;
+            if (filters.city     && event.city     !== filters.city)     return false;
+            return true;
         });
-    };
-    
-    return Div([
-        Input({ 
-            value: user.check(u => u.name),
-            placeholder: 'Name'
-        }).nd.onInput(e => updateName(e.target.value)),
-        
-        Button('Dark Mode').nd.onClick(() => 
-            updatePreferences({ theme: 'dark' })
-        )
-    ]);
-};
-```
+    }, ['catalog', 'filters']);
+});
 
-## Store Access Patterns
+// Same API as Store
+EventStore.use('catalog');      // two-way follower
+EventStore.follow('filtered');  // read-only follower
+EventStore.get('filters');      // raw observable
 
-### Direct Store Access
+// Direct property access - raw observable, always read-only
+EventStore.catalog;
+EventStore.filters;
+```
 
-```javascript
-// Get store reference without reactivity
-const userStore = Store.get('user');
+Groups can reference each other in `createComposed()`:
 
-// Check current value
-if (userStore.$value.isLoggedIn) {
-    console.log('User is logged in');
-}
+```javascript
+const CartStore = Store.group('cart', (group) => {
+    group.create('items', []);
+    group.createComposed('total', () => {
+        return CartStore.get('items').val()
+            .reduce((sum, item) => sum + item.price * item.qty, 0);
+    }, ['items']);
+});
 
-// Subscribe to changes manually
-userStore.subscribe(newUser => {
-    console.log('User changed:', newUser);
+const OrderStore = Store.group('orders', (group) => {
+    group.createComposed('summary', () => ({
+        items:  CartStore.get('items').val(),
+        events: EventStore.get('catalog').val()
+    }), [CartStore.get('items'), EventStore.get('catalog')]);
 });
 ```
 
-## Real-World Examples
-
-## Store Cleanup
+Groups can be created without a name:
 
-Properly clean up stores when they're no longer needed:
+```javascript
+const CartStore = Store.group((group) => {
+    group.create('items', []);
+});
+```
 
-### Manual Cleanup
+Use groups to organize state by domain:
 
 ```javascript
-// Remove store and all its subscribers
-Store.delete('temporaryStore');
-
-// Clean up specific subscriber
-const userStore = Store.use('user');
-userStore.destroy(); // Clean up this subscriber instance
+// Good - domain-driven grouping
+const UserStore  = Store.group('user',   g => g.create('session', null));
+const EventStore = Store.group('events', g => g.create('catalog', []));
+const CartStore  = Store.group('cart',   g => g.create('items', []));
+
+// Avoid - flat global stores for everything
+Store.create('userSession',  null);
+Store.create('eventCatalog', []);
+Store.create('cartItems',    []);
 ```
 
-## Performance Considerations
+---
+
+## Accessing Stores
 
-### Efficient Store Updates
+### `Store.use(name)` - Two-way reactive
+
+Returns a reactive reference. The observable's `.set()` method is inherited from `Observable` - any change notifies all subscribers:
 
 ```javascript
-// Good: Batch related updates
-const updateUserProfile = (name, email, preferences) => {
+const UserProfile = () => {
     const user = Store.use('user');
-    user.set({
-        ...user.$value,
-        name,
-        email,
-        preferences: {
-            ...user.$value.preferences,
-            ...preferences
-        }
-    });
-};
 
-// Less efficient: Multiple separate updates
-const updateUserProfileSlow = (name, email, preferences) => {
-    const user = Store.use('user');
-    user.set({ ...user.$value, name });        // Triggers update
-    user.set({ ...user.$value, email });       // Triggers update
-    user.set({ ...user.$value, preferences }); // Triggers update
+    return Div([
+        H1(['User Profile: ', user.select(u => u.name)]),
+        P(['Email: ', user.select(u => u.email)]),
+        P(['Status: ', user.format(u => u.isLoggedIn ? 'Online' : 'Offline')])
+    ]);
 };
 ```
 
-### Selective Subscriptions
+### `Store.follow(name)` - Read-only reactive
+
+Any attempt to call `.set()`, `.toggle()`, or `.reset()` throws a `NativeDocumentError`:
 
 ```javascript
-// Subscribe to specific parts of store
-const UserName = () => {
-    const user = Store.use('user');
-    
-    // Only re-render when name changes
-    const userName = user.check(u => u.name);
-    
-    return Span(userName);
-};
+const NotificationBadge = () => {
+    const notifications = Store.follow('notifications');
+    // notifications.set(...) -> throws NativeDocumentError
 
-// More efficient than re-rendering entire user profile
-// when only name is needed
+    return ShowIf(notifications.isNotEmpty(),
+        () => Span({ class: 'badge' }, notifications.toLength())
+    );
+};
 ```
 
-## Best Practices
+### `Store.get(name)` - Raw observable
 
-### 1. Use Descriptive Store Names
+Returns the raw store observable directly - no follower, no cleanup contract:
 
 ```javascript
-// Good: Clear, descriptive names
-const userAuthStore = Store.create('userAuth', defaultUser);
-const shoppingCartStore = Store.create('shoppingCart', defaultCart);
-const appSettingsStore = Store.create('appSettings', defaultSettings);
-
-// Less clear: Generic names
-const store1 = Store.create('data', {});
-const state = Store.create('state', {});
-```
+const userStore = Store.get('user');
 
-### 2. Initialize with Complete Data Structures
+if (userStore.$value.isLoggedIn) {
+    console.log('User is logged in');
+}
 
-```javascript
-// Good: Complete initial structure
-const userStore = Store.create('user', {
-    id: null,
-    name: '',
-    email: '',
-    preferences: {
-        theme: 'light',
-        notifications: true
-    },
-    isLoggedIn: false
+userStore.subscribe(newUser => {
+    console.log('User changed:', newUser);
 });
-
-// Problematic: Incomplete structure
-const userStore = Store.create('user', {});
-// Later code might fail when accessing user.preferences.theme
 ```
 
-### 3. Create Service Objects for Complex Operations
+> Mutations on a raw observable from `Store.get()` impact all subscribers immediately.
 
-```javascript
-// Good: Organized actions
-const AuthService= (function() {
-    const authUser = Store.create('user', {});
-  
-    return {
-        login: (credentials) => { /* ... */ },
-        logout: () => { /* ... */ },
-        updateProfile: (data) => { /* ... */ },
-        updatePreferences: (prefs) => { /* ... */ }
-    };
-}());
-
-// Instead of scattered update logic throughout components
-```
+### Direct property access
 
-### 4. Use Store for Cross-Component State Only
+Stores and groups expose their observables as direct properties via a Proxy - equivalent to `Store.get()`:
 
 ```javascript
-// Good: Local state for component-specific data
-const ContactForm = () => {
-    const name = Observable('');     // Local state
-    const email = Observable('');    // Local state
-    const user = Store.use('user');  // Global state
-    
-    return Form([/* ... */]);
-};
+EventStore.catalog;  // same as EventStore.get('catalog')
 
-// Avoid: Putting everything in stores
-// Don't store form input state globally unless shared
+// Assignment and deletion are forbidden
+EventStore.catalog = [];    // throws - Store structure is immutable
+delete EventStore.catalog;  // throws - Store keys cannot be deleted
 ```
 
-## Debugging Stores
+---
+
+## Updating Store State
 
-### Store State Inspection
+`.set()` is inherited from `Observable` and works the same way:
 
 ```javascript
-// Log current store state
-console.log('Current user:', Store.get('user').$value);
+// Direct value
+const theme = Store.use('theme');
+theme.set('dark');
+theme.toggle(); // for boolean stores
+
+// Function update
+const counter = Store.use('counter');
+counter.set(current => current + 1);
+
+// Object spread
+const user = Store.use('user');
+user.set({ ...user.$value, name: 'Alice', isLoggedIn: true });
+```
 
-// Monitor store changes
-Store.get('user').subscribe(newUser => {
-    console.log('User changed:', newUser);
-});
+---
 
-// Check all followers of a store
-const userData = Store.getWithSubscribers('user');
-console.log('Store value:', userData.observer.$value);
-console.log('Followers count:', userData.subscribers.size);
-```
+## Other Store Methods
 
-## Common Patterns
+### `Store.has(name)`
 
-### Persistent Store
+Check if a store exists before accessing it:
 
 ```javascript
-const createPersistentStore = (name, defaultValue, storageKey) => {
-    // Load from localStorage
-    const saved = localStorage.getItem(storageKey);
-    const initialValue = saved ? JSON.parse(saved) : defaultValue;
-    
-    const store = Store.create(name, initialValue);
-    
-    // Save changes to localStorage
-    store.subscribe(newValue => {
-        localStorage.setItem(storageKey, JSON.stringify(newValue));
-    });
-    
-    return store;
-};
+if (Store.has('cart')) {
+    const cart = Store.use('cart');
+}
 
-// Usage
-createPersistentStore('userPreferences', {
-    theme: 'light',
-    language: 'en'
-}, 'app_preferences');
+// Typical use: dynamic module initialization
+if (!Store.has('cart')) {
+    Store.create('cart', { items: [], total: 0 });
+}
 ```
 
-### Store Composition
+### `Store.delete(name)`
+
+Destroys a store - cleans up all followers and the observable, then removes it from the registry:
 
 ```javascript
-// Combine multiple stores for complex state
-const createAppState = () => {
-    const auth = Store.create('auth', defaultAuth);
-    const cart = Store.create('cart', defaultCart);
-    const settings = Store.create('settings', defaultSettings);
-    
-    // Computed store that combines others
-    const appStatus = Observable.computed(() => {
-        return {
-            isLoggedIn: auth.$value.user !== null,
-            cartItems: cart.$value.items.length,
-            theme: settings.$value.theme
-        };
-    }, [auth, cart, settings]);
-    
-    return { auth, cart, settings, appStatus };
-};
+Store.delete('session'); // cleans up all subscribers and removes the store
+```
+
+> After deletion, any existing follower references become stale. Always check with `Store.has()` before accessing a store that may have been deleted.
+
+### `Store.reset(name)`
+
+Resets a resettable store to its initial value:
+
+```javascript
+Store.reset('user');    // works - created with createResettable()
+Store.reset('theme');   // throws - created with create()
 ```
 
+---
+
 ## Next Steps
 
-Now that you understand state management, explore these related topics:
+- **[Observables](./observables.md)** - Local state and reactive primitives
+- **[Lifecycle Events](./lifecycle-events.md)** - Lifecycle events
+- **[NDElement](./native-document-element.md)** - Native Document Element
+- **[Args Validation](./validation.md)** - Function argument validation
+- **[Memory Management](./memory-management.md)** - Memory management
+
+## Utilities
 
-- **[Lifecycle Events](lifecycle-events.md)** - Lifecycle events
-- **[Memory Management](memory-management.md)** - Memory management
-- **[Anchor](anchor.md)** - Anchor
+- **[Cache](./cache.md)** - Lazy initialization and singleton patterns
+- **[NativeFetch](./native-fetch.md)** - HTTP client with interceptors
+- **[Filters](./filters.md)** - Data filtering helpers