@signaltree/core 9.2.2 → 9.3.0

package/README.md

@@ -305,7 +305,7 @@ console.log(tree.$.message()); // 'Hello World'
 //   tree.$.message.set('Updated!');
 //   tree.$.count.update((n) => n + 1);
 // See: https://github.com/JBorgia/signaltree/blob/main/packages/callable-syntax/README.md
-tree.$.count(5);          // requires @signaltree/callable-syntax transform
+tree.$.count(5); // requires @signaltree/callable-syntax transform
 tree.$.message('Updated!'); // requires @signaltree/callable-syntax transform
 
 // Use in an Angular component
@@ -343,6 +343,10 @@ const tree = signalTree({
 });
 
 // Access nested signals with full type safety
+// Requires @signaltree/callable-syntax. Without the transform, use:
+// tree.$.user.name.set('Jane Doe');
+// tree.$.user.preferences.theme.set('light');
+// tree.$.ui.loading.set(true);
 tree.$.user.name('Jane Doe');
 tree.$.user.preferences.theme('light');
 tree.$.ui.loading(true);
@@ -500,6 +504,8 @@ const tree = signalTree<AppState>({
 });
 
 // Complex updates with type safety
+// Requires @signaltree/callable-syntax. Without the transform, use
+// tree.set((state) => ({ ... })) or leaf .set() / .update() calls instead.
 tree((state) => ({
   auth: {
     ...state.auth,
@@ -671,16 +677,15 @@ All enhancers are exported directly from `@signaltree/core`:
 ```typescript
 import { signalTree, effects } from '@signaltree/core';
 
-const tree = signalTree({ count: 0, user: { name: 'Alice' } })
-  .with(effects());
+const tree = signalTree({ count: 0, user: { name: 'Alice' } }).with(effects());
 
 // Subscribe with automatic cleanup on destroy
-const unsub = tree.subscribe(state => {
+const unsub = tree.subscribe((state) => {
   console.log('State changed:', state.count);
 });
 
 // Effect with cleanup callback
-const cleanup = tree.effect(state => {
+const cleanup = tree.effect((state) => {
   console.log('Count:', state.count);
   return () => console.log('Previous effect cleaned up');
 });
@@ -708,7 +713,7 @@ import { signalTree, batching, devTools } from '@signaltree/core';
 
 // Apply enhancers by chaining — each .with() takes a single enhancer
 const tree = signalTree({ count: 0 })
-  .with(batching())  // Performance optimization
+  .with(batching()) // Performance optimization
   .with(devTools()); // Development tools
 ```
 
@@ -721,8 +726,7 @@ import { signalTree, batching } from '@signaltree/core';
 const tree = signalTree({
   products: entityMap<Product>(),
   ui: { loading: false },
-})
-  .with(batching()); // Batch updates for optimal rendering
+}).with(batching()); // Batch updates for optimal rendering
 
 // Entity CRUD operations
 tree.$.products.addOne(newProduct);
@@ -741,11 +745,14 @@ const tree = signalTree({
   user: null as User | null,
   preferences: { theme: 'light' },
 })
-  .with(serialization({  // Auto-save to localStorage
-    autoSave: true,
-    storage: 'localStorage',
-  }))
-  .with(timeTravel());   // Undo/redo support
+  .with(
+    serialization({
+      // Auto-save to localStorage
+      autoSave: true,
+      storage: 'localStorage',
+    })
+  )
+  .with(timeTravel()); // Undo/redo support
 
 // For async operations, use manual async or async helpers
 async function fetchUser(id: string) {
@@ -776,8 +783,8 @@ Enhancers can declare metadata for automatic dependency resolution:
 ```typescript
 // Chain enhancers — each .with() takes a single enhancer
 const tree = signalTree(state)
-  .with(batching())   // Requires: core, provides: batching
-  .with(devTools());  // Requires: core, provides: debugging
+  .with(batching()) // Requires: core, provides: batching
+  .with(devTools()); // Requires: core, provides: debugging
 ```
 
 #### Core Stubs
@@ -1159,6 +1166,8 @@ LoadingState.Error; // 'error'
 
 Auto-syncs state to localStorage with versioning and migration support.
 
+> ⚠️ **Read first:** [Persistence and Security](../../docs/guides/persistence-and-security.md) covers the threat model and what `stored()` is — and isn't — appropriate for. Short version: fine for UI prefs, never for tokens, secrets, or PII.
+
 ```typescript
 import { signalTree, stored, createStorageKeys, clearStoragePrefix } from '@signaltree/core';
 
@@ -1653,18 +1662,24 @@ const tree = signalTree({
     data: { users: [], posts: [] },
   },
 })
-  .with(batching())                       // Performance
-  .with(serialization({                   // State persistence
-    autoSave: true,
-    storage: 'localStorage',
-  }))
+  .with(batching()) // Performance
+  .with(
+    serialization({
+      // State persistence
+      autoSave: true,
+      storage: 'localStorage',
+    })
+  )
   .with(timeTravel({ maxHistorySize: 50 })) // Undo/redo
-  .with(devTools({                        // Debug tools (dev only)
-    name: 'MyApp',
-    enableTimeTravel: true,
-    includePaths: ['app.*', 'ui.*'],
-    formatPath: (path) => path.replace(/\.(\d+)/g, '[$1]'),
-  }));
+  .with(
+    devTools({
+      // Debug tools (dev only)
+      name: 'MyApp',
+      enableTimeTravel: true,
+      includePaths: ['app.*', 'ui.*'],
+      formatPath: (path) => path.replace(/\.(\d+)/g, '[$1]'),
+    })
+  );
 
 // Rich feature set available
 async function fetchUser(id: string) {
@@ -2159,7 +2174,7 @@ Consider separate packages when you need:
 
 ### Case Study
 
-Measured from a production Angular mobile application migrating from NgRx Signal Store to SignalTree. Results reflect one team's experience; your mileage will vary depending on app complexity and existing architecture.
+Snapshot from one production Angular mobile app's NgRx Signal Store → SignalTree migration. Original migration measured ~11,700 → ~2,800 lines of state code (~76%) and ~50KB → ~27KB gzipped state bundle (~46%). Both codebases have continued to evolve; re-measuring today the same scope yields a 60–70% reduction depending on definition (apps-only vs apps+libs, narrow vs broad import filter). The directional finding is reproducible — the exact percentages are not. **YMMV** — your migration's reduction depends on app complexity, prior architecture, and how heavily the original code leaned on custom `withX` helpers. The single biggest driver of the savings is cross-cutting concerns (devtools, error banners, telemetry, refresh handling) moving from per-store composition to tree-level enhancers.
 
 | Metric | NgRx | SignalTree | Change |
 | --- | --- | --- | --- |

package/dist/enhancers/devtools/devtools.js

@@ -3,6 +3,7 @@ import { copyTreeProperties } from '../utils/copy-tree-properties.js';
 import { applyState, snapshotState } from '../../lib/utils.js';
 import { interceptLeafSignals } from '../../lib/internals/intercept-leaf-signals.js';
 import { getPathNotifier } from '../../lib/path-notifier.js';
+import { withWriteContext } from '../../lib/write-context.js';
 import { ENHANCER_META } from '../../lib/types.js';
 
 function createActivityTracker(options) {
@@ -904,11 +905,16 @@ function devTools(config = {}) {
       if (state === undefined || state === null) return;
       isApplyingExternalState = true;
       try {
-        if ('$' in tree) {
-          applyState(tree.$, state);
-        } else {
-          originalTreeCall(state);
-        }
+        withWriteContext({
+          intent: 'system',
+          source: 'time-travel'
+        }, () => {
+          if ('$' in tree) {
+            applyState(tree.$, state);
+          } else {
+            originalTreeCall(state);
+          }
+        });
       } finally {
         isApplyingExternalState = false;
         lastSnapshot = readSnapshot();

package/dist/enhancers/time-travel/time-travel.js

@@ -1,6 +1,7 @@
 import { snapshotState } from '../../lib/utils.js';
 import { interceptLeafSignals } from '../../lib/internals/intercept-leaf-signals.js';
 import { getPathNotifier } from '../../lib/path-notifier.js';
+import { withWriteContext } from '../../lib/write-context.js';
 import { deepEqual, deepClone } from './utils.js';
 import { ENHANCER_META } from '../../lib/types.js';
 
@@ -122,11 +123,16 @@ class TimeTravelManager {
     return this.currentIndex < this.history.length - 1;
   }
   restoreState(state) {
-    if (this.restoreStateFn) {
-      this.restoreStateFn(state);
-    } else {
-      this.tree(state);
-    }
+    withWriteContext({
+      intent: 'system',
+      source: 'time-travel'
+    }, () => {
+      if (this.restoreStateFn) {
+        this.restoreStateFn(state);
+      } else {
+        this.tree(state);
+      }
+    });
   }
 }
 function timeTravel(config = {}) {

package/dist/index.js

@@ -1,4 +1,6 @@
 export { signalTree } from './lib/signal-tree.js';
+export { getActiveWriteContext, withWriteContext } from './lib/write-context.js';
+export { interceptLeafSignals } from './lib/internals/intercept-leaf-signals.js';
 export { ENHANCER_META } from './lib/types.js';
 export { derivedFrom, externalDerived } from './lib/internals/derived-types.js';
 export { isDerivedMarker } from './lib/markers/derived.js';

package/dist/lib/internals/intercept-leaf-signals.js

@@ -1,3 +1,5 @@
+import { getActiveWriteContext } from '../write-context.js';
+
 function interceptLeafSignals(root, onWrite, options = {}) {
   const restorers = [];
   const seen = new WeakSet();
@@ -38,13 +40,13 @@ function interceptLeafSignals(root, onWrite, options = {}) {
           const prev = original();
           originalSet(value);
           const next = original();
-          if (next !== prev) onWrite(childPath, next, prev);
+          if (next !== prev) onWrite(childPath, next, prev, getActiveWriteContext());
         };
         original.update = updater => {
           const prev = original();
           originalUpdate(updater);
           const next = original();
-          if (next !== prev) onWrite(childPath, next, prev);
+          if (next !== prev) onWrite(childPath, next, prev, getActiveWriteContext());
         };
         continue;
       }

package/dist/lib/write-context.js

@@ -0,0 +1,15 @@
+let activeContext;
+function withWriteContext(meta, fn) {
+  const previous = activeContext;
+  activeContext = meta;
+  try {
+    return fn();
+  } finally {
+    activeContext = previous;
+  }
+}
+function getActiveWriteContext() {
+  return activeContext;
+}
+
+export { getActiveWriteContext, withWriteContext };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaltree/core",
-  "version": "9.2.2",
+  "version": "9.3.0",
   "description": "Reactive JSON for Angular. JSON branches, reactive leaves. No actions. No reducers. No selectors.",
   "license": "MIT",
   "type": "module",

package/src/index.d.ts

@@ -1,5 +1,7 @@
 export { signalTree } from './lib/signal-tree';
-export type { ISignalTree, SignalTree, SignalTreeBase, TreeNode, CallableWritableSignal, AccessibleNode, NodeAccessor, Primitive, NotFn, TreeConfig, Enhancer, EnhancerMeta, EnhancerWithMeta, EntitySignal, EntityMapMarker, EntityConfig, MutationOptions, AddOptions, AddManyOptions, TimeTravelEntry, TimeTravelMethods, EnhancerCleanup, EffectsMethods, } from './lib/types';
+export type { ISignalTree, SignalTree, SignalTreeBase, TreeNode, CallableWritableSignal, AccessibleNode, NodeAccessor, Primitive, NotFn, TreeConfig, Enhancer, EnhancerMeta, EnhancerWithMeta, EntitySignal, EntityMapMarker, EntityConfig, MutationOptions, AddOptions, AddManyOptions, TimeTravelEntry, TimeTravelMethods, EnhancerCleanup, EffectsMethods, UpdateMetadata, } from './lib/types';
+export { withWriteContext, getActiveWriteContext } from './lib/write-context';
+export { interceptLeafSignals } from './lib/internals/intercept-leaf-signals';
 export { entityMap } from './lib/types';
 export type { ProcessDerived, DeepMergeTree, DerivedFactory, WithDerived, } from './lib/internals/derived-types';
 export { derivedFrom, externalDerived } from './lib/internals/derived-types';

package/src/lib/internals/intercept-leaf-signals.d.ts

@@ -1 +1,4 @@
-export {};
+import type { UpdateMetadata } from '../types';
+export declare function interceptLeafSignals(root: unknown, onWrite: (path: string, next: unknown, prev: unknown, meta?: UpdateMetadata) => void, options?: {
+    maxDepth?: number;
+}): () => void;

package/src/lib/types.d.ts

@@ -3,6 +3,14 @@ import { FormMarker, FormSignal } from './markers/form';
 import { StatusMarker, StatusSignal } from './markers/status';
 import { StoredMarker, StoredSignal } from './markers/stored';
 import { SecurityValidatorConfig } from './security/security-validator';
+export interface UpdateMetadata {
+    intent?: 'hydrate' | 'reset' | 'bulk' | 'migration' | 'user' | 'system';
+    source?: 'serialization' | 'time-travel' | 'devtools' | 'user' | 'system';
+    suppressGuardrails?: boolean;
+    correlationId?: string;
+    timestamp?: number;
+    [key: string]: unknown;
+}
 export interface TimeTravelConfig {
     enabled?: boolean;
     maxHistorySize?: number;

package/src/lib/write-context.d.ts

@@ -0,0 +1,3 @@
+import type { UpdateMetadata } from './types';
+export declare function withWriteContext<R>(meta: UpdateMetadata, fn: () => R): R;
+export declare function getActiveWriteContext(): UpdateMetadata | undefined;