@signaltree/enterprise 13.4.0 → 13.5.0

package/README.md

@@ -1,272 +1,115 @@
 # @signaltree/enterprise
 
-Enterprise-grade optimizations for SignalTree. Designed for large-scale applications with 500+ signals and high-frequency bulk updates.
+> # ⚠️ Deprecated as of 13.5.0
+>
+> **Use `tree.updateAndReport()` from `@signaltree/core`.** They are built in, need no enhancer, add no bundle, and are faster than this package.
+>
+> This package remains published so existing installs keep resolving, and will receive security fixes only. No new features, and the array defect below is not being fixed.
 
-## Features
+## Why it was retired
 
-- **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-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
+**The headline performance claim was inverted.** Measured against `tree.updateAndReport()` — which returns the same changed paths — `updateOptimized()` is:
 
-## Installation
+| Workload (2,000 leaves)       | `updateOptimized()` | `updateAndReport()` | Result             |
+| ----------------------------- | ------------------- | ------------------- | ------------------ |
+| 10% of leaves changed         | ~0.53 ms            | ~0.08 ms            | **~7x slower**     |
+| identical re-fetch (all no-op)| ~0.14 ms            | ~0.07 ms            | **~2x slower**     |
+| every leaf changed            | ~24-27 ms           | ~0.12-0.17 ms       | **~160-190x slower** |
 
-```bash
-npm install @signaltree/core @signaltree/enterprise
-```
-
-## Type Definitions
-
-Type declarations are shipped as `src/**/*.d.ts` and referenced by the package exports.
-No extra build step is needed to consume types.
-
-## Quick Start
-
-```typescript
-import { signalTree } from '@signaltree/core';
-import { enterprise } from '@signaltree/enterprise';
-
-const tree = signalTree(largeState).with(enterprise());
+At 500 leaves the same workloads measure ~4-4.5x, ~1.2-1.6x and ~43x. The ratio
+grows with tree size in every workload, which is the opposite of the scaling
+story the package was sold on ("use it at 500+ signals").
 
-// Use optimized bulk updates
-const result = tree.updateOptimized(newData, {
-  ignoreArrayOrder: true,
-  maxDepth: 10,
-});
+The long-standing "2-5x faster" claim was never measured against core. Numbers
+are means over 50 timed iterations after warm-up, payloads generated outside the
+timed loop; they will differ on your hardware, so treat the RATIOS as the
+finding, not the absolute times.
 
-console.log(result.stats);
-// { totalChanges: 45, adds: 10, updates: 30, deletes: 5 }
-```
-
-## When to Use
-
-### ✅ Use @signaltree/enterprise when:
-
-- You have 500+ signals in your state tree
-- Bulk updates happen at high frequency (60Hz+)
-- You need real-time dashboards or data feeds
-- You're building enterprise-scale applications
-- You need detailed update monitoring and statistics
-
-### ❌ Skip @signaltree/enterprise when:
+This is structural, not a tuning problem. Core leaves are `signal(value, { equal })` — deep equality plus a reference-equality short-circuit — so **"only write what actually changed" is already core behaviour, for free**. The diff engine walks the whole state to decide which writes to skip, and the writes it skips were already no-ops. No amount of optimization changes that shape; the work it does is work core does not need to do.
 
-- Small to medium apps (<100 signals)
-- Infrequent state updates
-- Startup/prototype projects
-- Bundle size is critical (adds +2.4KB gzipped)
+Two further reasons:
 
-## API
+- **It no longer offers anything core lacks.** `changedPaths` and `updateAndReport()` return the same information, and `onPathChange` now ships in core.
+- **It has no independent runtime dependency**, which puts it on the wrong side of the packaging rule in [RFC 0007](../../docs/rfcs/0007-packaging-principle-and-ng-forms-reslice.md) — a package should exist because it pulls in a dependency core should not.
 
-### `enterprise(options?)`
-
-Enhancer that adds enterprise optimizations to a SignalTree.
+## Migration
 
 ```typescript
+// Before
 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?)`
-
-Performs optimized bulk updates using diff-based change detection.
-
-**Parameters:**
-
-- `updates: Partial<T>` - The new state values
-- `options?: UpdateOptions` - Configuration options
-
-**Options:**
-
-```typescript
-{
-  maxDepth?: number;              // Maximum depth to traverse (default: 100)
-  ignoreArrayOrder?: boolean;     // Ignore array element order (default: false)
-  equalityFn?: (a, b) => boolean; // Custom equality function
-  autoBatch?: boolean;            // Automatically batch updates (default: true)
-  batchSize?: number;             // Patches per batch (default: 10)
-}
-```
-
-**Returns:**
-
-```typescript
-{
-  changed: boolean; // Whether any changes were made
-  stats: {
-    totalChanges: number; // Total number of changes
-    adds: number; // New properties added
-    updates: number; // Properties updated
-    deletes: number; // Properties deleted
-  }
-}
-```
-
-### `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.
+const tree = signalTree(state).with(enterprise());
+const result = tree.updateOptimized(payload);
+if (result.changed) sync(result.changedPaths);
 
-Get the PathIndex for debugging/monitoring. Returns `null` if `updateOptimized` hasn't been called yet (lazy initialization).
-
-```typescript
-const index = tree.getPathIndex();
-if (index) {
-  console.log('Path index active');
-}
-```
-
-### `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 }));
+// After — no enhancer, no extra bundle
+import { signalTree } from '@signaltree/core';
 
-tree.updateAuto({ a: 1, b: 2 }); // fast path
-tree.updateAuto(largeServerPayload); // diff engine
+const tree = signalTree(state);
+const changed = tree.updateAndReport(payload);
+if (changed.length) sync(changed);
 ```
 
-## Examples
+| Enterprise                                | Core replacement                                    |
+| ----------------------------------------- | --------------------------------------------------- |
+| `tree.updateOptimized(p)`                 | `tree.updateAndReport(p)` — returns changed paths   |
+| `tree.onPathChange(fn)`                   | **no direct replacement yet** — use `tree.updateAndReport(p)` at the call site; a subscription API is being designed |
+| `tree.snapshot()`                         | `const snap = tree()`                               |
+| `tree.restore(snap)`                      | `tree(snap)`                                        |
+| `tree.updateAuto(p)`                      | `tree(p)`                                           |
+| `tree.getPathIndex()`                     | no replacement — was debug-only, already deprecated |
+| `enterprise({ autoOptimizeThreshold: n })` | drop it — core has one write path                   |
 
-### Real-time Dashboard
+### Two rows above are an IMPROVEMENT, not an equivalence
 
-```typescript
-import { signalTree } from '@signaltree/core';
-import { enterprise } from '@signaltree/enterprise';
+`restore()` and `updateAuto()` do not merely have a core equal — the core form
+is **more correct**, because both inherit the array defect:
 
-interface DashboardState {
-  metrics: Record<string, number>;
-  alerts: Alert[];
-  users: User[];
-  // ... hundreds more properties
-}
+- `tree.restore(snap)` → `tree(snap)`. Restoring `{a, b:{c,d}, arr:[1,2,3]}`
+  after mutating it leaves `arr` at its mutated value while reporting
+  `arr.0`, `arr.1`, `arr.2` as changed — three paths it never wrote. `tree(snap)`
+  restores the array. Neither deletes keys absent from the snapshot; both merge.
+- `tree.updateAuto(p)` → `tree(p)`, but only exactly equivalent when NO
+  `autoOptimizeThreshold` is set (then `updateAuto` is a plain passthrough). With
+  a threshold, a payload over it routes through the diff engine and drops array
+  writes; `tree(p)` applies them.
 
-const dashboard = signalTree<DashboardState>(initialState).with(enterprise());
+### Three behaviour differences worth knowing
 
-// High-frequency updates from WebSocket
-socket.on('metrics', (newMetrics) => {
-  const result = dashboard.updateOptimized({ metrics: newMetrics }, { ignoreArrayOrder: true });
+**1. `updateAndReport()` is stricter about what counts as a change.** It reports only paths whose leaf signal actually accepted the write. A re-fetched payload identical to what you already hold reports `[]`; the diff engine reported every key in it. If you were counting on the old numbers, they were counting no-ops.
 
-  console.log(`Updated ${result.stats.updates} metrics`);
-});
-```
+**2. `onPathChange` in core fires for every root write** — the call form `tree({...})`, `batchUpdate()` and `updateAndReport()` — not just `updateOptimized()`. It does **not** fire for direct leaf writes (`tree.$.a.b.set(x)`), which bypass the root.
 
-### Data Grid with Bulk Operations
+**3. `snapshot()` here used `structuredClone`,** so it threw `DataCloneError` on any tree holding a function. `tree()` has no such limit.
 
-```typescript
-import { signalTree } from '@signaltree/core';
-import { enterprise } from '@signaltree/enterprise';
-
-const grid = signalTree({
-  rows: [] as GridRow[],
-  columns: [] as GridColumn[],
-  filters: {} as FilterState,
-  selection: new Set<string>(),
-}).with(enterprise());
+## Known defect (not being fixed)
 
-// Bulk update from API
-async function loadData() {
-  const data = await fetchGridData();
+`updateOptimized()` **silently drops writes that target an array.** It reports `changed: true`, lists the paths, and writes nothing.
 
-  const result = grid.updateOptimized(data, {
-    maxDepth: 5,
-    autoBatch: true,
-  });
+An array in a SignalTree is a single leaf — one `WritableSignal<T[]>` — while the diff engine is a general-purpose differ emitting element-level paths (`users.1`). The apply step cannot consume those against a leaf, so it bails and reports success anyway.
 
-  console.log(`Loaded ${result.stats.adds} rows in bulk`);
-}
-```
+Two fixes were attempted and both withdrawn, each having introduced defects worse than the one it closed (silent truncation and prototype injection in the first; dotted-key data loss and spurious writes in the second). Given the package is superseded, it stays documented rather than fixed.
 
-### Custom Equality for Complex Objects
+**Workaround** — write the array through its leaf:
 
 ```typescript
-const tree = signalTree(complexState).with(enterprise());
-
-tree.updateOptimized(newState, {
-  equalityFn: (a, b) => {
-    // Custom deep equality for specific object types
-    if (a instanceof Date && b instanceof Date) {
-      return a.getTime() === b.getTime();
-    }
-    return a === b;
-  },
-});
+tree.$.users.set(nextUsers); // works
+tree.updateOptimized({ users: nextUsers }); // silently does nothing
 ```
 
-## Performance
-
-**Bundle Size:**
+Or migrate to `updateAndReport()`, which handles arrays correctly.
 
-- Adds +2.4KB gzipped to your bundle
-- Zero overhead until first `updateOptimized()` call (lazy initialization)
+## Removed in 13.5.0
 
-**Performance Gains:**
-
-- 2-5x faster for bulk updates on large state trees
-- Scales efficiently with tree depth and complexity
-- Minimal memory overhead with path indexing
+`./scheduler` and `./thread-pools` subpath exports are gone. Both were dead — no caller anywhere in the repo and no tests. (They were *mentioned* in the v9 plan and on a demo page, but never documented as an API.) And `thread-pools` only ever exported `createMockPool()`, a test double that should never have shipped to production consumers. `scheduler`'s advertised "yield to the event loop" was `await Promise.resolve()`, a microtask, which does not yield.
 
 ## License
 
-Business Source License 1.1 (BSL-1.1) - See [LICENSE](../../LICENSE) for details.
-
-Converts to MIT license on the Change Date specified in the license.
+Business Source License 1.1 (BSL-1.1) — see [LICENSE](../../LICENSE). Converts to MIT on the Change Date specified in the license.
 
-## Related Packages
+## Related packages
 
-- [@signaltree/core](../core) - Core SignalTree functionality
-- [@signaltree/ng-forms](../ng-forms) - Angular forms integration
-- [@signaltree/callable-syntax](../callable-syntax) - Callable syntax transform
+- [@signaltree/core](../core) — where `updateAndReport()` and `onPathChange()` now live
+- [@signaltree/ng-forms](../ng-forms) — Angular forms integration
+- [@signaltree/callable-syntax](../callable-syntax) — callable syntax transform

package/dist/index.js

@@ -2,5 +2,3 @@ export { ChangeType, DiffEngine } from './lib/diff-engine.js';
 export { PathIndex } from './lib/path-index.js';
 export { OptimizedUpdateEngine } from './lib/update-engine.js';
 export { enterprise } from './lib/enterprise-enhancer.js';
-export { configureScheduler, getSchedulerMetrics, postTask } from './lib/scheduler.js';
-export { createMockPool } from './lib/thread-pools.js';

package/dist/lib/update-engine.js

@@ -3,6 +3,10 @@ import { isTraversableNode, isBuiltInObject } from '@signaltree/core';
 import { DiffEngine, ChangeType } from './diff-engine.js';
 import { PathIndex } from './path-index.js';
 
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+function isUnsafeKey(key) {
+  return typeof key === 'string' && UNSAFE_KEYS.has(key);
+}
 class OptimizedUpdateEngine {
   constructor(tree) {
     this.pathIndex = new PathIndex();
@@ -150,13 +154,18 @@ class OptimizedUpdateEngine {
       let current = tree;
       for (let i = 0; i < patch.path.length - 1; i++) {
         const key = patch.path[i];
+        if (isUnsafeKey(key)) return false;
+        if (!Object.prototype.hasOwnProperty.call(current, key)) {
+          return false;
+        }
         current = current[key];
         if (!isTraversableNode(current)) {
           return false;
         }
       }
       const lastKey = patch.path[patch.path.length - 1];
-      const target = current[lastKey];
+      if (isUnsafeKey(lastKey)) return false;
+      const target = Object.prototype.hasOwnProperty.call(current, lastKey) ? current[lastKey] : undefined;
       if (isTraversableNode(target)) {
         if (isSignal(target)) {
           const leaf = target;
@@ -171,10 +180,19 @@ class OptimizedUpdateEngine {
         }
         return false;
       }
-      if (this.isEqual(current[lastKey], patch.value)) {
+      if (this.isEqual(target, patch.value)) {
+        return false;
+      }
+      const existing = Object.getOwnPropertyDescriptor(current, lastKey);
+      if (!existing || !existing.enumerable) {
         return false;
       }
-      current[lastKey] = patch.value;
+      Object.defineProperty(current, lastKey, {
+        value: patch.value,
+        enumerable: true,
+        writable: true,
+        configurable: true
+      });
       return true;
     } catch (error) {
       console.error(`Failed to apply patch at ${patch.path.join('.')}:`, error);
@@ -192,6 +210,8 @@ class OptimizedUpdateEngine {
     if (isTraversableNode(node) && value && typeof value === 'object') {
       let changed = false;
       for (const [key, child] of Object.entries(value)) {
+        if (isUnsafeKey(key)) continue;
+        if (!Object.prototype.hasOwnProperty.call(node, key)) continue;
         changed = this.applyDeepToNode(node[key], child) || changed;
       }
       return changed;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@signaltree/enterprise",
-  "version": "13.4.0",
-  "description": "Enterprise optimizations for SignalTree reactive JSON. Diff-based updates, bulk operations, and advanced change tracking for large-scale applications.",
+  "version": "13.5.0",
+  "description": "DEPRECATED — use tree.updateAndReport() in @signaltree/core instead. The diff engine is measurably slower than the core API that replaced it.",
   "license": "BUSL-1.1",
   "type": "module",
   "sideEffects": false,
@@ -33,16 +33,6 @@
       "types": "./src/lib/enterprise-enhancer.d.ts",
       "import": "./dist/lib/enterprise-enhancer.js",
       "default": "./dist/lib/enterprise-enhancer.js"
-    },
-    "./scheduler": {
-      "types": "./src/lib/scheduler.d.ts",
-      "import": "./dist/lib/scheduler.js",
-      "default": "./dist/lib/scheduler.js"
-    },
-    "./thread-pools": {
-      "types": "./src/lib/thread-pools.d.ts",
-      "import": "./dist/lib/thread-pools.js",
-      "default": "./dist/lib/thread-pools.js"
     }
   },
   "keywords": [
@@ -68,7 +58,7 @@
   },
   "peerDependencies": {
     "@angular/core": "^20.0.0 || ^21.0.0 || ^22.0.0",
-    "@signaltree/core": "^13.4.0",
+    "@signaltree/core": "^13.5.0",
     "tslib": "^2.0.0"
   },
   "peerDependenciesMeta": {},

package/src/index.d.ts

@@ -2,5 +2,3 @@ export * from './lib/diff-engine';
 export * from './lib/path-index';
 export * from './lib/update-engine';
 export * from './lib/enterprise-enhancer';
-export * from './lib/scheduler';
-export * from './lib/thread-pools';

package/dist/lib/scheduler.js

@@ -1,76 +0,0 @@
-import { __awaiter } from 'tslib';
-
-const defaultConfig = {
-  yieldEveryTasks: 500,
-  yieldEveryMs: 8,
-  instrumentation: false
-};
-let config = Object.assign({}, defaultConfig);
-let metrics = {
-  drainCycles: 0,
-  tasksExecuted: 0,
-  maxQueueLength: 0,
-  yields: 0,
-  lastDrainDurationMs: 0,
-  totalDrainDurationMs: 0
-};
-const q = [];
-let draining = false;
-function configureScheduler(newConfig) {
-  config = Object.assign(Object.assign({}, config), newConfig);
-}
-function getSchedulerMetrics(reset = false) {
-  const snapshot = Object.assign({}, metrics);
-  if (reset) {
-    metrics = {
-      drainCycles: 0,
-      tasksExecuted: 0,
-      maxQueueLength: 0,
-      yields: 0,
-      lastDrainDurationMs: 0,
-      totalDrainDurationMs: 0
-    };
-  }
-  return snapshot;
-}
-function postTask(t) {
-  q.push(t);
-  if (config.instrumentation && q.length > metrics.maxQueueLength) {
-    metrics.maxQueueLength = q.length;
-  }
-  if (!draining) {
-    draining = true;
-    Promise.resolve().then(drain);
-  }
-}
-function drain() {
-  return __awaiter(this, void 0, void 0, function* () {
-    const start = config.instrumentation ? performance.now() : 0;
-    if (config.instrumentation) metrics.drainCycles++;
-    let tasksSinceYield = 0;
-    while (q.length) {
-      const t = q.shift();
-      if (!t) break;
-      try {
-        t();
-      } catch (e) {
-        console.error('[EnterpriseScheduler]', e);
-      }
-      tasksSinceYield++;
-      if (config.instrumentation) metrics.tasksExecuted++;
-      if (tasksSinceYield >= config.yieldEveryTasks || config.instrumentation && performance.now() - start >= config.yieldEveryMs) {
-        if (config.instrumentation) metrics.yields++;
-        tasksSinceYield = 0;
-        yield Promise.resolve();
-      }
-    }
-    if (config.instrumentation) {
-      const duration = performance.now() - start;
-      metrics.lastDrainDurationMs = duration;
-      metrics.totalDrainDurationMs += duration;
-    }
-    draining = false;
-  });
-}
-
-export { configureScheduler, getSchedulerMetrics, postTask };

package/dist/lib/thread-pools.js

@@ -1,13 +0,0 @@
-import { __awaiter } from 'tslib';
-
-function createMockPool() {
-  return {
-    run(fn, ...args) {
-      return __awaiter(this, void 0, void 0, function* () {
-        return fn(...args);
-      });
-    }
-  };
-}
-
-export { createMockPool };

package/src/lib/scheduler.d.ts

@@ -1,18 +0,0 @@
-export type Task = () => void;
-interface SchedulerConfig {
-    yieldEveryTasks?: number;
-    yieldEveryMs?: number;
-    instrumentation?: boolean;
-}
-interface SchedulerMetrics {
-    drainCycles: number;
-    tasksExecuted: number;
-    maxQueueLength: number;
-    yields: number;
-    lastDrainDurationMs: number;
-    totalDrainDurationMs: number;
-}
-export declare function configureScheduler(newConfig: SchedulerConfig): void;
-export declare function getSchedulerMetrics(reset?: boolean): SchedulerMetrics;
-export declare function postTask(t: Task): void;
-export {};

package/src/lib/thread-pools.d.ts

@@ -1,4 +0,0 @@
-export interface WorkerPool {
-    run<T, A extends unknown[]>(fn: (...args: A) => T, ...args: A): Promise<T>;
-}
-export declare function createMockPool(): WorkerPool;