@jucie.io/state 1.0.1

package/plugins/on-change/README.md

@@ -0,0 +1,444 @@
+# @jucio.io/state/on-change
+
+Simple global change listener plugin for @jucio.io/state that notifies you of all state changes with automatic batching and consolidation.
+
+## Features
+
+- 🔔 **Global Change Tracking**: Listen to all state changes in one place
+- 📦 **Automatic Batching**: Changes are batched and delivered asynchronously
+- 🔄 **Smart Consolidation**: Multiple changes to the same path are consolidated
+- 🎯 **Simple API**: Just add listeners and remove them when done
+- ⚡ **Performance Optimized**: Only active when listeners are registered
+- 🔌 **Zero Configuration**: Works out of the box
+
+## Installation
+
+```bash
+npm install @jucio.io/state
+```
+
+**Note:** OnChange plugin is included in the main package.
+
+## Quick Start
+
+```javascript
+import { createState } from '@jucio.io/state';
+import { OnChange } from '@jucio.io/state/on-change';
+
+// Create state and install OnChange plugin
+const state = createState({
+  user: { name: 'Alice', age: 30 },
+  settings: { theme: 'dark' }
+});
+state.install(OnChange);
+
+// Add a change listener
+const unsubscribe = state.onChange.addListener((changes) => {
+  console.log('State changed:', changes);
+});
+
+// Make some changes
+state.set(['user', 'name'], 'Bob');
+state.set(['settings', 'theme'], 'light');
+
+// Console: "State changed: [{ path: ['user', 'name'], from: 'Alice', to: 'Bob', ... }, ...]"
+
+// Remove listener when done
+unsubscribe();
+```
+
+## Configuration
+
+The OnChange plugin can be configured with custom options:
+
+```javascript
+import { createState } from '@jucio.io/state';
+import { OnChange } from '@jucio.io/state/on-change';
+
+const state = createState({
+  user: { name: 'Alice', age: 30 }
+});
+
+// Install with custom configuration
+state.install(OnChange.configure({
+  debounce: 100  // Debounce change notifications by 100ms (default: 0)
+}));
+```
+
+### Options
+
+- **`debounce`** (number): Delay in milliseconds before notifying listeners. Default: `0` (no debounce)
+
+## API Reference
+
+### Actions
+
+#### `state.onChange.addListener(callback)`
+
+Add a listener that will be called whenever state changes occur.
+
+```javascript
+const unsubscribe = state.onChange.addListener((changes) => {
+  changes.forEach(change => {
+    console.log('Changed:', change.path);
+    console.log('From:', change.from);
+    console.log('To:', change.to);
+  });
+});
+```
+
+**Parameters:**
+- `callback` (Function): Function that receives an array of change objects
+
+**Returns:** Unsubscribe function to remove the listener
+
+**Change Object Structure:**
+```javascript
+{
+  path: ['user', 'name'],     // Path that changed
+  from: 'Alice',               // Previous value
+  to: 'Bob',                   // New value
+  method: 'set',               // Method used (set, delete, push, etc.)
+  timestamp: 1234567890        // Timestamp of change (if available)
+}
+```
+
+#### `state.onChange.removeListener(callback)`
+
+Manually remove a listener.
+
+```javascript
+function myListener(changes) {
+  console.log('Changes:', changes);
+}
+
+state.onChange.addListener(myListener);
+
+// Later...
+state.onChange.removeListener(myListener);
+```
+
+**Parameters:**
+- `callback` (Function): The listener function to remove
+
+## How It Works
+
+### Automatic Batching
+
+Multiple synchronous changes are automatically batched and delivered together:
+
+```javascript
+state.onChange.addListener((changes) => {
+  console.log('Received', changes.length, 'changes');
+});
+
+// These three changes are batched together
+state.set(['a'], 1);
+state.set(['b'], 2);
+state.set(['c'], 3);
+
+// Console: "Received 3 changes"
+```
+
+### Smart Consolidation
+
+Multiple changes to the same path are consolidated, keeping only the most recent:
+
+```javascript
+state.onChange.addListener((changes) => {
+  console.log('Changes:', changes);
+});
+
+// Rapid changes to the same path
+state.set(['counter'], 1);
+state.set(['counter'], 2);
+state.set(['counter'], 3);
+
+// Console: "Changes: [{ path: ['counter'], from: 0, to: 3, ... }]"
+// Only the final change is reported
+```
+
+### Performance Optimization
+
+The plugin only tracks changes when at least one listener is registered:
+
+```javascript
+// No listeners = no overhead
+state.set(['value'], 1); // Fast, no tracking
+
+// Add listener
+const unsubscribe = state.onChange.addListener(handler);
+
+// Now tracking is active
+state.set(['value'], 2); // Tracked and reported
+
+// Remove listener
+unsubscribe();
+
+// Back to no overhead
+state.set(['value'], 3); // Fast, no tracking
+```
+
+## Common Use Cases
+
+### Logging
+
+```javascript
+state.onChange.addListener((changes) => {
+  if (process.env.NODE_ENV === 'development') {
+    console.group('State Changes');
+    changes.forEach(change => {
+      console.log(`${change.path.join('.')}: ${change.from} → ${change.to}`);
+    });
+    console.groupEnd();
+  }
+});
+```
+
+### Persistence
+
+```javascript
+state.onChange.addListener((changes) => {
+  // Save entire state to localStorage
+  localStorage.setItem('appState', JSON.stringify(state.get([])));
+});
+```
+
+### Analytics
+
+```javascript
+state.onChange.addListener((changes) => {
+  changes.forEach(change => {
+    analytics.track('state_changed', {
+      path: change.path.join('.'),
+      method: change.method,
+      timestamp: Date.now()
+    });
+  });
+});
+```
+
+### DevTools Integration
+
+```javascript
+if (window.__REDUX_DEVTOOLS_EXTENSION__) {
+  const devTools = window.__REDUX_DEVTOOLS_EXTENSION__.connect();
+  
+  state.onChange.addListener((changes) => {
+    changes.forEach(change => {
+      devTools.send({
+        type: `SET ${change.path.join('.')}`,
+        payload: change.to
+      }, state.get([]));
+    });
+  });
+}
+```
+
+### Sync to Server
+
+```javascript
+let syncTimeout;
+
+state.onChange.addListener((changes) => {
+  // Debounce server sync
+  clearTimeout(syncTimeout);
+  syncTimeout = setTimeout(async () => {
+    await fetch('/api/sync', {
+      method: 'POST',
+      body: JSON.stringify({
+        changes,
+        state: state.get([])
+      })
+    });
+  }, 1000);
+});
+```
+
+### Change History
+
+```javascript
+const changeHistory = [];
+
+state.onChange.addListener((changes) => {
+  changeHistory.push({
+    timestamp: Date.now(),
+    changes: changes.map(c => ({ ...c }))
+  });
+  
+  // Keep last 100 change batches
+  if (changeHistory.length > 100) {
+    changeHistory.shift();
+  }
+});
+```
+
+### Validation
+
+```javascript
+state.onChange.addListener((changes) => {
+  changes.forEach(change => {
+    if (change.path[0] === 'user' && change.path[1] === 'email') {
+      const email = change.to;
+      if (!email.includes('@')) {
+        console.warn('Invalid email address');
+        // Optionally revert the change
+        state.set(change.path, change.from);
+      }
+    }
+  });
+});
+```
+
+## Advanced Patterns
+
+### Conditional Listeners
+
+```javascript
+let unsubscribe = null;
+
+function enableChangeTracking() {
+  if (!unsubscribe) {
+    unsubscribe = state.onChange.addListener((changes) => {
+      console.log('Tracking changes:', changes);
+    });
+  }
+}
+
+function disableChangeTracking() {
+  if (unsubscribe) {
+    unsubscribe();
+    unsubscribe = null;
+  }
+}
+
+// Enable tracking based on some condition
+if (userPreferences.debugMode) {
+  enableChangeTracking();
+}
+```
+
+### Multiple Listeners
+
+```javascript
+// Logger
+state.onChange.addListener((changes) => {
+  console.log('LOG:', changes.length, 'changes');
+});
+
+// Validator
+state.onChange.addListener((changes) => {
+  changes.forEach(validateChange);
+});
+
+// Sync
+state.onChange.addListener((changes) => {
+  syncToServer(changes);
+});
+
+// All listeners receive the same changes
+```
+
+### Filtered Listeners
+
+```javascript
+// Create a filtered listener helper
+function createFilteredListener(pathPrefix, callback) {
+  return state.onChange.addListener((changes) => {
+    const filtered = changes.filter(change => {
+      return change.path.length >= pathPrefix.length &&
+        pathPrefix.every((segment, i) => change.path[i] === segment);
+    });
+    
+    if (filtered.length > 0) {
+      callback(filtered);
+    }
+  });
+}
+
+// Only listen to user changes
+const unsubscribe = createFilteredListener(['user'], (changes) => {
+  console.log('User changed:', changes);
+});
+```
+
+### Change Replay
+
+```javascript
+const recordedChanges = [];
+let isRecording = false;
+
+const unsubscribe = state.onChange.addListener((changes) => {
+  if (isRecording) {
+    recordedChanges.push(...changes);
+  }
+});
+
+function startRecording() {
+  isRecording = true;
+  recordedChanges.length = 0;
+}
+
+function stopRecording() {
+  isRecording = false;
+  return [...recordedChanges];
+}
+
+function replay(changes) {
+  changes.forEach(change => {
+    state.set(change.path, change.to);
+  });
+}
+```
+
+## Comparison with Matcher Plugin
+
+| Feature | OnChange | Matcher |
+|---------|----------|---------|
+| Scope | All changes | Specific paths |
+| Batching | Automatic | Automatic |
+| Consolidation | By address | By path |
+| Filtering | Manual | Built-in |
+| Use Case | Global tracking | Specific watchers |
+| Performance | Tracks everything | Optimized for paths |
+
+**When to use OnChange:**
+- Debug logging
+- Global persistence
+- Analytics tracking
+- DevTools integration
+- You need to see all changes
+
+**When to use Matcher:**
+- Watch specific data
+- React to specific paths
+- Need hierarchical matching
+- Better performance for selective watching
+
+## Performance Tips
+
+1. **Remove listeners when done** - Always unsubscribe to prevent memory leaks
+2. **Avoid heavy computations** - Listeners are called frequently, keep them fast
+3. **Use debouncing** for expensive operations like server sync
+4. **Filter early** if you only care about specific changes
+5. **Batch operations** when making multiple changes to reduce listener calls
+
+```javascript
+// Good: Remove when done
+const unsub = state.onChange.addListener(handler);
+cleanup(() => unsub());
+
+// Bad: Memory leak
+state.onChange.addListener(handler);
+```
+
+## License
+
+See the root [LICENSE](../../LICENSE) file for license information.
+
+## Related Packages
+
+- [@jucio.io/state](../../core) - Core state management system
+- [@jucio.io/state/history](../history) - Undo/redo functionality
+- [@jucio.io/state/matcher](../matcher) - Path-based change tracking
+