@signal-tree/angular 15.1.1 → 15.1.2

package/README.md

@@ -81,3 +81,29 @@ const profileModel = toWritableSignal(tree.$.profile, injector, {
 Application components
 should normally receive a read-only `$` plus explicit operation services for
 writes and asynchronous work.
+
+## Initial values and external reactivity
+
+Pass initial values to `signalTree()`, not existing Angular signals. Direct
+signals (including readonly and computed signals) at the root or a nested branch
+are rejected with a path-specific error, and known signal types are rejected by
+TypeScript. SignalTree creates its own native signals so it owns their writes.
+
+```ts
+import { signal, untracked } from '@angular/core';
+import { leaf, signalTree } from '@signal-tree/angular';
+
+const existing = signal(1);
+const tree = signalTree({ count: leaf(untracked(existing)) });
+```
+
+This takes an independent snapshot; later writes to `existing` do not update
+`tree`. For an object snapshot, copy the value too if you need independent object
+identity. `leaf(existing)` explicitly stores the signal itself as data. Reading
+that leaf returns the original signal; its inner writes remain outside tree
+transactions and restoration.
+
+Validation stops at explicit `leaf(...)`, marker definitions, arrays and built-in
+terminal values. Their contents remain data, not separately owned tree locations.
+Ordinary functions remain valid callable data. These checks apply to initial
+construction, not arbitrary later writes or foreign reactivity from other libraries.

package/dist/index.js

@@ -1 +1 @@
-import{ANGULAR_OBSERVATION_ADAPTER}from"./lib/observation-adapter.js";import{createSignalTreeFactory}from"@signal-tree/kernel/adapter";import{asReadonly as asReadonly$1}from"@signal-tree/kernel";export*from"@signal-tree/kernel";import{defineStore}from"./lib/define-store.js";import{toWritableSignal}from"./lib/to-writable-signal.js";const signalTree=createSignalTreeFactory(ANGULAR_OBSERVATION_ADAPTER);const asReadonly=asReadonly$1;export{asReadonly,defineStore,signalTree,toWritableSignal};
+import{ANGULAR_OBSERVATION_ADAPTER}from"./lib/observation-adapter.js";import{createSignalTreeFactory}from"@signal-tree/kernel/adapter";import{asReadonly as asReadonly$1}from"@signal-tree/kernel";export*from"@signal-tree/kernel";import{prepareConstructionInput}from"./lib/construction-input.js";import{defineStore}from"./lib/define-store.js";import{toWritableSignal}from"./lib/to-writable-signal.js";const createAngularTree=createSignalTreeFactory(ANGULAR_OBSERVATION_ADAPTER);const signalTree=(initialState,config)=>createAngularTree(prepareConstructionInput(initialState),config);const asReadonly=asReadonly$1;export{asReadonly,defineStore,signalTree,toWritableSignal};

package/dist/lib/construction-input.js

@@ -0,0 +1 @@
+import{isSignal}from"@angular/core";import{isConstructionBranch}from"@signal-tree/kernel/adapter";function prepareConstructionInput(initialState){const branches=new WeakMap;const visit=(value,path)=>{if(isSignal(value)){throw new TypeError(`SignalTree: Angular signal at ${path}. Pass an initial value or leaf(untracked(existing)) for an independent snapshot. Use leaf(existing) only to store the signal as data; its writes remain external to the tree.`)}if(!isConstructionBranch(value))return value;const previous=branches.get(value);if(previous)return previous;const prepared=Object.create(null);branches.set(value,prepared);for(const key of Object.getOwnPropertySymbols(value)){const descriptor=Object.getOwnPropertyDescriptor(value,key);if(descriptor)Object.defineProperty(prepared,key,descriptor)}for(const[key,child]of Object.entries(value)){prepared[key]=key==="__proto__"?child:visit(child,`${path}[${JSON.stringify(key)}]`)}return prepared};return visit(initialState,"$")}export{prepareConstructionInput};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signal-tree/angular",
-  "version": "15.1.1",
+  "version": "15.1.2",
   "description": "Angular realization for SignalTree.",
   "license": "Apache-2.0",
   "type": "module",
@@ -25,7 +25,7 @@
     "llms.txt"
   ],
   "dependencies": {
-    "@signal-tree/kernel": "15.1.1"
+    "@signal-tree/kernel": "15.1.2"
   },
   "peerDependencies": {
     "@angular/core": "^20.0.0 || ^21.0.0 || ^22.0.0",

package/src/index.d.ts

@@ -1,7 +1,9 @@
 /** Angular observation plus the complete SignalTree application surface. */
 import './lib/carrier.js';
-import type { AccessibleNodeOf, EntityNodeOf, EntitySignalOf, EntitySignalWithSlicesOf, ISignalTreeOf, LeafOf, ReadonlyStoreOf, ReadonlyViewOf, SignalTreeFactoryOf, TreeNodeOf } from '@signal-tree/kernel/adapter';
-export declare const signalTree: SignalTreeFactoryOf<"angular">;
+import type { AccessibleNodeOf, EntityNodeOf, EntitySignalOf, EntitySignalWithSlicesOf, ISignalTreeOf, LeafOf, ReadonlyStoreOf, ReadonlyViewOf, TreeNodeOf } from '@signal-tree/kernel/adapter';
+import { type FrameworkSignalTreeFactory } from './lib/construction-input.js';
+/** Construct native Angular leaves from values; external signals require leaf(). */
+export declare const signalTree: FrameworkSignalTreeFactory;
 export type TreeNode<T> = TreeNodeOf<T, 'angular'>;
 export type WritableLeaf<T> = LeafOf<T, 'angular'>;
 export type AccessibleNode<T> = AccessibleNodeOf<T, 'angular'>;

package/src/lib/construction-input.d.ts

@@ -0,0 +1,9 @@
+import { type Signal } from '@angular/core';
+import type { SignalTreeFactoryOf } from '@signal-tree/kernel/adapter';
+export type FrameworkSignalTreeFactory = SignalTreeFactoryOf<'angular', Signal<unknown>>;
+/**
+ * Read each branch property once, so accessor-backed definitions cannot change
+ * between validation and construction. Terminal data retains its identity.
+ * No reactive primitive is read, subscribed to, or adopted here.
+ */
+export declare function prepareConstructionInput(initialState: object): object;