r-state-tree 0.4.6 → 0.5.0

package/README.md

@@ -42,6 +42,19 @@ TypeScript 5+ supports TC39 Stage 3 decorators.
 - `useDefineForClassFields: true` is recommended with modern toolchains targeting ES2022.
 - The library includes a `Symbol.metadata` polyfill via `@tsmetadata/polyfill`.
 
+### Vite / esbuild config (SSR)
+
+When using Vite or esbuild for SSR, ensure the target is set to `es2022` to support Stage 3 decorators:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+	esbuild: {
+		target: "es2022",
+	},
+});
+```
+
 ## 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()`.
@@ -389,6 +402,55 @@ effect(() => {
 state.count++; // Triggers the effect
 ```
 
+### Shallow and signal observables
+
+Control the depth of reactivity with `@observable.shallow` and `@observable.signal`:
+
+| Decorator | Container Observable? | Values Observable? | Triggers on... |
+|-----------|----------------------|-------------------|----------------|
+| `@observable` | ✅ Yes | ✅ Yes (deep) | mutations + assignment |
+| `@observable.shallow` | ✅ Yes | ❌ No | mutations + assignment |
+| `@observable.signal` | ❌ No | ❌ No | assignment only |
+
+```ts
+import { Observable, observable, effect, isObservable } from "r-state-tree";
+
+class DataStore extends Observable {
+	// Deep observable - items pushed are also observable
+	@observable deepItems: { value: number }[] = [];
+
+	// Shallow - container is observable, but pushed items are NOT
+	@observable.shallow shallowItems: { value: number }[] = [];
+
+	// Signal - only assignment triggers, mutations do not
+	@observable.signal signalItems: number[] = [];
+}
+
+const store = new DataStore();
+
+// Shallow: items pushed are NOT observable (safe for structuredClone)
+store.shallowItems.push({ value: 1 });
+console.log(isObservable(store.shallowItems[0])); // false
+
+// Signal: mutations don't trigger effects
+effect(() => store.signalItems.length);
+store.signalItems.push(1); // Does NOT trigger effect
+store.signalItems = [1, 2]; // DOES trigger effect
+```
+
+**Use cases:**
+- `@observable.shallow`: Store external data that may need `structuredClone()`, or when you want change detection on the container but not deep reactivity
+- `@observable.signal`: Maximum performance when you're replacing values rather than mutating them
+
+Models support the same modifiers with `@state`:
+
+```ts
+class M extends Model {
+	@state.shallow items: { value: number }[] = []; // Container tracked, items not
+	@state.signal data: SomeType = null; // Only assignment tracked
+}
+```
+
 ## Observables (low‑level)
 
 Create reactive structures outside Stores/Models. Supported: Objects, Arrays, Map, Set, WeakMap, WeakSet.
@@ -824,6 +886,31 @@ const off = onSnapshot(m, (snap) =>
 - Forgetting stable keys for `@child` arrays causes identity churn.
 - Assuming deep reactivity on undecorated fields of plain classes; use `@observable` for `Observable` classes, or use Stores/Models.
 - 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.
+
+### 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.
+
+## LLM implementation checklist
+
+- Do not thread context data via props. Provide contexts at the parent and consume them in children. Passing `getX` callbacks for resource/page/video/skill is a red flag—consume contexts instead.
+- Avoid aggregating contexts into a single `ctx` object; consume where needed or expose small, focused getters.
+- Only create stores in three places: root, `@child` getters, or immediately before mounting. Avoid standalone factory helpers; inline `createStore` in `@child` getters.
+- Do not wrap `createStore` calls with `as Record<string, unknown>`; fix typing instead.
+- Domain/persistent state belongs in Models; UI/app orchestration in Stores. Keep UI terms out of domain models—name domain concepts (e.g., `ChatThreadsModel`).
+- If state is persistent/rehydratable, model it and derive stores from the model; keep purely view/ephemeral state in stores.
+- Use r-state-tree snapshots (`toSnapshot`/`applySnapshot`) instead of hand-rolled `serialize`/`rehydrate` unless a different shape is required.
+- Keep `onPersist` only when syncing store state into a backing model; otherwise prefer snapshot listeners.
+- Pure, stateless helpers belong in utility modules, not as store methods. If a method does not touch `this`, extract it; keep coupled helpers in the store.
+- Provide stable, rarely changing resource/view/video/page data via context (resourceId, resourceType, totalPages, current page/display mode, page offsets, document title, skill/detail, video info). Children should consume context directly.
+- Use `@child` getters to create child stores with stable keys; avoid constructor creation. Pass only what the child needs; avoid prop drilling context.
+- Eliminate blanket casts; fix types and let inference work. Avoid `any`.
+- 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`.
+- Use `@model` for injected models; `@child` for child stores; stable keys for arrays.
 
 ## Typing recipes
 

package/dist/api.d.ts

@@ -1,6 +1,6 @@
-import { Snapshot, SnapshotDiff } from "./types";
-import Store from "./store/Store";
-import Model from "./model/Model";
+import type { Snapshot, SnapshotDiff } from "./types";
+import type Store from "./store/Store";
+import type Model from "./model/Model";
 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>;

package/dist/computedProxy.d.ts

@@ -1,2 +1,2 @@
-import { ComputedNode } from "./observables";
+import type { ComputedNode } from "./observables";
 export default function <T extends Record<PropertyKey, any>>(computed: ComputedNode<T>): T;

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import Model from "./model/Model";
 import { mount, unmount, onSnapshot, toSnapshot, applySnapshot, onSnapshotDiff } from "./api";
 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 { observable, computed, source, reportChanged, reportObserved, getSignal, isObservable, reaction, Signal, type 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,4 +1,4 @@
-import { ModelConfiguration, Snapshot } from "../types";
+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 : [] : [];

package/dist/model/ModelAdministration.d.ts

@@ -1,6 +1,7 @@
-import { PreactObjectAdministration, ComputedNode, AtomNode } from "../observables";
+import { PreactObjectAdministration } from "../observables";
+import type { ComputedNode, AtomNode } from "../observables";
 import Model from "../model/Model";
-import { ModelConfiguration, Snapshot, SnapshotChange } from "../types";
+import type { ModelConfiguration, Snapshot, SnapshotChange } from "../types";
 export declare function getConfigurationFromSnapshot(snapshot: object): ModelConfiguration<unknown> | undefined;
 export declare function getModelAdm<T extends Model>(model: T): ModelAdministration;
 export declare class ModelAdministration extends PreactObjectAdministration<any> {

package/dist/model/idMap.d.ts

@@ -1,5 +1,5 @@
-import { IdType } from "../types";
-import Model from "./Model";
+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;
 export declare function getIdentifier(model: Model): IdType | undefined;

package/dist/observables/array.d.ts

@@ -1,4 +1,4 @@
-import { AtomNode } from "./preact";
+import type { AtomNode } from "./preact";
 import { Administration } from "./internal/Administration";
 import { SignalMap } from "./internal/NodeMap";
 export declare class ArrayAdministration<T> extends Administration<T[]> {

package/dist/observables/collection.d.ts

@@ -1,4 +1,4 @@
-import { AtomNode } from "./preact";
+import type { AtomNode } from "./preact";
 import { Administration } from "./internal/Administration";
 import { AtomMap, SignalMap } from "./internal/NodeMap";
 type Collection<K, V> = Set<K> | Map<K, V>;

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, reaction, SignalNode, createAtom, batch, createComputed, createSignal, untracked, ListenerNode, createListener, ComputedNode, PreactObjectAdministration, getSignal, source, reportChanged, reportObserved, observable, computed, Signal, ReadonlySignal, effect, signal, Observable, } from "./preact";
+export { type AtomNode, reaction, type SignalNode, createAtom, batch, createComputed, createSignal, untracked, type ListenerNode, createListener, type ComputedNode, PreactObjectAdministration, getSignal, source, reportChanged, reportObserved, observable, computed, Signal, type ReadonlySignal, effect, signal, Observable, } from "./preact";

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

@@ -1,5 +1,5 @@
-import { ObservedAtomNode } from "../preact";
-import { SignalMap } from "./NodeMap";
+import type { ObservedAtomNode } from "../preact";
+import type { SignalMap } from "./NodeMap";
 export declare class Administration<T extends object = any> {
     static readonly proxyTraps: ProxyHandler<object>;
     readonly proxy: T;

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

@@ -1,4 +1,4 @@
-import { AtomNode, ObservedAtomNode, SignalNode } from "../preact";
+import type { AtomNode, ObservedAtomNode, SignalNode } from "../preact";
 declare class NodeMap<K = unknown, GraphNode extends AtomNode | SignalNode<unknown> = AtomNode | SignalNode<unknown>> {
     private map;
     private weakMap;

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

@@ -2,7 +2,7 @@ import { CollectionAdministration } from "../collection";
 import { PreactObjectAdministration } from "../preact";
 import { ArrayAdministration } from "../array";
 import { DateAdministration } from "../date";
-import { Administration } from "./Administration";
+import type { Administration } from "./Administration";
 export declare function getAdministration<T extends object>(obj: T): T extends Set<infer S> ? CollectionAdministration<S> : T extends Map<infer K, infer V> ? CollectionAdministration<K, V> : T extends Array<infer R> ? ArrayAdministration<R> : T extends Date ? DateAdministration : PreactObjectAdministration<any>;
 export declare function getSource<T>(obj: T): T;
 export declare function getAction<T extends Function>(fn: T): T;
@@ -10,5 +10,7 @@ export declare function getObservableClassInstance<T extends object>(value: T):
 export declare function getObservableIfExists<T>(value: T): T | undefined;
 export declare function createObservableWithCustomAdministration<T>(value: T, Adm: new (obj: any) => Administration): T;
 export declare function getObservable<T>(value: T): T;
+export declare function isShallowObservable(obj: unknown): boolean;
+export declare function getShallowObservable<T>(value: T): T;
 export declare function isObservable(obj: unknown): boolean;
 export declare function getInternalNode(obj: object, key?: PropertyKey): any;

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

@@ -1,8 +1,8 @@
-import { AtomNode, ComputedNode, SignalNode } from "../preact";
+import type { AtomNode, ComputedNode, SignalNode } from "../preact";
 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 type PropertyType = "action" | "computed" | "observable" | "observableShallow" | "observableSignal";
 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;

package/dist/observables/object.d.ts

@@ -1,5 +1,5 @@
-import { AtomNode, ComputedNode } from "./preact";
-import { PropertyType } from "./internal/utils";
+import type { AtomNode, ComputedNode } from "./preact";
+import type { PropertyType } from "./internal/utils";
 import { Administration } from "./internal/Administration";
 import { AtomMap, SignalMap } from "./internal/NodeMap";
 export declare class ObjectAdministration<T extends object> extends Administration<T> {

package/dist/observables/preact.d.ts

@@ -1,4 +1,5 @@
-import { signal, Signal, ReadonlySignal, batch, effect, untracked } from "@preact/signals-core";
+import { signal, Signal, batch, effect, untracked } from "@preact/signals-core";
+import type { ReadonlySignal } from "@preact/signals-core";
 import { ObjectAdministration } from "./object";
 export { isObservable } from "./index";
 export declare class PreactObjectAdministration<T extends object> extends ObjectAdministration<T> {
@@ -39,7 +40,8 @@ export declare function createObservedAtom(): {
 };
 export declare function createSignal<T>(initialValue: T): SignalNode<T>;
 export declare function createAtom(): AtomNode;
-export { effect, signal, batch, untracked, Signal, ReadonlySignal };
+export { effect, signal, batch, untracked, Signal };
+export type { ReadonlySignal };
 export declare function reaction<T>(fn: () => T, callback: (value: T) => void): () => void;
 export type Listener = {
     dispose: () => void;
@@ -54,8 +56,14 @@ 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;
+declare function observableImpl<T>(obj: T): PreactObservable<T>;
+declare function observableImpl(value: undefined, context: ClassFieldDecoratorContext): void;
+declare function shallowDecorator(value: any, context: ClassFieldDecoratorContext): any;
+declare function signalDecorator(value: any, context: ClassFieldDecoratorContext): any;
+export declare const observable: typeof observableImpl & {
+    shallow: typeof shallowDecorator;
+    signal: typeof signalDecorator;
+};
 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;