@signaltree/enterprise 9.0.0 → 9.1.0

package/README.md

@@ -7,7 +7,9 @@ Enterprise-grade optimizations for SignalTree. Designed for large-scale applicat
 - **Diff-based updates** - Only update signals that actually changed
 - **Bulk operation optimization** - 2-5x faster for large state updates
 - **Advanced change tracking** - Detailed statistics and monitoring
-- **Path indexing** - Optimized signal lookup for large trees
+- **Path-change subscriptions** - React to specific dot-paths changing (9.1+)
+- **Snapshot / restore** - Cheap structured-clone snapshots with diff-engine restore (9.1+)
+- **Auto-optimize threshold** - Route large updates through the diff engine automatically (9.1+)
 - **Lazy initialization** - Zero overhead until first use
 
 ## Installation
@@ -58,7 +60,7 @@ console.log(result.stats);
 
 ## API
 
-### `enterprise()`
+### `enterprise(options?)`
 
 Enhancer that adds enterprise optimizations to a SignalTree.
 
@@ -67,6 +69,19 @@ import { signalTree } from '@signaltree/core';
 import { enterprise } from '@signaltree/enterprise';
 
 const tree = signalTree(initialState).with(enterprise());
+
+// Or with auto-optimize threshold (9.1+):
+const tree2 = signalTree(initialState).with(enterprise({ autoOptimizeThreshold: 100 }));
+```
+
+**Options (9.1+):**
+
+```typescript
+{
+  autoOptimizeThreshold?: number; // If set, tree.updateAuto(...) routes through
+                                  // updateOptimized when the payload has at
+                                  // least this many top-level keys.
+}
 ```
 
 ### `tree.updateOptimized(updates, options?)`
@@ -106,6 +121,9 @@ Performs optimized bulk updates using diff-based change detection.
 
 ### `tree.getPathIndex()`
 
+> **Deprecated (9.1+):** Path-index access is an internal detail and will be
+> removed in a future major. Use `onPathChange` for change observation.
+
 Get the PathIndex for debugging/monitoring. Returns `null` if `updateOptimized` hasn't been called yet (lazy initialization).
 
 ```typescript
@@ -115,6 +133,52 @@ if (index) {
 }
 ```
 
+### `tree.onPathChange(listener)` (9.1+)
+
+Subscribe to dot-paths that change on each `updateOptimized` (or
+`updateAuto` when it routes through the diff engine). Returns an
+unsubscribe function.
+
+```typescript
+const off = tree.onPathChange((paths) => {
+  console.log('changed:', paths); // e.g. ['user.name', 'cart.items.0.qty']
+});
+
+tree.updateOptimized({ user: { name: 'Ada' } });
+// → listener fires with ['user.name']
+
+off(); // stop listening
+```
+
+### `tree.snapshot()` / `tree.restore(snap)` (9.1+)
+
+Capture and restore the entire state via a `structuredClone`. `restore`
+routes through the diff engine, so listeners and stats fire as if the
+restored values were a normal optimized update.
+
+```typescript
+const snap = tree.snapshot();
+
+tree.updateOptimized({ user: { name: 'Grace' } });
+
+// later... roll back
+tree.restore(snap);
+```
+
+### `tree.updateAuto(updates)` (9.1+)
+
+When `enterprise({ autoOptimizeThreshold: N })` is configured, payloads
+with `≥ N` top-level keys are routed through `updateOptimized`; smaller
+payloads use the regular fast path. Without a threshold this is a plain
+`update`.
+
+```typescript
+const tree = signalTree(initialState).with(enterprise({ autoOptimizeThreshold: 50 }));
+
+tree.updateAuto({ a: 1, b: 2 }); // fast path
+tree.updateAuto(largeServerPayload); // diff engine
+```
+
 ## Examples
 
 ### Real-time Dashboard

package/dist/lib/enterprise-enhancer.js

@@ -1,19 +1,32 @@
 import { PathIndex } from './path-index.js';
 import { OptimizedUpdateEngine } from './update-engine.js';
 
-function enterprise() {
+function enterprise(options = {}) {
   return tree => {
     let pathIndex = null;
     let updateEngine = null;
+    const listeners = new Set();
     const signalTree = tree;
     const enhancedTree = tree;
-    enhancedTree.updateOptimized = (updates, options) => {
+    const ensureEngine = () => {
       if (!updateEngine) {
         pathIndex = new PathIndex();
         pathIndex.buildFromTree(signalTree.state);
         updateEngine = new OptimizedUpdateEngine(signalTree.state);
       }
-      const result = updateEngine.update(signalTree.state, updates, options);
+      return updateEngine;
+    };
+    const notifyListeners = paths => {
+      if (!listeners.size || !paths.length) return;
+      for (const fn of Array.from(listeners)) {
+        try {
+          fn(paths);
+        } catch (_a) {}
+      }
+    };
+    const runOptimized = (updates, opts) => {
+      const engine = ensureEngine();
+      const result = engine.update(signalTree.state, updates, opts);
       if (result.changed && pathIndex) {
         if (result.changedPaths.length) {
           pathIndex.incrementalUpdate(signalTree.state, result.changedPaths);
@@ -22,8 +35,35 @@ function enterprise() {
           pathIndex.buildFromTree(signalTree.state);
         }
       }
+      notifyListeners(result.changedPaths);
       return result;
     };
+    enhancedTree.updateOptimized = runOptimized;
+    enhancedTree.onPathChange = listener => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    };
+    enhancedTree.snapshot = () => {
+      const current = tree();
+      return structuredClone(current);
+    };
+    enhancedTree.restore = snapshot => {
+      return runOptimized(snapshot);
+    };
+    const threshold = options.autoOptimizeThreshold;
+    if (threshold && threshold > 0) {
+      const originalCall = tree.bind(tree);
+      const wrapped = function (arg) {
+        if (arguments.length === 1 && arg && typeof arg === 'object' && !Array.isArray(arg) && Object.keys(arg).length >= threshold) {
+          runOptimized(arg);
+          return;
+        }
+        return originalCall(arg);
+      };
+      enhancedTree.updateAuto = wrapped;
+    } else {
+      enhancedTree.updateAuto = arg => tree(arg);
+    }
     enhancedTree.getPathIndex = () => pathIndex;
     return enhancedTree;
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaltree/enterprise",
-  "version": "9.0.0",
+  "version": "9.1.0",
   "description": "Enterprise optimizations for SignalTree reactive JSON. Diff-based updates, bulk operations, and advanced change tracking for large-scale applications.",
   "license": "BSL-1.1",
   "type": "module",
@@ -68,12 +68,12 @@
   },
   "peerDependencies": {
     "@angular/core": "^20.0.0",
-    "@signaltree/core": "^9.0.0",
+    "@signaltree/core": "workspace:*",
     "tslib": "^2.0.0"
   },
   "peerDependenciesMeta": {},
   "devDependencies": {
-    "@signaltree/core": "^9.0.0"
+    "@signaltree/core": "workspace:*"
   },
   "publishConfig": {
     "access": "public"

package/src/lib/enterprise-enhancer.d.ts

@@ -2,7 +2,11 @@ import { PathIndex } from './path-index';
 import { UpdateResult } from './update-engine';
 import type { Signal } from '@angular/core';
 import type { ISignalTree } from '@signaltree/core';
-export declare function enterprise<T = unknown>(): (tree: ISignalTree<T>) => ISignalTree<T> & EnterpriseEnhancedTree<T>;
+export type PathChangeListener = (changedPaths: readonly string[]) => void;
+export interface EnterpriseOptions {
+    autoOptimizeThreshold?: number;
+}
+export declare function enterprise<T = unknown>(options?: EnterpriseOptions): (tree: ISignalTree<T>) => ISignalTree<T> & EnterpriseEnhancedTree<T>;
 export interface EnterpriseEnhancedTree<T> {
     updateOptimized(updates: Partial<T>, options?: {
         maxDepth?: number;
@@ -11,6 +15,10 @@ export interface EnterpriseEnhancedTree<T> {
         autoBatch?: boolean;
         batchSize?: number;
     }): UpdateResult;
+    onPathChange(listener: PathChangeListener): () => void;
+    snapshot(): unknown;
+    restore(snapshot: unknown): UpdateResult;
+    updateAuto(updates: unknown): unknown;
     getPathIndex(): PathIndex<Signal<unknown>> | null;
 }
 export declare const withEnterprise: typeof enterprise;