r-state-tree 0.7.0 → 0.8.0

package/README.md

@@ -62,7 +62,7 @@ export default defineConfig({
 
 ## Core concepts
 
-- Stores: application/view state containers. Create with `createStore()`, attach with `mount()`. Compose with `@child` (single or arrays, stable via `{ key }`). React to changes with `effect`/`reaction` and store lifecycles (`storeDidMount`/`storeWillUnmount`). Update reactive `props` via `updateStore()`.
+- Stores: application/view state containers. Create with `createStore()`, attach with `mount()`, and dispose with `Symbol.dispose`. Compose with `@child` and register owned `effect`/`reaction` behavior in constructors. Update reactive `props` via `updateStore()`.
 - Models: domain state containers. Create with `Model.create()`. Persistent via snapshots (`toSnapshot`, `applySnapshot`, `onSnapshot`, diffs via `onSnapshotDiff`). Structure with `@state`, `@child`, identifiers via `@id`, and references via `@modelRef`.
 - Context: pass data through Store/Model trees without prop drilling using `createContext<T>()`, `[Context.provide]`, and `Context.consume(this)`. Context is reactive and can be overridden by descendants.
 - Reactivity: powered by signals. Use `observable()`, `computed` / `@computed`, `effect`, `reaction`, `batch`, and `untracked` for precise updates.
@@ -139,7 +139,7 @@ app.todo.title;
 
 - Always create with `createStore()` and attach with `mount()`. Stores cannot be constructed with `new` directly.
 - Prefer no custom constructor. Type stores as `Store<Props>` and access props via `this.props`.
-- If a constructor is necessary, call `super(props)` exactly once and keep it minimal; put effects in `storeDidMount`.
+- Constructors may register framework-owned reactions and effects after `super(props)`. Gate external resource acquisition on `isMounted` and return cleanup from effects.
 - Do not shadow or re-declare `props` as a class field; `props` is read-only. Use the generic `Store<{ ... }>` for typing.
 
 ```ts
@@ -203,20 +203,28 @@ class ItemsStore extends Store {
 }
 ```
 
-### Lifecycle hooks
+### Store lifetime and owned effects
 
-Stores support lifecycle methods:
+Mounted stores expose reactive `isMounted` state and implement `Disposable`:
 
 ```ts
 class TodoStore extends Store {
-	storeDidMount() {
-		console.log("Store mounted");
-	}
-
-	storeWillUnmount() {
-		console.log("Store will unmount");
+	constructor(props) {
+		super(props);
+		this.effect(() => {
+			if (!this.isMounted) return;
+			const connection = connect();
+			return () => connection.close();
+		});
 	}
 }
+
+const store = mount(createStore(TodoStore));
+store[Symbol.dispose]();
+
+{
+	using store = mount(createStore(TodoStore));
+} // Symbol.dispose is called automatically
 ```
 
 ### Reactions
@@ -225,10 +233,11 @@ Create side effects that run when reactive values change:
 
 ```ts
 class TodoStore extends Store {
-	storeDidMount() {
+	constructor(props) {
+		super(props);
 		this.reaction(
 			() => this.props.title,
-			(title) => console.log("Title changed:", title)
+			(title, previousTitle) => console.log(previousTitle, "->", title)
 		);
 	}
 }
@@ -834,37 +843,55 @@ const off = onSnapshot(list, (snap) => {
 
 Mutate Models through domain methods and let snapshots record changes automatically.
 
-### Model lifecycle hooks
+### Model creation and named factories
 
-Models support lifecycle methods:
+`Model.create()` accepts a canonical snapshot. For defaults, identifier generation, normalization, migrations, or external API formats, use a named static factory that prepares the input before calling `create()`:
 
 ```ts
 class TodoModel extends Model {
-	@child tags: TagModel[] = [];
+	@id id = "";
+	@state title = "";
 
-	modelDidInit(snapshot?, ...args: unknown[]) {
-		// Called when model is created via Model.create()
-		// Receives the snapshot and any additional arguments passed to create()
-		console.log("Model initialized", snapshot);
+	static new(title = "Untitled") {
+		return this.create({
+			id: crypto.randomUUID(),
+			title: title.trim(),
+		});
 	}
 
-	modelDidAttach() {
-		// Called when this model is attached as a child to another model
-		console.log("Model attached to parent");
+	static fromApi(input: ApiTodo) {
+		return this.create({
+			id: input.todo_id,
+			title: input.name.trim(),
+		});
 	}
+}
+
+const todo = TodoModel.new("  Write documentation  ");
+todo.title; // "Write documentation"
+```
+
+This keeps snapshot hydration predictable: `create(snapshot)` and `applySnapshot(model, snapshot)` both consume the same canonical shape. Named factories make non-canonical inputs and generated values explicit and independently typed. Nested snapshots must already be canonical.
+
+### Model attachment and disposal
+
+The public `parent` relationship is reactive. Register a model-owned reaction in the constructor to observe attachment and detachment:
 
-	modelWillDetach() {
-		// Called when this model is detached from its parent
-		console.log("Model will be detached");
+```ts
+class TodoModel extends Model {
+	@child tags: TagModel[] = [];
+
+	constructor() {
+		super();
+		this.reaction(() => this.parent, (parent, previousParent) => {
+			if (previousParent) console.log("detached", previousParent);
+			if (parent) console.log("attached", parent);
+		});
 	}
 }
 ```
 
-When to use each:
-
-- `modelDidInit`: initialize/normalize data based on the initial snapshot.
-- `modelDidAttach`: link to other models or read context after the model is part of a tree.
-- `modelWillDetach`: cleanup before the model is removed or replaced.
+Detachment is reversible; model-owned effects survive reattachment. `model[Symbol.dispose]()` is terminal and recursively disposes owned child models, but never model refs.
 
 ### Model configuration
 
@@ -883,7 +910,7 @@ class User extends Model {
 class TodoModel extends Model {
 	@id id = 0;
 	@state title = "";
-	@modelRef assignee?: User; // Reference to another model by ID
+	@modelRef(User) assignee?: User; // Reference to another model by ID
 	@child metadata = MetadataModel.create(); // Nested child model
 	@child tags: TagModel[] = []; // Array of child models
 }
@@ -928,14 +955,14 @@ class TodoModel extends Model {
 
 ### Model references
 
-Reference models by ID using `@modelRef` (or `static types`):
+Reference models by ID using `@modelRef(ModelType)` (or `modelRef(ModelType)` in `static types`). The model constructor is required because identifiers are namespaced by model type:
 
 ```ts
 class ProjectModel extends Model {
 	@id id = 0;
 	@child users: User[] = [];
-	@modelRef owner?: User; // Single reference
-	@modelRef assignees: User[] = []; // Array of references
+	@modelRef(User) owner?: User; // Single reference
+	@modelRef(User) assignees: User[] = []; // Array of references
 
 	assignOwner(userId: number) {
 		// Find user by ID and set as owner
@@ -983,9 +1010,10 @@ class ContainerModel extends Model {
 ## API surface
 
 - Stores
-  - `Store`, `createStore`, `mount`, `unmount`, `updateStore`
+  - `Store`, `createStore`, `mount`, `updateStore`
 - Models
-- - `Model`, configuration: decorators (`@state`, `@id`, `@child`, `@modelRef`) or `static types` with `state`, `id`, `child`, `modelRef`
+	- `Model`, `Model.create()`
+  - configuration: decorators (`@state`, `@id`, `@child`, `@modelRef`) or `static types` with `state`, `id`, `child`, `modelRef`
 - Store configuration
   - decorators (`@child`, `@model`) or `static types` with `child`, `model`
 - Snapshots
@@ -1049,12 +1077,21 @@ Use the observers/renderers provided by the signals bindings for your UI library
 
 ### Identifier and reference rules
 
-- `@id` values are unique within a tree. They cannot be cleared to `undefined` after assignment.
-- Identifiers can be reassigned to a new value (including in snapshots) as long as uniqueness is preserved.
-- `@modelRef` requires the referenced model to have an id and be attached to the tree; the ref becomes `undefined` when the model detaches.
+- `@id` values are unique per exact runtime Model class within a tree. Different Model classes may use the same id; subclasses have their own identifier namespace. IDs cannot be cleared to `undefined` after assignment.
+- Identifiers are mutable and can be reassigned (including in snapshots) as long as the new id is unused by that exact Model class. A failed reassignment preserves the old id and its references.
+- Use `@modelRef(ModelType)` or `modelRef(ModelType)` when ids can overlap across Model classes; references resolve only within the declared Model class.
+- `@modelRef(ModelType)` requires an explicit model constructor. The referenced model must have an id and be attached to the tree; the ref becomes `undefined` when the model detaches.
 - When a model is re-attached to the same tree, compatible refs restore automatically; attaching to a different root does not restore prior refs.
 - `@modelRef` and `@child` can switch between single and array at runtime; reactions observe the property itself rather than internal array mutations.
 
+Use `findModelById` for an optional, typed lookup within a model tree:
+
+```ts
+const user = findModelById(root, User, 1); // User | undefined
+```
+
+The lookup is reactive inside an effect or computed value. It returns `undefined` when the matching model changes its id, detaches, or is disposed.
+
 ### Snapshot diffs
 
 Use `onSnapshotDiff` to receive undo/redo payloads:
@@ -1167,17 +1204,22 @@ class ListModel extends Model {
 }
 ```
 
-Lifecycle hooks:
+Lifecycle registration:
 
 ```ts
 class M extends Model {
-	modelDidInit() {}
-	modelDidAttach() {}
-	modelWillDetach() {}
+	constructor() {
+		super();
+		this.reaction(() => this.parent, (parent, previousParent) => {});
+	}
 }
 class S extends Store {
-	storeDidMount() {}
-	storeWillUnmount() {}
+	constructor(props) {
+		super(props);
+		this.effect(() => {
+			if (!this.isMounted) return;
+		});
+	}
 }
 ```
 
@@ -1199,11 +1241,11 @@ const off = onSnapshot(m, (snap) =>
 - Mutating raw `@state` arrays/objects in place (`push`, `obj.x = 1`) and expecting snapshots to update. Snapshots are memoized; use reassignment or store `observable()` containers / `signal()` values in `@state`.
 - Passing observables to third‑party APIs that expect cloneable/serializable values (e.g. `structuredClone`). Use `source(value)` to get the backing value. It will be observable-free for values written via r-state-tree’s observable APIs (unwrap-on-write), but `source(...)` is **not** guaranteed observable-free if you manually seed observables into backing sources.
 - Creating child stores in constructors: `@child` must be on getters so identity and lifecycle can be managed by the framework.
-- Passing `models` into child stores during mount can create a recursive mount loop. If a child needs parent models, create the child store/model inside `storeDidMount` instead of wiring it through `models` during the mount cycle.
+- Passing `models` into child stores during mount can create a recursive mount loop. Break the ownership cycle rather than wiring models back through a child during mount.
 
 ### Circular store/model creation
 
-When child stores are created during mount with `models` that point back into the parent, it is easy to trigger an endless mount loop. The runtime now guards this by throwing a descriptive error (for example, `detected circular store/model creation while mounting ParentStore -> ChildStore.loop -> ...`). If you see this, move child creation into `storeDidMount` or break the cycle so that models are produced after the parent finishes mounting.
+When child stores are created during mount with `models` that point back into the parent, it is easy to trigger an endless mount loop. The runtime guards this with a descriptive circular-creation error. Break the cycle so models are produced independently of the child mount.
 
 ## LLM implementation checklist
 
@@ -1222,7 +1264,7 @@ When child stores are created during mount with `models` that point back into th
 - For `createStore` props, extend `Record<string, unknown>` only if needed; otherwise rely on proper prop types and context.
 - Avoid barrel files if they cause import confusion; prefer direct imports.
 - Keep file boundaries clean: one model per file; avoid piling multiple models together.
-- Do not shadow `props` or use constructors for work better suited to `storeDidMount`.
+- Do not shadow `props`; constructors are the registration phase for owned reactions and effects.
 - Use `@model`/`model` for injected models; `@child`/`child` for child stores; stable keys for arrays.
 
 ## Typing recipes
@@ -1236,10 +1278,10 @@ When child stores are created during mount with `models` that point back into th
 - Configuration (no decorators): `static types = { ... }` with `state`, `id`, `child`, `modelRef`, `model`, `computed`
 - Decorators (Models): `@state`, `@id`, `@child`, `@modelRef`
 - Decorators (Stores): `@child`, `@model`
-- Core: `createStore`, `mount`, `unmount`, `updateStore`
+- Core: `createStore`, `mount`, `Symbol.dispose`, `updateStore`
 - Snapshots: `onSnapshot`, `toSnapshot`, `applySnapshot`, `onSnapshotDiff`
-- Lifecycle: `storeDidMount`, `storeWillUnmount`, `modelDidInit`, `modelDidAttach`, `modelWillDetach`
-- Best practices: domain in Models; delegate from Stores; stable keys for `@child`; in-place mutations in Models; no effectful constructors; don’t shadow `props`.
+- Lifecycle: reactive `Store.isMounted`, reactive `Model.parent`, and owned `reaction`/`effect`
+- Best practices: domain in Models; delegate from Stores; stable keys for `@child`; gate resources on lifecycle state; don’t shadow `props`.
 
 ## Testing
 

package/dist/api.d.ts

@@ -1,8 +1,8 @@
-import type { Snapshot, SnapshotDiff } from "./types";
+import type { Snapshot, SnapshotDiff, IdType } from "./types";
 import type Store from "./store/Store";
 import type Model from "./model/Model";
+export declare function findModelById<T extends Model>(root: Model, ModelType: new (...args: any[]) => T, id: IdType): T | undefined;
 export declare function mount<T extends Store>(container: T): T;
-export declare function unmount<S extends Store>(container: S): void;
 export declare function toSnapshot<T extends Model>(model: T): Snapshot<T>;
 export declare function onSnapshot<T extends Model>(model: T, callback: (snapshot: Snapshot<T>, model: T) => void): () => void;
 export declare function onSnapshotDiff<T extends Model>(model: T, callback: (snapshotDiff: SnapshotDiff<T>, model: T) => void): () => void;

package/dist/decorators.d.ts

@@ -1,6 +1,6 @@
 import "@tsmetadata/polyfill";
 export declare const child: any;
-export declare const modelRef: any;
+export declare function modelRef<T extends Function>(childCtor: T): any;
 export declare const model: any;
 export declare const id: any;
 export declare const state: any;

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import "@tsmetadata/polyfill";
 import Store, { createStore, updateStore } from "./store/Store";
 import Model from "./model/Model";
-import { mount, unmount, onSnapshot, toSnapshot, applySnapshot, onSnapshotDiff } from "./api";
+import { mount, onSnapshot, toSnapshot, applySnapshot, onSnapshotDiff, findModelById } from "./api";
 import { createContext } from "./context";
 import { toObservableTree } from "./toObservableTree";
-export { createStore, Store, Model, mount, unmount, updateStore, onSnapshot, onSnapshotDiff, toSnapshot, applySnapshot, createContext, toObservableTree, };
+export { createStore, Store, Model, mount, updateStore, onSnapshot, onSnapshotDiff, toSnapshot, applySnapshot, findModelById, createContext, toObservableTree, };
 export { observable, computed, source, reportChanged, reportObserved, getSignal, isObservable, reaction, Signal, type ReadonlySignal, batch, untracked, effect, signal, Observable, } from "./observables";
 export * from "./decorators";
 export type { Configuration, Snapshot, SnapshotValue, IdType, SnapshotDiff, } from "./types";

package/dist/model/Model.d.ts

@@ -1,17 +1,13 @@
 import type { ModelConfiguration, Snapshot } from "../types";
-type ExtractModelDidInitArgs<T extends Model> = T extends {
-    modelDidInit(...args: infer Args): unknown;
-} ? Args extends [infer Snapshot, ...infer Rest] ? Rest : [] : [];
-export default class Model {
+export default class Model implements Disposable {
     static types?: ModelConfiguration<unknown>;
     static childTypes: object;
     static create<T extends Model = Model>(this: {
         new (...args: unknown[]): T;
-    }, snapshot?: Snapshot<T>, ...args: ExtractModelDidInitArgs<T>): T;
+    }, snapshot?: Snapshot<T>): T;
     constructor();
     get parent(): Model | null;
-    modelDidInit(snapshot?: Snapshot<this>, ...args: unknown[]): void;
-    modelDidAttach(): void;
-    modelWillDetach(): void;
+    reaction<T>(track: () => T, callback: (value: T, previousValue: T) => void): () => void;
+    effect(callback: () => void | (() => void)): () => void;
+    [Symbol.dispose](): void;
 }
-export {};

package/dist/model/ModelAdministration.d.ts

@@ -20,10 +20,16 @@ export declare class ModelAdministration extends PreactObjectAdministration<any>
     private computedSnapshot;
     private snapshotMap;
     private contextCache;
+    private ownedDisposers;
+    private disposed;
     parentName: PropertyKey | null;
     get parent(): ModelAdministration | null;
     set parent(value: ModelAdministration | null);
     setConfiguration(configurationGetter: () => ModelConfiguration<any>): void;
+    assertUsable(): void;
+    private own;
+    reaction<T>(track: () => T, callback: (value: T, previousValue: T) => void): () => void;
+    effect(callback: () => void | (() => void)): () => void;
     private get configuration();
     private getReferencedAtom;
     private setState;
@@ -35,12 +41,17 @@ export declare class ModelAdministration extends PreactObjectAdministration<any>
     private getModelRefs;
     private setModelRef;
     private setModelRefs;
+    private getRequiredModelRefType;
+    private assertModelRefType;
     private attach;
+    private getReactiveRoot;
     private detach;
+    dispose(internal?: boolean): void;
     getContextValue<T>(contextId: symbol, provideSymbol: symbol, defaultValue: T | undefined, hasDefault: boolean): T;
     private lookupContextValue;
     private toJSON;
     onSnapshotChange(onChange: SnapshotChange<any>): () => void;
     loadSnapshot(snapshot: Snapshot<any>): void;
     getSnapshot(): Snapshot<any>;
+    getSnapshotForRollback(): Snapshot<any>;
 }

package/dist/model/idMap.d.ts

@@ -1,8 +1,8 @@
 import type { IdType } from "../types";
-import type Model from "./Model";
-export declare function onSnapshotLoad<T>(fn: () => T): T;
-export declare function setIdentifier(model: Model, id: string | number): void;
+import Model from "./Model";
+export type ModelConstructor<T extends Model = Model> = new (...args: any[]) => T;
+export declare function setIdentifier(model: Model, id: IdType): void;
 export declare function getIdentifier(model: Model): IdType | undefined;
-export declare function getModelById(root: Model, id: IdType): Model | undefined;
+export declare function getModelById<T extends Model>(root: Model, Type: ModelConstructor<T>, id: IdType): T | undefined;
 export declare function onModelAttached(model: Model): void;
 export declare function onModelDetached(model: Model): void;

package/dist/observables/preact.d.ts

@@ -41,7 +41,7 @@ export declare function createSignal<T>(initialValue: T): SignalNode<T>;
 export declare function createAtom(): AtomNode;
 export { effect, batch, untracked, Signal };
 export type { ReadonlySignal };
-export declare function reaction<T>(fn: () => T, callback: (value: T) => void): () => void;
+export declare function reaction<T>(fn: () => T, callback: (value: T, previousValue: T) => void): () => void;
 export type Listener = {
     dispose: () => void;
     track: <T>(trackFn: () => T) => T;