@jucie.io/state 1.0.1

package/plugins/matcher/README.md

@@ -0,0 +1,402 @@
+# @jucio.io/state/matcher
+
+Path-based state watching plugin for @jucio.io/state that allows you to watch specific paths in your state tree and react to changes. **Your handlers receive the current data at the watched path, not change objects.**
+
+## Features
+
+- 🎯 **Path Matching**: Watch specific paths in your state tree
+- 📊 **Data Values**: Handlers receive actual data at the path, not change objects
+- 🌳 **Hierarchical Watching**: Match exact paths, parent paths, or child paths
+- 📦 **Automatic Batching**: Changes are automatically batched and debounced
+- 🔄 **Smart Consolidation**: Multiple changes to the same path are consolidated
+- 🎬 **Declarative Setup**: Define matchers during state initialization
+- 🔌 **Plugin Architecture**: Seamlessly integrates with @jucie-state/core
+
+## Installation
+
+```bash
+npm install @jucio.io/state
+```
+
+**Note:** Matcher plugin is included in the main package.
+
+## Quick Start
+
+```javascript
+import { createState } from '@jucio.io/state';
+import { Matcher, createMatcher } from '@jucio.io/state/matcher';
+
+// Create a matcher
+const userMatcher = createMatcher(['user'], (userData) => {
+  console.log('User data:', userData);
+});
+
+// Create state and install matcher plugin
+const state = createState({
+  user: { name: 'Alice', age: 30 },
+  settings: { theme: 'dark' }
+});
+
+// Install with initial matchers
+state.install(Matcher.configure({
+  matchers: [userMatcher]
+}));
+
+// Change user data - matcher receives the NEW data
+state.set(['user', 'name'], 'Bob');
+// Console: "User data: { name: 'Bob', age: 30 }"
+
+// Change settings - matcher doesn't fire (different path)
+state.set(['settings', 'theme'], 'light');
+```
+
+## API Reference
+
+### Creating Matchers
+
+#### `createMatcher(path, handler)`
+
+Create a matcher that watches a specific path in the state tree.
+
+**The handler receives the current data at the watched path, not change objects.**
+
+```javascript
+import { createMatcher } from '@jucio.io/state/matcher';
+
+const matcher = createMatcher(['users', 'profile'], (profileData) => {
+  console.log('Profile is now:', profileData);
+});
+```
+
+**Parameters:**
+- `path` (Array): Path to watch (e.g., `['user']`, `['users', 'profile']`)
+- `handler` (Function): Callback function that receives the **current data** at the path
+
+**Returns:** Matcher function that can be added to the plugin
+
+### Plugin Actions
+
+When using the Matcher plugin with a state instance, you get access to these actions:
+
+#### `state.matcher.createMatcher(path, handler)`
+
+Create and automatically register a matcher.
+
+```javascript
+import { createState } from '@jucio.io/state';
+import { Matcher } from '@jucio.io/state/matcher';
+
+const state = createState({ user: { name: 'Alice' } });
+state.install(Matcher);
+
+const unsubscribe = state.matcher.createMatcher(['user'], (userData) => {
+  console.log('User is now:', userData);
+});
+
+// Later: remove the matcher
+unsubscribe();
+```
+
+**Returns:** Unsubscribe function
+
+#### `state.matcher.addMatcher(matcher)`
+
+Add an existing matcher to the plugin.
+
+```javascript
+const matcher = createMatcher(['user'], (userData) => {
+  console.log('User:', userData);
+});
+
+state.matcher.addMatcher(matcher);
+```
+
+#### `state.matcher.removeMatcher(matcher)`
+
+Remove a matcher from the plugin.
+
+```javascript
+state.matcher.removeMatcher(matcher);
+```
+
+## Match Types
+
+Matchers use hierarchical matching with three types. **The handler always receives the current data at the matched path:**
+
+### Exact Match
+
+Watches the exact path specified:
+
+```javascript
+const matcher = createMatcher(['user', 'profile'], (profileData) => {
+  console.log('Profile data:', profileData);
+});
+
+state.set(['user', 'profile'], { bio: 'Hello' }); // ✅ Fires with { bio: 'Hello' }
+state.set(['user', 'profile', 'bio'], 'Hi');       // ✅ Fires with { bio: 'Hi' }
+state.set(['user'], { profile: { bio: 'Hi' } });   // ✅ Fires with { bio: 'Hi' }
+state.set(['user', 'settings'], {});                // ❌ Doesn't fire
+```
+
+### Parent Match
+
+Fires when a parent path or any descendant changes:
+
+```javascript
+const matcher = createMatcher(['user'], (userData) => {
+  console.log('User data:', userData);
+});
+
+state.set(['user', 'name'], 'Alice');               // ✅ Fires with entire user object
+state.set(['user', 'profile', 'bio'], 'Hello');     // ✅ Fires with entire user object
+state.set(['user'], { name: 'Bob' });               // ✅ Fires with { name: 'Bob' }
+```
+
+### Child Match
+
+When watching a parent and children change, child changes are consolidated:
+
+```javascript
+const matcher = createMatcher(['users'], (usersData) => {
+  console.log('Users data:', usersData);
+});
+
+state.set(['users', 'alice'], { name: 'Alice' });
+state.set(['users', 'bob'], { name: 'Bob' });
+
+// Both changes are batched. Handler receives the full current state:
+// { alice: { name: 'Alice' }, bob: { name: 'Bob' } }
+```
+
+## Configuration
+
+### Initialize with Matchers
+
+```javascript
+import { createState } from '@jucio.io/state';
+import { Matcher, createMatcher } from '@jucio.io/state/matcher';
+
+const userMatcher = createMatcher(['user'], (user) => {
+  console.log('User:', user);
+});
+
+const settingsMatcher = createMatcher(['settings'], (settings) => {
+  console.log('Settings:', settings);
+});
+
+const state = createState({ user: {}, settings: {} });
+state.install(Matcher.configure({
+  matchers: [userMatcher, settingsMatcher]
+}));
+```
+
+### Define Matchers as Objects
+
+```javascript
+import { createState } from '@jucio.io/state';
+import { Matcher } from '@jucio.io/state/matcher';
+
+const state = createState({ user: {}, settings: {} });
+state.install(Matcher.configure({
+  matchers: [
+    {
+      path: ['user'],
+      handler: (user) => console.log('User:', user)
+    },
+    {
+      path: ['settings'],
+      handler: (settings) => console.log('Settings:', settings)
+    }
+  ]
+}));
+```
+
+## Advanced Usage
+
+### Multiple Matchers on Same Path
+
+```javascript
+const logger = createMatcher(['user'], (userData) => {
+  console.log('User changed:', userData);
+});
+
+const validator = createMatcher(['user'], (userData) => {
+  if (!userData.email) {
+    console.warn('User has no email!');
+  }
+});
+
+state.matcher.addMatcher(logger);
+state.matcher.addMatcher(validator);
+
+state.set(['user'], { name: 'Alice' });
+// Both matchers fire with { name: 'Alice' }
+```
+
+### Dynamic Matcher Management
+
+```javascript
+// Add matcher conditionally
+if (process.env.NODE_ENV === 'development') {
+  const debugMatcher = state.matcher.createMatcher(['*'], (data) => {
+    console.log('DEBUG: State changed:', data);
+  });
+}
+
+// Add/remove based on user settings
+function toggleAuditLog(enabled) {
+  if (enabled) {
+    const auditMatcher = createMatcher(['data'], (data) => {
+      logToServer('data-change', data);
+    });
+    state.matcher.addMatcher(auditMatcher);
+    return () => state.matcher.removeMatcher(auditMatcher);
+  }
+}
+```
+
+### Nested Path Watching
+
+```javascript
+// Watch different levels of nesting
+const userMatcher = createMatcher(['user'], (userData) => {
+  console.log('Entire user object:', userData);
+});
+
+const profileMatcher = createMatcher(['user', 'profile'], (profileData) => {
+  console.log('Just profile:', profileData);
+});
+
+const nameMatcher = createMatcher(['user', 'profile', 'name'], (name) => {
+  console.log('Just name:', name);
+});
+
+state.set(['user', 'profile', 'name'], 'Alice');
+// All three matchers fire:
+// - userMatcher gets the entire user object
+// - profileMatcher gets just the profile object  
+// - nameMatcher gets just 'Alice'
+```
+
+### Batching and Consolidation
+
+```javascript
+const matcher = createMatcher(['items'], (itemsData) => {
+  console.log('Items:', itemsData);
+});
+
+// Multiple rapid changes are batched
+state.set(['items', 'item1'], { value: 1 });
+state.set(['items', 'item2'], { value: 2 });
+state.set(['items', 'item3'], { value: 3 });
+
+// Single callback with current state:
+// { item1: { value: 1 }, item2: { value: 2 }, item3: { value: 3 } }
+```
+
+## Common Patterns
+
+### Form Field Validation
+
+```javascript
+const emailMatcher = createMatcher(['form', 'email'], (email) => {
+  const isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+  state.set(['form', 'errors', 'email'], isValid ? null : 'Invalid email');
+});
+
+state.matcher.addMatcher(emailMatcher);
+```
+
+### Persistence
+
+```javascript
+const persistMatcher = createMatcher(['user', 'preferences'], (preferences) => {
+  localStorage.setItem('preferences', JSON.stringify(preferences));
+});
+
+state.matcher.addMatcher(persistMatcher);
+```
+
+### Analytics Tracking
+
+```javascript
+const analyticsMatcher = createMatcher(['analytics', 'events'], (events) => {
+  Object.entries(events).forEach(([key, event]) => {
+    trackEvent(event.name, event.properties);
+  });
+});
+
+state.matcher.addMatcher(analyticsMatcher);
+```
+
+### Derived State Updates
+
+```javascript
+// Update derived state when source changes
+const cartMatcher = createMatcher(['cart', 'items'], (items) => {
+  const total = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+  state.set(['cart', 'total'], total);
+});
+
+state.matcher.addMatcher(cartMatcher);
+```
+
+### API Synchronization
+
+```javascript
+const syncMatcher = createMatcher(['user'], async (userData) => {
+  try {
+    await fetch('/api/user', {
+      method: 'PUT',
+      body: JSON.stringify(userData)
+    });
+    console.log('User synced to server');
+  } catch (error) {
+    console.error('Failed to sync user:', error);
+  }
+});
+
+state.matcher.addMatcher(syncMatcher);
+```
+
+## Performance Considerations
+
+1. **Automatic Batching**: Matchers automatically batch changes using `setTimeout(fn, 0)`, so multiple synchronous changes trigger the handler only once
+
+2. **Smart Consolidation**: Multiple changes to the same path are consolidated into a single update
+
+3. **Efficient Matching**: Uses marker comparison for fast path matching
+
+4. **Cleanup**: Always unsubscribe matchers when they're no longer needed to prevent memory leaks
+
+```javascript
+// Good: Clean up when done
+const unsubscribe = state.matcher.createMatcher(['temp'], handler);
+// ... later
+unsubscribe();
+```
+
+## Comparison with OnChange Plugin
+
+| Feature | Matcher | OnChange |
+|---------|---------|----------|
+| What handler receives | Current data at path | Change objects with metadata |
+| Scope | Specific paths | Global changes |
+| Batching | Automatic | Automatic |
+| Consolidation | Smart path-based | By change address |
+| Performance | Optimized for specific paths | Tracks all changes |
+| Use Case | Watch specific data, get values | Track all changes, get metadata |
+
+**Use Matcher when:** You want the current data at specific paths
+**Use OnChange when:** You need change metadata (from/to values, method, etc.)
+
+## License
+
+See the root [LICENSE](../../LICENSE) file for license information.
+
+## Related Packages
+- [@jucio.io/react](https://github.com/adrianjonmiller/react) - React integration
+- [@jucio.io/state](../../core) - Core state management system
+- [@jucio.io/state/history](../history) - Undo/redo functionality
+- [@jucio.io/state/on-change](../on-change) - Global change listeners
+