r-state-tree 0.1.0-rc9 → 0.3.1

package/README.md

@@ -0,0 +1,119 @@
+# r-state-tree
+
+Reactive state management featuring store trees, computed child stores, and snapshot utilities backed by `@preact/signals-core`.
+
+## Installation
+
+```bash
+pnpm add r-state-tree
+```
+
+## 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";
+
+class TodoStore extends Store {
+	props = { title: "" };
+
+	get title() {
+		return this.props.title;
+	}
+}
+
+class AppStore extends Store {
+	@child get todo() {
+		return createStore(TodoStore, { title: "Write docs" });
+	}
+}
+
+const app = mount(createStore(AppStore));
+app.todo.title; // "Write docs"
+```
+
+### Updating props
+
+Stores receive reactive `props` objects. Use `updateStore` to change them.
+
+```ts
+import { updateStore } from "r-state-tree";
+
+updateStore(app.todo, { title: "Ship release" });
+```
+
+### Actions and batching
+
+`runInBatch` groups updates to avoid redundant reactions.
+
+```ts
+import { runInBatch } from "r-state-tree";
+
+runInBatch(() => {
+	app.todo.props.title = "Refactor";
+});
+```
+
+## Models and snapshots
+
+Models capture persistent state with snapshot utilities.
+
+```ts
+import Model from "r-state-tree/model/Model";
+import {
+	applySnapshot,
+	onSnapshot,
+	onSnapshotDiff,
+	toSnapshot,
+} from "r-state-tree";
+
+class TodoModel extends Model {
+	static types = {
+		title: stateType,
+		assignee: modelRefType,
+	};
+
+	title = "";
+}
+
+const todo = new TodoModel();
+
+const stop = onSnapshot(todo, (snapshot) => {
+	console.log(snapshot.title);
+});
+
+applySnapshot(todo, { title: "Learn signals" });
+stop();
+```
+
+### Snapshot diffs
+
+Use `onSnapshotDiff` to receive undo/redo payloads.
+
+```ts
+const off = onSnapshotDiff(todo, ({ undo, redo }) => {
+	// undo and redo contain patch-like snapshots
+});
+```
+
+## Testing
+
+The repository ships with Vitest suites covering stores, models, containers, and observable primitives.
+
+```bash
+pnpm test
+```
+
+## Build & publishing
+
+```bash
+pnpm build
+```
+
+The build emits CommonJS, ESM bundles, and type declarations under `dist/`.
+
+## License
+
+MIT

package/{lib → dist}/api.d.ts

@@ -1,8 +1,9 @@
-import { Snapshot } from "./types";
-import Store from "./store/Store";
-import 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>;
-export declare function onSnapshot<T extends Model>(model: T, callback: (snapshot: Snapshot<T>, model: T) => void): () => void;
-export declare function applySnapshot<T extends Model>(model: T, snapshot: Snapshot<T>): T;
+import { Snapshot, SnapshotDiff } from "./types";
+import Store from "./store/Store";
+import 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>;
+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;
+export declare function applySnapshot<T extends Model>(model: T, snapshot: Snapshot<T>): T;

package/dist/computedProxy.d.ts

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

package/{lib → dist}/decorators.d.ts

@@ -1,10 +1,7 @@
-export declare const action: any;
-export declare const computed: any;
-export declare const observable: any;
-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 identifier: any;
-export declare const state: any;
+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 identifier: any;
+export declare const state: any;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+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";
+export * from "./decorators";
+export type { Configuration, Snapshot, IdType, SnapshotDiff } from "./types";

package/dist/model/ChildModelsAdministration.d.ts

@@ -0,0 +1,35 @@
+import { ArrayAdministration } from "../observables";
+export declare function notifyArrayUpdate<T>(arr: T[], index: number, oldValue: T, newValue: T): void;
+export declare function notifySpliceArray<T>(arr: T[], index: number, added: T[], removed: T[]): void;
+export declare function observe<T>(obj: object, method: MutationListener<T>): () => void;
+export type UpdateArrayEvent<T> = {
+    object: T[];
+    type: "updateArray";
+    index: number;
+    oldValue: T;
+    newValue: T;
+};
+export type SpliceArrayEvent<T> = {
+    object: T[];
+    type: "spliceArray";
+    index: number;
+    added: T[];
+    removed: T[];
+};
+export type MutationEvent<T> = UpdateArrayEvent<T> | SpliceArrayEvent<T>;
+export type MutationListener<T> = (ev: MutationEvent<T>) => void;
+export type HasListener<T> = {
+    listener: ObservableListener<T>;
+};
+declare class ObservableListener<T> {
+    private listeners;
+    private notifying;
+    subscribe(l: MutationListener<T>): () => void;
+    get size(): number;
+    notify(ev: MutationEvent<T>): void;
+}
+export declare class ChildModelsAdministration<T> extends ArrayAdministration<T> {
+    set(index: number, newValue: T): void;
+    spliceWithArray(index: number, deleteCount?: number | undefined, newItems?: T[] | undefined): T[];
+}
+export {};

package/{lib → dist}/model/Model.d.ts

@@ -1,14 +1,13 @@
-import { Snapshot } from "../types";
-export declare function isModelInitialized(model: Model): boolean;
-export default class Model {
-    static types: object;
-    static childTypes: object;
-    static create<T extends Model = Model>(this: {
-        new (...args: unknown[]): T;
-    }, snapshot?: Snapshot<T>, ...args: unknown[]): T;
-    constructor();
-    get parent(): Model | null;
-    modelDidInit(snapshot?: Snapshot<this>, ...args: unknown[]): void;
-    modelDidAttach(): void;
-    modelWillDetach(): void;
-}
+import { Snapshot } from "../types";
+export default class Model {
+    static types: object;
+    static childTypes: object;
+    static create<T extends Model = Model>(this: {
+        new (...args: unknown[]): T;
+    }, snapshot?: Snapshot<T>, ...args: unknown[]): T;
+    constructor();
+    get parent(): Model | null;
+    modelDidInit(snapshot?: Snapshot<this>, ...args: unknown[]): void;
+    modelDidAttach(): void;
+    modelWillDetach(): void;
+}

package/dist/model/ModelAdministration.d.ts

@@ -0,0 +1,37 @@
+import { PreactObjectAdministration, ComputedNode, AtomNode } from "../observables";
+import Model from "../model/Model";
+import { 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> {
+    static proxyTraps: ProxyHandler<object>;
+    configuration: ModelConfiguration<any>;
+    parent: ModelAdministration | null;
+    referencedAtoms: Map<PropertyKey, AtomNode>;
+    referencedModels: Map<PropertyKey, ComputedNode<Model[]>>;
+    activeModels: Set<PropertyKey>;
+    root: ModelAdministration;
+    private modelsTraceUnsub;
+    private writeInProgress;
+    private computedSnapshot;
+    private snapshotMap;
+    parentName: PropertyKey | null;
+    setConfiguration(configuration: ModelConfiguration<any>): void;
+    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;
+    private toJSON;
+    onSnapshotChange(onChange: SnapshotChange<any>): () => void;
+    loadSnapshot(snapshot: Snapshot<any>): void;
+    getSnapshot(): Snapshot<any>;
+}

package/{lib → dist}/model/idMap.d.ts

@@ -1,7 +1,8 @@
-import { IdType } from "../types";
-import Model from "./Model";
-export declare function setIdentifier(model: Model, id: string | number, name: string): void;
-export declare function getIdentifier(model: Model): IdType | undefined;
-export declare function getModelById(root: Model, id: IdType): Model | undefined;
-export declare function onModelAttached(model: Model): void;
-export declare function onModelDetached(model: Model): void;
+import { IdType } from "../types";
+import 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;
+export declare function getModelById(root: Model, id: IdType): Model | undefined;
+export declare function onModelAttached(model: Model): void;
+export declare function onModelDetached(model: Model): void;

package/dist/observables/array.d.ts

@@ -0,0 +1,21 @@
+import { AtomNode } from "./preact";
+import { Administration } from "./internal/Administration";
+import { SignalMap } from "./internal/NodeMap";
+export declare class ArrayAdministration<T> extends Administration<T[]> {
+    valuesMap: SignalMap<number>;
+    keysAtom: AtomNode;
+    static proxyTraps: ProxyHandler<Array<unknown>>;
+    static methods: Partial<{
+        [K in keyof typeof Array.prototype as (typeof Array.prototype)[K] extends Function ? K : never]: (typeof Array.prototype)[K];
+    }>;
+    constructor(source?: T[]);
+    protected reportObserveDeep(): void;
+    getNode(key?: number): unknown;
+    get(index: number): T | undefined;
+    set(index: number, newValue: T): void;
+    getArrayLength(): number;
+    setArrayLength(newLength: number): void;
+    spliceWithArray(index: number, deleteCount?: number, newItems?: T[]): T[];
+    spliceItemsIntoValues(index: number, deleteCount: number, newItems: T[]): T[];
+    onArrayChanged(lengthChanged?: boolean, index?: number, count?: number): void;
+}

package/dist/observables/collection.d.ts

@@ -0,0 +1,43 @@
+import { AtomNode } from "./preact";
+import { Administration } from "./internal/Administration";
+import { AtomMap, SignalMap } from "./internal/NodeMap";
+type Collection<K, V> = Set<K> | Map<K, V>;
+export declare class CollectionAdministration<K, V = K> extends Administration<Collection<K, V>> {
+    isMap: boolean;
+    hasMap: AtomMap<K>;
+    valuesMap: SignalMap<K>;
+    keysAtom: AtomNode;
+    static proxyTraps: ProxyHandler<Set<unknown> | Map<unknown, unknown>>;
+    static methods: {
+        clear: (this: any) => unknown;
+        forEach: (this: any) => unknown;
+        has: (this: any) => unknown;
+        add: (this: any) => unknown;
+        set: (this: any) => unknown;
+        get: (this: any) => unknown;
+        delete: (this: any) => unknown;
+        entries: (this: any) => unknown;
+        keys: (this: any) => unknown;
+        values: (this: any) => unknown;
+        [Symbol.iterator]: (this: any) => unknown;
+    };
+    constructor(source: Collection<K, V>);
+    private hasEntry;
+    private onCollectionChange;
+    protected reportObserveDeep(): void;
+    getNode(key?: K): unknown;
+    clear(): void;
+    forEach(callbackFn: (value: V, key: K, collection: Collection<K, V>) => void, thisArg?: unknown): void;
+    get size(): number;
+    add(value: K): this;
+    delete(value: K): boolean;
+    has(value: K): boolean;
+    entries(): IterableIterator<[K, V]>;
+    keys(): IterableIterator<K>;
+    get(key: K): V | undefined;
+    set(key: K, value: V): this;
+    values(): IterableIterator<V>;
+    [Symbol.iterator](): IterableIterator<[K, V] | V>;
+    [Symbol.toStringTag]: string;
+}
+export {};

package/dist/observables/date.d.ts

@@ -0,0 +1,4 @@
+import { Administration } from "./internal/Administration";
+export declare class DateAdministration extends Administration<Date> {
+    static proxyTraps: ProxyHandler<Date>;
+}

package/dist/observables/index.d.ts

@@ -0,0 +1,6 @@
+export { getAdministration, getSource, isObservable, getObservable, getObservableClassInstance, getInternalNode, createObservableWithCustomAdministration, } from "./internal/lookup";
+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";

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

@@ -0,0 +1,17 @@
+import { ObservedAtomNode } from "../preact";
+import { SignalMap } from "./NodeMap";
+export declare class Administration<T extends object = any> {
+    static readonly proxyTraps: ProxyHandler<object>;
+    readonly proxy: T;
+    readonly source: T;
+    readonly atom: ObservedAtomNode;
+    protected valuesMap?: SignalMap;
+    protected isObserved: boolean;
+    private forceObservedAtoms?;
+    constructor(source: T);
+    protected flushChange(): void;
+    getNode(): unknown;
+    reportChanged(): void;
+    protected reportObserveDeep(): void;
+    reportObserved(deep?: boolean): void;
+}

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

@@ -0,0 +1,23 @@
+import { AtomNode, ObservedAtomNode, SignalNode } from "../preact";
+declare class NodeMap<K = unknown, GraphNode extends AtomNode | SignalNode<unknown> = AtomNode | SignalNode<unknown>> {
+    private map;
+    private weakMap;
+    private observedAtom?;
+    private cleanUpRegistered;
+    constructor(observedAtom?: ObservedAtomNode);
+    private registerCleanup;
+    protected createNode(_initialValue?: unknown): GraphNode;
+    get(key: unknown): GraphNode | undefined;
+    delete(key: K): void;
+    add(key: K, atom: GraphNode): void;
+    getOrCreate(key: K, value?: unknown): GraphNode;
+    reportObserved(key: K, value?: unknown): void;
+    reportChanged(key: K, value?: unknown): void;
+}
+export declare class AtomMap<K = unknown> extends NodeMap<K, AtomNode> {
+    protected createNode(): AtomNode;
+}
+export declare class SignalMap<K = unknown, V = unknown> extends NodeMap<K, SignalNode<V>> {
+    protected createNode(initialValue?: unknown): SignalNode<V>;
+}
+export {};

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

@@ -0,0 +1,14 @@
+import { CollectionAdministration } from "../collection";
+import { PreactObjectAdministration } from "../preact";
+import { ArrayAdministration } from "../array";
+import { DateAdministration } from "../date";
+import { 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;
+export declare function getObservableClassInstance<T extends object>(value: T): 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 isObservable(obj: unknown): boolean;
+export declare function getInternalNode(obj: object, key?: PropertyKey): any;

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

@@ -0,0 +1,9 @@
+import { 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 declare function getPropertyType(key: PropertyKey, obj: object): PropertyType;
+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

@@ -0,0 +1,25 @@
+import { AtomNode, ComputedNode } from "./preact";
+import { 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> {
+    keysAtom: AtomNode;
+    hasMap: AtomMap<PropertyKey>;
+    valuesMap: SignalMap<PropertyKey>;
+    computedMap: Map<PropertyKey, ComputedNode<T[keyof T]>>;
+    types: Map<PropertyKey, PropertyType>;
+    static proxyTraps: ProxyHandler<object>;
+    constructor(source?: T);
+    private get;
+    private set;
+    private getComputed;
+    private callComputed;
+    private getType;
+    protected reportObserveDeep(): void;
+    reportChanged(): void;
+    getNode(key?: keyof T): unknown;
+    read(key: keyof T): unknown;
+    write(key: keyof T, newValue: T[keyof T]): void;
+    has(key: keyof T): boolean;
+    remove(key: keyof T): void;
+}

package/dist/observables/preact.d.ts

@@ -0,0 +1,68 @@
+import { Signal, ReadonlySignal } from "@preact/signals-core";
+import { ObjectAdministration } from "./object";
+export { isObservable } from "./index";
+export declare class PreactObjectAdministration<T extends object> extends ObjectAdministration<T> {
+    static proxyTraps: ProxyHandler<object>;
+}
+export interface AtomNode {
+    reportObserved(): void;
+    reportChanged(val?: unknown): void;
+    node?: Signal<unknown>;
+}
+export type ObservedAtomNode = AtomNode & {
+    observing: boolean;
+    onObservedStateChange(callback: (observing: boolean) => void): () => void;
+};
+export interface SignalNode<T> {
+    reportObserved(): void;
+    reportChanged(val: T): void;
+    node?: Signal<T>;
+    get: () => T;
+    set: (value: T) => T;
+}
+export interface ComputedNode<T> {
+    get(): T;
+    node?: ReadonlySignal<T>;
+    clear: () => void;
+}
+export interface ListenerNode {
+    dispose: () => void;
+    track: <T>(trackFn: () => T) => T;
+    isDisposed: boolean;
+}
+export declare function createObservedAtom(): {
+    node: Signal<number>;
+    reportObserved(): number;
+    reportChanged(): number;
+    readonly observing: boolean;
+    onObservedStateChange(callback: (observing: boolean) => void): () => void;
+};
+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 type Listener = {
+    dispose: () => void;
+    track: <T>(trackFn: () => T) => T;
+    isDisposed: boolean;
+    callback(listener: Listener): void;
+};
+export declare function createListener(callback: (listener: Listener) => void): Listener;
+export declare function createComputed<T>(fn: () => T, context?: unknown): ComputedNode<T>;
+export type PreactObservable<T> = T extends Function ? T : T extends Map<infer K, infer V> ? Map<K, PreactObservable<V>> : T extends Array<infer V> ? Array<PreactObservable<V>> : T extends Set<infer V> ? Set<PreactObservable<V>> : T extends WeakSet<infer V> ? WeakSet<PreactObservable<V>> : T extends WeakMap<infer K, infer V> ? WeakMap<K, PreactObservable<V>> : {
+    [key in keyof T]: T[key] extends object ? PreactObservable<T[key]> : T[key];
+} & {
+    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 source<T>(obj: PreactObservable<T> | T): T;
+export declare function runInBatch<T>(fn: () => T): T;
+export declare class Observable {
+    constructor();
+}
+export declare function reportChanged<T extends object>(obj: T): T;
+export declare function reportObserved<T extends object>(obj: T, opts?: {
+    deep?: boolean;
+}): T;
+export declare function getSignal<T extends object>(obj: T, key: keyof T): Signal<T[keyof T]>;