@signal-tree/angular 15.1.2 → 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

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.2",
+  "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.2"
+    "@signal-tree/kernel": "15.1.3"
   },
   "peerDependencies": {
     "@angular/core": "^20.0.0 || ^21.0.0 || ^22.0.0",

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>;