r-state-tree 0.3.1 → 0.4.1

package/README.md

@@ -8,13 +8,18 @@ Reactive state management featuring store trees, computed child stores, and snap
 pnpm add r-state-tree
 ```
 
+### Requirements
+
+This library uses [TC39 Stage 3 Decorators](https://github.com/tc39/proposal-decorators) and requires TypeScript 5.0+ with `target: "es2022"` or higher.
+
+The library includes a decorator metadata polyfill for runtimes that don't yet natively support `Symbol.metadata`.
+
 ## Stores
 
 Stores describe reactive state containers composed into a tree.
 
 ```ts
-import Store, { createStore, mount } from "r-state-tree";
-import { child } from "r-state-tree/decorators";
+import { Store, createStore, mount, child } from "r-state-tree";
 
 class TodoStore extends Store {
 	props = { title: "" };
@@ -44,58 +49,330 @@ import { updateStore } from "r-state-tree";
 updateStore(app.todo, { title: "Ship release" });
 ```
 
+### Child stores
+
+Use `@child` for both single child stores and arrays.
+
+```ts
+import { child } from "r-state-tree";
+
+class ListStore extends Store {
+	items = ["Buy milk", "Walk dog"];
+
+	@child get todos() {
+		return this.items.map((title, i) =>
+			createStore(TodoStore, { title, key: i })
+		);
+	}
+}
+```
+
+### Lifecycle hooks
+
+Stores support lifecycle methods:
+
+```ts
+class TodoStore extends Store {
+	storeDidMount() {
+		console.log("Store mounted");
+	}
+
+	storeWillUnmount() {
+		console.log("Store will unmount");
+	}
+}
+```
+
+### Reactions
+
+Create side effects that run when reactive values change:
+
+```ts
+class TodoStore extends Store {
+	storeDidMount() {
+		this.reaction(
+			() => this.props.title,
+			(title) => console.log("Title changed:", title)
+		);
+	}
+}
+```
+
+### Context
+
+Share data across the store tree without prop drilling:
+
+```ts
+import { createContext } from "r-state-tree";
+
+const ThemeContext = createContext<"light" | "dark">("light");
+
+class AppStore extends Store {
+	theme = "dark";
+
+	[ThemeContext.provide]() {
+		return this.theme;
+	}
+
+	@child get todo() {
+		return createStore(TodoStore);
+	}
+}
+
+class TodoStore extends Store {
+	get theme() {
+		return ThemeContext.consume(this);
+	}
+}
+
+const app = mount(createStore(AppStore));
+app.todo.theme; // "dark"
+```
+
+Context is reactive and updates automatically when the provided value changes.
+
 ### Actions and batching
 
-`runInBatch` groups updates to avoid redundant reactions.
+`batch` groups updates to avoid redundant reactions.
 
 ```ts
-import { runInBatch } from "r-state-tree";
+import { batch } from "r-state-tree";
 
-runInBatch(() => {
+batch(() => {
 	app.todo.props.title = "Refactor";
 });
 ```
 
+## Observable classes
+
+For reactive class instances outside the Model/Store system, use `@observable` and `@computed` decorators:
+
+```ts
+import { Observable, observable, computed, effect } from "r-state-tree";
+
+class Counter extends Observable {
+	@observable count = 0;
+	@observable step = 1;
+
+	@computed get doubled() {
+		return this.count * 2;
+	}
+
+	increment() {
+		this.count += this.step;
+	}
+}
+
+const counter = new Counter();
+
+effect(() => {
+	console.log("Count:", counter.count, "Doubled:", counter.doubled);
+});
+
+counter.increment(); // Triggers the effect
+```
+
+**Important:** Class instances require explicit `@observable` and `@computed` decorators. Properties without decorators are **not** reactive.
+
+### Plain objects (implicit reactivity)
+
+Plain objects wrapped with `observable()` use implicit reactivity for backward compatibility:
+
+```ts
+import { observable, effect } from "r-state-tree";
+
+const state = observable({ count: 0 });
+
+effect(() => {
+	console.log(state.count); // All properties are reactive
+});
+
+state.count++; // Triggers the effect
+```
+
 ## Models and snapshots
 
 Models capture persistent state with snapshot utilities.
 
 ```ts
-import Model from "r-state-tree/model/Model";
 import {
+	Model,
+	state,
+	identifier,
 	applySnapshot,
 	onSnapshot,
-	onSnapshotDiff,
 	toSnapshot,
 } from "r-state-tree";
 
 class TodoModel extends Model {
-	static types = {
-		title: stateType,
-		assignee: modelRefType,
-	};
-
-	title = "";
+	@identifier id = 0;
+	@state title = "";
+	@state completed = false;
 }
 
-const todo = new TodoModel();
+const todo = TodoModel.create({ id: 1, title: "Learn signals" });
 
 const stop = onSnapshot(todo, (snapshot) => {
-	console.log(snapshot.title);
+	console.log(snapshot); // { id: 1, title: "Learn signals", completed: false }
 });
 
-applySnapshot(todo, { title: "Learn signals" });
+todo.title = "Learn r-state-tree";
 stop();
 ```
 
+### Model lifecycle hooks
+
+Models support lifecycle methods:
+
+```ts
+class TodoModel extends Model {
+	@child tags: TagModel[] = [];
+
+	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);
+	}
+
+	modelDidAttach() {
+		// Called when this model is attached as a child to another model
+		console.log("Model attached to parent");
+	}
+
+	modelWillDetach() {
+		// Called when this model is detached from its parent
+		console.log("Model will be detached");
+	}
+}
+```
+
+### Model decorators
+
+Use decorators to configure model properties:
+
+```ts
+import { Model, state, identifier, child, modelRef } from "r-state-tree";
+
+class User extends Model {
+	@identifier id = 0;
+	@state name = "";
+}
+
+class TodoModel extends Model {
+	@identifier id = 0;
+	@state title = "";
+	@modelRef assignee?: User; // Reference to another model by ID
+	@child metadata = MetadataModel.create(); // Nested child model
+	@child tags: TagModel[] = []; // Array of child models
+}
+```
+
+The `@child` and `@modelRef` decorators support both single values and arrays. You can also specify the child type using `@child(ChildType)`:
+
+```ts
+class TodoModel extends Model {
+	@child(TagModel) tags: TagModel[] = []; // Type-safe array of child models
+	@child(TagModel) primaryTag: TagModel | null = null; // Can switch between single and array at runtime
+}
+```
+
+### Model references
+
+Reference models by ID using `@modelRef`:
+
+```ts
+class ProjectModel extends Model {
+	@identifier id = 0;
+	@child users: User[] = [];
+	@modelRef owner?: User; // Single reference
+	@modelRef assignees: User[] = []; // Array of references
+
+	assignOwner(userId: number) {
+		// Find user by ID and set as owner
+		const user = this.users.find((u) => u.id === userId);
+		this.owner = user;
+	}
+}
+
+const project = ProjectModel.create({
+	id: 1,
+	users: [
+		{ id: 1, name: "Alice" },
+		{ id: 2, name: "Bob" },
+	],
+	owner: { id: 1 }, // Reference by ID in snapshot
+});
+
+project.owner?.name; // "Alice"
+```
+
+Both `@child` and `@modelRef` support runtime type switching between single values and arrays:
+
+```ts
+class ItemModel extends Model {
+	@identifier id = 0;
+	@state value = 0;
+}
+
+class ContainerModel extends Model {
+	@child(ItemModel) items: ItemModel | ItemModel[]; // Can be single or array
+
+	setSingle() {
+		this.items = ItemModel.create({ id: 1, value: 10 });
+	}
+
+	setArray() {
+		this.items = [
+			ItemModel.create({ id: 2, value: 20 }),
+			ItemModel.create({ id: 3, value: 30 }),
+		];
+	}
+}
+```
+
 ### Snapshot diffs
 
-Use `onSnapshotDiff` to receive undo/redo payloads.
+Use `onSnapshotDiff` to receive undo/redo payloads:
 
 ```ts
-const off = onSnapshotDiff(todo, ({ undo, redo }) => {
-	// undo and redo contain patch-like snapshots
+const history: SnapshotDiff[] = [];
+
+const off = onSnapshotDiff(todo, (diff) => {
+	history.push(diff);
 });
+
+todo.title = "New title";
+todo.completed = true;
+
+// Undo
+applySnapshot(todo, history[history.length - 1].undo);
+
+// Redo
+applySnapshot(todo, history[history.length - 1].redo);
+```
+
+### Context with Models
+
+Models also support context:
+
+```ts
+const AuthContext = createContext<User | null>(null);
+
+class AppModel extends Model {
+	@child currentUser = User.create({ id: 1, name: "Alice" });
+
+	[AuthContext.provide]() {
+		return this.currentUser;
+	}
+
+	@child project = ProjectModel.create();
+}
+
+class ProjectModel extends Model {
+	get currentUser() {
+		return AuthContext.consume(this);
+	}
+}
 ```
 
 ## Testing

package/dist/context.d.ts

@@ -0,0 +1,13 @@
+import type Model from "./model/Model";
+import type Store from "./store/Store";
+declare const CONTEXT_SYMBOL: unique symbol;
+declare const HAS_DEFAULT: unique symbol;
+export interface Context<T> {
+    readonly [CONTEXT_SYMBOL]: symbol;
+    readonly [HAS_DEFAULT]: boolean;
+    readonly defaultValue: T | undefined;
+    readonly provide: symbol;
+    consume(instance: Model | Store): T;
+}
+export declare function createContext<T>(defaultValue?: T): Context<T>;
+export {};

package/dist/decorators.d.ts

@@ -1,7 +1,6 @@
+import "@tsmetadata/polyfill";
 export declare const child: any;
-export declare const children: any;
-export declare const model: any;
 export declare const modelRef: any;
-export declare const modelRefs: any;
+export declare const model: any;
 export declare const identifier: any;
 export declare const state: any;

package/dist/index.d.ts

@@ -1,7 +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";
-export { createStore, Store, Model, mount, unmount, updateStore, onSnapshot, onSnapshotDiff, toSnapshot, applySnapshot, };
-export { observable, source, reportChanged, reportObserved, getSignal, isObservable, createSignal, createAtom, createComputed, createReaction, createListener, runInBatch, runInUntracked, createEffect, Observable, } from "./observables";
+import { createContext } from "./context";
+export { createStore, Store, Model, mount, unmount, updateStore, onSnapshot, onSnapshotDiff, toSnapshot, applySnapshot, createContext, };
+export { observable, computed, source, reportChanged, reportObserved, getSignal, isObservable, reaction, Signal, ReadonlySignal, batch, untracked, effect, Observable, signal, } from "./observables";
 export * from "./decorators";
 export type { Configuration, Snapshot, IdType, SnapshotDiff } from "./types";
+export type { Context } from "./context";

package/dist/model/Model.d.ts

@@ -1,13 +1,17 @@
-import { Snapshot } from "../types";
+import { 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 {
-    static types: object;
+    static get types(): ModelConfiguration<unknown>;
     static childTypes: object;
     static create<T extends Model = Model>(this: {
         new (...args: unknown[]): T;
-    }, snapshot?: Snapshot<T>, ...args: unknown[]): T;
+    }, snapshot?: Snapshot<T>, ...args: ExtractModelDidInitArgs<T>): T;
     constructor();
     get parent(): Model | null;
     modelDidInit(snapshot?: Snapshot<this>, ...args: unknown[]): void;
     modelDidAttach(): void;
     modelWillDetach(): void;
 }
+export {};

package/dist/model/ModelAdministration.d.ts

@@ -5,8 +5,9 @@ export declare function getConfigurationFromSnapshot(snapshot: object): ModelCon
 export declare function getModelAdm<T extends Model>(model: T): ModelAdministration;
 export declare class ModelAdministration extends PreactObjectAdministration<any> {
     static proxyTraps: ProxyHandler<object>;
-    configuration: ModelConfiguration<any>;
-    parent: ModelAdministration | null;
+    private configurationGetter?;
+    private _parent;
+    private parentAtom;
     referencedAtoms: Map<PropertyKey, AtomNode>;
     referencedModels: Map<PropertyKey, ComputedNode<Model[]>>;
     activeModels: Set<PropertyKey>;
@@ -15,21 +16,25 @@ export declare class ModelAdministration extends PreactObjectAdministration<any>
     private writeInProgress;
     private computedSnapshot;
     private snapshotMap;
+    private contextCache;
     parentName: PropertyKey | null;
-    setConfiguration(configuration: ModelConfiguration<any>): void;
+    get parent(): ModelAdministration | null;
+    set parent(value: ModelAdministration | null);
+    setConfiguration(configurationGetter: () => ModelConfiguration<any>): void;
+    private get configuration();
     private getReferencedAtom;
     private setState;
     private setId;
     private setModel;
     private setModels;
-    private getModel;
-    private getModels;
     private getModelRef;
     private getModelRefs;
     private setModelRef;
     private setModelRefs;
     private attach;
     private detach;
+    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;

package/dist/observables/index.d.ts

@@ -3,4 +3,4 @@ export { ArrayAdministration } from "./array";
 export { CollectionAdministration } from "./collection";
 export { DateAdministration } from "./date";
 export { ObjectAdministration } from "./object";
-export { AtomNode, createReaction, SignalNode, createAtom, runInBatch, createComputed, createSignal, runInUntracked, ListenerNode, createListener, ComputedNode, PreactObjectAdministration, getSignal, source, reportChanged, reportObserved, observable, createEffect, Observable, } from "./preact";
+export { AtomNode, reaction, SignalNode, createAtom, batch, createComputed, createSignal, untracked, ListenerNode, createListener, ComputedNode, PreactObjectAdministration, getSignal, source, reportChanged, reportObserved, observable, computed, Signal, ReadonlySignal, effect, signal, Observable, } from "./preact";

package/dist/observables/internal/utils.d.ts

@@ -3,7 +3,7 @@ export declare function defaultEquals<T>(a: T, b: T): boolean;
 export declare function isNonPrimitive(val: unknown): val is object;
 export declare function isPropertyKey(val: unknown): val is string | number | symbol;
 export type PropertyType = "action" | "computed" | "observable";
-export declare function getPropertyType(key: PropertyKey, obj: object): PropertyType;
+export declare function getPropertyType(key: PropertyKey, obj: object): PropertyType | null;
 export declare function getPropertyDescriptor(obj: object, key: PropertyKey): PropertyDescriptor | undefined;
 export declare function isPlainObject(value: unknown): value is object;
 export declare function resolveNode(node: SignalNode<unknown> | AtomNode | ComputedNode<unknown>): unknown;

package/dist/observables/object.d.ts

@@ -7,7 +7,7 @@ export declare class ObjectAdministration<T extends object> extends Administrati
     hasMap: AtomMap<PropertyKey>;
     valuesMap: SignalMap<PropertyKey>;
     computedMap: Map<PropertyKey, ComputedNode<T[keyof T]>>;
-    types: Map<PropertyKey, PropertyType>;
+    types: Map<PropertyKey, PropertyType | null>;
     static proxyTraps: ProxyHandler<object>;
     constructor(source?: T);
     private get;

package/dist/observables/preact.d.ts

@@ -1,4 +1,4 @@
-import { Signal, ReadonlySignal } from "@preact/signals-core";
+import { signal, Signal, ReadonlySignal, batch, effect, untracked } from "@preact/signals-core";
 import { ObjectAdministration } from "./object";
 export { isObservable } from "./index";
 export declare class PreactObjectAdministration<T extends object> extends ObjectAdministration<T> {
@@ -39,9 +39,8 @@ export declare function createObservedAtom(): {
 };
 export declare function createSignal<T>(initialValue: T): SignalNode<T>;
 export declare function createAtom(): AtomNode;
-export declare function createEffect(fn: () => void): () => void;
-export declare function runInUntracked<T>(fn: () => T): T;
-export declare function createReaction<T>(fn: () => T, callback: (value: T) => void): () => void;
+export { effect, signal, batch, untracked, Signal, ReadonlySignal };
+export declare function reaction<T>(fn: () => T, callback: (value: T) => void): () => void;
 export type Listener = {
     dispose: () => void;
     track: <T>(trackFn: () => T) => T;
@@ -56,8 +55,10 @@ export type PreactObservable<T> = T extends Function ? T : T extends Map<infer K
     readonly [key in keyof T as T[key] extends object ? never : `$${string & key}`]?: Signal<T[key]>;
 };
 export declare function observable<T>(obj: T): PreactObservable<T>;
+export declare function observable(value: undefined, context: ClassFieldDecoratorContext): void;
+export declare function computed<T>(value: () => T, context: ClassGetterDecoratorContext): void;
+export declare function computed<T>(fn: () => T): ReadonlySignal<T>;
 export declare function source<T>(obj: PreactObservable<T> | T): T;
-export declare function runInBatch<T>(fn: () => T): T;
 export declare class Observable {
     constructor();
 }