@signal-tree/angular 15.1.1 → 15.1.3

package/README.md

@@ -23,8 +23,82 @@ the complete SignalTree facade for Angular applications: import `signalTree`,
 markers, enhancers, and types from this package rather than mixing kernel
 imports into Angular application code.
 
-Angular applications should construct state through this package, not through
-the neutral kernel package:
+## Application-store ownership
+
+Use `defineStore(() => signalTree(...))` for an Angular-owned application store.
+`signalTree` selects Angular reactivity and constructs the tree; `defineStore`
+creates its injectable token and binds destruction to the providing injector.
+The factory runs in injection context and must return a fresh owned object or
+function, not a primitive or a tree borrowed from another owner. Cleanup errors
+are reported with Angular's default `ErrorHandler` so later store cleanup can
+still run. This does not resolve the application's custom handler: that handler
+may itself depend on a store, and the owning injector is already destroyed when
+teardown runs.
+
+```ts
+import { inject } from '@angular/core';
+import { defineStore, signalTree } from '@signal-tree/angular';
+
+export const SettingsStore = defineStore(() => signalTree({ theme: 'light' }), { providedIn: 'root' });
+
+// In an Angular injection context:
+const settings = inject(SettingsStore);
+```
+
+Omit `providedIn` and add the token to a component's `providers` for a separate
+store per component. A consumer borrowing an injected store does not destroy
+it. Do not wrap a borrowed tree in another `defineStore`: that registers a
+second owner. Root/request injectors must themselves be destroyed by the
+application or SSR host at the end of their lifetime.
+
+### Readonly state and operations share one owner
+
+`expose: 'readonly'` narrows the token for **all** consumers, including an Ops
+service. It does not create a separate writable injection path. When components
+need readonly state and operations need writes, keep the owner token internal
+and expose its readonly `$` through a non-owning Angular provider:
+
+```ts
+import { inject, Injectable, InjectionToken, type Provider } from '@angular/core';
+import { asReadonly, defineStore, signalTree } from '@signal-tree/angular';
+
+const CounterTree = defineStore(() => signalTree({ count: 0 }));
+
+@Injectable()
+export class CounterOps {
+  private readonly tree = inject(CounterTree);
+  readonly state = asReadonly(this.tree).$;
+
+  increment(): void {
+    this.tree.$.count.update((count) => count + 1);
+  }
+}
+
+export const COUNTER_STATE = new InjectionToken<CounterOps['state']>('CounterState');
+
+export function provideCounterStore(): Provider[] {
+  return [CounterTree, CounterOps, { provide: COUNTER_STATE, useFactory: () => inject(CounterOps).state }];
+}
+```
+
+Register `provideCounterStore()` at application bootstrap for one application
+owner, or in a component's `providers` for independent local owners. Register
+Ops and the reader together with the tree at the intended scope. Components use
+`inject(COUNTER_STATE).count()` and `inject(CounterOps).increment()`; only
+`CounterTree` owns teardown. The reader exposes neither writers nor `destroy()`.
+Readonly remains a compile-time boundary, not runtime access control.
+
+For stores where every injected consumer should be readonly, the existing
+`expose: 'readonly'` option is sufficient. Prefer an inferred config literal or
+`{ expose: 'readonly' } satisfies DefineStoreConfig`; widening to
+`DefineStoreConfig` erases the information required to choose the readonly
+return type.
+
+## Tree construction
+
+Inside the store factory, declare state, enhancers, and derived recipes together.
+The following standalone example uses explicit cleanup; this lower-level form
+also serves tests and intentionally manual lifetimes:
 
 ```ts
 import { asReadonly, batching, entityMap, signalTree } from '@signal-tree/angular';
@@ -53,6 +127,7 @@ const tree = signalTree(
 
 const reader = asReadonly(tree);
 reader.$.selectedName();
+tree.destroy(); // End the explicitly owned standalone example.
 ```
 
 There is one construction grammar: state, enhancers, and one derived factory are
@@ -81,3 +156,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/dist/lib/define-store.js

@@ -1 +1 @@
-import{__decorate,__metadata}from"tslib";import{Injectable,inject,DestroyRef}from"@angular/core";function defineStore(factory,config={}){let SignalTreeStore=class SignalTreeStore{constructor(){const tree=factory();inject(DestroyRef).onDestroy(()=>{try{tree.destroy?.()}catch{}});return tree}};SignalTreeStore=__decorate([Injectable({providedIn:config.providedIn??null}),__metadata("design:paramtypes",[])],SignalTreeStore);return SignalTreeStore}export{defineStore};
+import{__decorate,__metadata}from"tslib";import{Injectable,inject,DestroyRef,ErrorHandler}from"@angular/core";function defineStore(factory,config={}){let SignalTreeStore=class SignalTreeStore{constructor(){const tree=factory();if(tree===null||typeof tree!=="object"&&typeof tree!=="function"){throw new TypeError("[SignalTree] defineStore factory must return an object or function.")}inject(DestroyRef).onDestroy(()=>{try{const destroy=tree.destroy;if(typeof destroy==="function")destroy.call(tree)}catch(error){new ErrorHandler().handleError(error)}});return tree}};SignalTreeStore=__decorate([Injectable({providedIn:config.providedIn??null}),__metadata("design:paramtypes",[])],SignalTreeStore);return SignalTreeStore}export{defineStore};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signal-tree/angular",
-  "version": "15.1.1",
+  "version": "15.1.3",
   "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.3"
   },
   "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;

package/src/lib/define-store.d.ts

@@ -5,9 +5,9 @@ import type { ISignalTreeOf, ReadonlyStoreOf } from '@signal-tree/kernel/adapter
  */
 export interface DefineStoreConfig {
     /**
-     * Where to provide the store. `'root'`/`'platform'` make it an app-wide
-     * singleton (like `@Injectable({ providedIn: 'root' })`); omit/`null` to
-     * provide it locally via a component/route `providers` array.
+     * `'root'` provides an application singleton. `'platform'` shares the store
+     * across applications on that platform; do not use it for request-local state.
+     * Omit/`null` to provide it locally via a component/route `providers` array.
      */
     providedIn?: 'root' | 'platform' | null;
     /**
@@ -21,9 +21,10 @@ export interface DefineStoreConfig {
      * it does not protect against a deliberate `as any` bypass — it protects
      * the common case where an AI agent or developer reaches for a
      * `.set()`/mutator that simply isn't offered on the injected type. Use it
-     * for components that should only read the store, pairing it with a
-     * separate `@Injectable` Ops service for writes (see "Production
-     * architecture" in the root README).
+     * when every consumer of this token should receive a readonly tree. An Ops
+     * service injecting this same token is also readonly. For separate readers
+     * and writers, own one writable tree and expose a non-owning readonly `$`
+     * token; see the Angular package README's ownership example.
      *
      * Only accepted when the factory returns a real tree
      * (`signalTree(...)`-shaped); combining it with
@@ -36,14 +37,24 @@ export interface DefineStoreConfig {
  * idiomatic Angular DI pattern for a tree, comparable to NgRx SignalStore's
  * `signalStore()`.
  *
- * `inject(MyStore)` resolves to the **real tree** — callable, with `$` and any
+ * `inject(MyStore)` resolves to the **real tree** — with `$` and any
  * configured enhancer methods — not a wrapper. The tree's
  * `destroy()` is tied to the host injector's lifecycle via `DestroyRef`, so a
  * component-provided store tears down with the component and a root store with
  * the app.
  *
  * The factory runs inside Angular's injection context, so it may call `inject()`
- * (e.g. to read other services).
+ * (e.g. to read other services). Return a fresh owned object or function for
+ * each providing injector, never a tree borrowed from another owner. The
+ * factory selects the realization: import `signalTree` from this Angular
+ * facade, not the neutral kernel. Use ordinary DI aliases for borrowed views;
+ * another `defineStore` would register another destruction owner.
+ *
+ * Primitive factory results are rejected. If the returned object has a
+ * `destroy()` method, failures are reported with Angular's default `ErrorHandler`,
+ * not resolved from DI: an application handler may itself depend on this store,
+ * and the owning injector is already destroyed when cleanup runs. Reporting
+ * allows sibling cleanup to continue. SignalTree destruction is idempotent.
  *
  * @example
  * ```ts
@@ -90,6 +101,6 @@ export declare function defineStore<T, A>(factory: () => ISignalTreeOf<T, 'angul
  * literal (or `as const`). Deliberate: this cliff is what makes
  * `expose: 'readonly'` misuse a compile error instead of a silent no-op.
  */
-export declare function defineStore<R>(factory: () => R, config?: DefineStoreConfig & {
+export declare function defineStore<R extends object>(factory: () => R, config?: DefineStoreConfig & {
     expose?: undefined;
 }): Type<R>;