r-state-tree 0.4.6 → 0.5.0

package/dist/r-state-tree.cjs

@@ -17,6 +17,8 @@ var CommonCfgTypes = /* @__PURE__ */ ((CommonCfgTypes2) => {
 })(CommonCfgTypes || {});
 var ModelCfgTypes = /* @__PURE__ */ ((ModelCfgTypes2) => {
   ModelCfgTypes2["state"] = "state";
+  ModelCfgTypes2["stateShallow"] = "stateShallow";
+  ModelCfgTypes2["stateSignal"] = "stateSignal";
   ModelCfgTypes2["id"] = "id";
   ModelCfgTypes2["modelRef"] = "modelRef";
   return ModelCfgTypes2;
@@ -27,6 +29,8 @@ var StoreCfgTypes = /* @__PURE__ */ ((StoreCfgTypes2) => {
 })(StoreCfgTypes || {});
 var ObservableCfgTypes = /* @__PURE__ */ ((ObservableCfgTypes2) => {
   ObservableCfgTypes2["observable"] = "observable";
+  ObservableCfgTypes2["observableShallow"] = "observableShallow";
+  ObservableCfgTypes2["observableSignal"] = "observableSignal";
   ObservableCfgTypes2["computed"] = "computed";
   return ObservableCfgTypes2;
 })(ObservableCfgTypes || {});
@@ -43,6 +47,14 @@ const stateType = {
   type: "state"
   /* state */
 };
+const stateShallowType = {
+  type: "stateShallow"
+  /* stateShallow */
+};
+const stateSignalType = {
+  type: "stateSignal"
+  /* stateSignal */
+};
 const modelRefType = Object.assign(
   function(childType2) {
     return { type: "modelRef", childType: childType2 };
@@ -85,6 +97,12 @@ function getPropertyType(key, obj) {
     switch (config.type) {
       case ObservableCfgTypes.computed:
         return "computed";
+      case ObservableCfgTypes.observableShallow:
+      case ModelCfgTypes.stateShallow:
+        return "observableShallow";
+      case ObservableCfgTypes.observableSignal:
+      case ModelCfgTypes.stateSignal:
+        return "observableSignal";
       case ModelCfgTypes.state:
       case ObservableCfgTypes.observable:
       case ModelCfgTypes.id:
@@ -353,6 +371,7 @@ class ObjectAdministration extends Administration {
     }
     switch (type) {
       case "observable":
+      case "observableShallow":
       case "action": {
         if (key in this.source) {
           this.valuesMap.reportObserved(key, this.source[key]);
@@ -364,8 +383,21 @@ class ObjectAdministration extends Administration {
         if (type === "observable") {
           return getObservable(this.get(key));
         }
+        if (type === "observableShallow") {
+          return getShallowObservable(this.get(key));
+        }
         return getAction(this.get(key));
       }
+      case "observableSignal": {
+        if (key in this.source) {
+          this.valuesMap.reportObserved(key, this.source[key]);
+        }
+        this.atom.reportObserved();
+        if (this.atom.observing) {
+          this.hasMap.reportObserved(key);
+        }
+        return this.get(key);
+      }
       case "computed": {
         return this.callComputed(key);
       }
@@ -573,13 +605,31 @@ function createComputed(fn, context = null) {
     }
   };
 }
-function observable(value, context) {
+function observableImpl(value, context) {
   if (context && typeof context === "object" && "kind" in context) {
     context.metadata[context.name] = { type: "observable" };
     return value;
   }
   return getObservable(value);
 }
+function shallowDecorator(value, context) {
+  if (context && typeof context === "object" && "kind" in context) {
+    context.metadata[context.name] = { type: "observableShallow" };
+    return value;
+  }
+  throw new Error("observable.shallow can only be used as a decorator");
+}
+function signalDecorator(value, context) {
+  if (context && typeof context === "object" && "kind" in context) {
+    context.metadata[context.name] = { type: "observableSignal" };
+    return value;
+  }
+  throw new Error("observable.signal can only be used as a decorator");
+}
+const observable = Object.assign(observableImpl, {
+  shallow: shallowDecorator,
+  signal: signalDecorator
+});
 function computed(value, context) {
   if (context && typeof context === "object" && "kind" in context) {
     context.metadata[context.name] = { type: "computed" };
@@ -791,6 +841,9 @@ class CollectionAdministration extends Administration {
     const value = sourceMap.get(targetKey) ?? sourceMap.get(key);
     if (has) {
       this.valuesMap.reportObserved(key, value);
+      if (isShallowObservable(this.proxy)) {
+        return value;
+      }
       return getObservable(value);
     }
     return void 0;
@@ -979,6 +1032,9 @@ class ArrayAdministration extends Administration {
   get(index) {
     this.atom.reportObserved();
     this.valuesMap.reportObserved(index, this.source[index]);
+    if (isShallowObservable(this.proxy)) {
+      return this.source[index];
+    }
     return getObservable(this.source[index]);
   }
   set(index, newValue) {
@@ -1244,6 +1300,39 @@ function getObservable(value) {
   }
   return value;
 }
+const shallowObservables = /* @__PURE__ */ new WeakSet();
+function isShallowObservable(obj) {
+  if (!obj || typeof obj !== "object") return false;
+  return shallowObservables.has(obj);
+}
+function getShallowObservable(value) {
+  if (!value) {
+    return value;
+  }
+  const existingAdm = getAdministration(value);
+  if (existingAdm) {
+    return existingAdm.proxy;
+  }
+  if ((typeof value === "object" || typeof value === "function") && !Object.isFrozen(value)) {
+    const obj = value;
+    let Adm = null;
+    if (Array.isArray(obj)) {
+      Adm = ArrayAdministration;
+    } else if (obj instanceof Map || obj instanceof WeakMap) {
+      Adm = CollectionAdministration;
+    } else if (obj instanceof Set || obj instanceof WeakSet) {
+      Adm = CollectionAdministration;
+    }
+    if (Adm) {
+      const adm = new Adm(obj);
+      administrationMap.set(adm.proxy, adm);
+      administrationMap.set(adm.source, adm);
+      shallowObservables.add(adm.proxy);
+      return adm.proxy;
+    }
+  }
+  return value;
+}
 function isObservable(obj) {
   if (!obj || typeof obj !== "object") return false;
   const adm = getAdministration(obj);
@@ -1317,6 +1406,33 @@ function getDiff(o1, o2, getConfig) {
   }
   return Object.keys(diff).length > 0 ? diff : null;
 }
+const MAX_MOUNT_DEPTH = 100;
+const mountingStack = [];
+function formatMountFrame(frame) {
+  const childSegment = frame.childName === void 0 ? "" : `.${String(frame.childName)}`;
+  return `${frame.storeName}${childSegment}`;
+}
+function formatMountChain(frame) {
+  const chain = [...mountingStack, frame];
+  const maxParts = 6;
+  if (chain.length > maxParts) {
+    const start = chain.slice(0, 3);
+    const end = chain.slice(-2);
+    return [
+      ...start,
+      { storeName: "...", modelsKeys: [], childName: void 0 },
+      ...end
+    ].map(formatMountFrame).join(" -> ");
+  }
+  return chain.map(formatMountFrame).join(" -> ");
+}
+function createCircularMountError(frame) {
+  const chain = formatMountChain(frame);
+  const models = frame.modelsKeys.length === 0 ? "no models provided" : `models: ${frame.modelsKeys.join(", ")}`;
+  return new Error(
+    `r-state-tree: detected circular store/model creation while mounting ${chain} (using ${models}). Passing models into child stores during mount can create recursive wiring. Move child store/model creation into storeDidMount or break the cycle.`
+  );
+}
 function updateProps(props, newProps) {
   signalsCore.untracked(() => {
     signalsCore.batch(() => {
@@ -1336,6 +1452,35 @@ function updateProps(props, newProps) {
 function getStoreAdm(store) {
   return getAdministration(store);
 }
+function validateStoreChildValue(value, propertyName) {
+  if (value === null || value === void 0) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    const invalidItem = value.find(
+      (item) => item !== null && (typeof item !== "object" || !("Type" in item) || !("props" in item) || typeof item.Type !== "function" || typeof item.props !== "object")
+    );
+    if (invalidItem !== void 0) {
+      throw new Error(
+        `r-state-tree: child property '${String(
+          propertyName
+        )}' must be a StoreElement ({ Type, props, key }), an array of StoreElements, or null/undefined. Found invalid array item: ${typeof invalidItem}`
+      );
+    }
+    return;
+  }
+  if (typeof value === "object" && value !== null && "Type" in value && "props" in value) {
+    const element = value;
+    if (typeof element.Type === "function" && typeof element.props === "object") {
+      return;
+    }
+  }
+  throw new Error(
+    `r-state-tree: child property '${String(
+      propertyName
+    )}' must be a StoreElement ({ Type, props, key }), an array of StoreElements, or null/undefined. Found: ${typeof value}`
+  );
+}
 class StoreAdministration extends PreactObjectAdministration {
   static proxyTraps = Object.assign(
     {},
@@ -1403,7 +1548,7 @@ class StoreAdministration extends PreactObjectAdministration {
         }
       });
       childStoreData.value.set(stores);
-      stores.forEach((s) => getStoreAdm(s).mount(this));
+      stores.forEach((s) => getStoreAdm(s).mount(this, name));
       return stores;
     }
     const newStores = /* @__PURE__ */ new Set();
@@ -1454,7 +1599,7 @@ class StoreAdministration extends PreactObjectAdministration {
       signalsCore.batch(() => childStoreData.value.set(stores));
     }
     removedStores.forEach((s) => getStoreAdm(s).unmount());
-    newStores.forEach((s) => getStoreAdm(s).mount(this));
+    newStores.forEach((s) => getStoreAdm(s).mount(this, name));
     return stores;
   }
   setSingleStore(name, element) {
@@ -1473,7 +1618,7 @@ class StoreAdministration extends PreactObjectAdministration {
       }
       const childStore = this.createChildStore(element);
       signalsCore.batch(() => childStoreData.value.set(childStore));
-      getStoreAdm(childStore).mount(this);
+      getStoreAdm(childStore).mount(this, name);
       return childStore;
     } else {
       signalsCore.batch(() => updateProps(oldStore.props, props));
@@ -1485,6 +1630,7 @@ class StoreAdministration extends PreactObjectAdministration {
     const storeElement = childStoreData.listener.track(
       () => childStoreData.computed.get()
     );
+    validateStoreChildValue(storeElement, name);
     Array.isArray(storeElement) ? this.setStoreList(name, storeElement) : this.setSingleStore(name, storeElement);
   }
   getComputedGetter(name) {
@@ -1505,6 +1651,7 @@ class StoreAdministration extends PreactObjectAdministration {
     const storeElement = childStoreData.listener.track(
       () => childStoreData.computed.get()
     );
+    validateStoreChildValue(storeElement, name);
     Array.isArray(storeElement) ? this.setStoreList(name, storeElement) : this.setSingleStore(name, storeElement);
     return childStoreData.value.get();
   }
@@ -1514,6 +1661,7 @@ class StoreAdministration extends PreactObjectAdministration {
       return this.initializeStore(name);
     } else {
       const storeElement = signalsCore.untracked(() => childStoreData.computed.get());
+      validateStoreChildValue(storeElement, name);
       Array.isArray(storeElement) ? this.setStoreList(name, storeElement) : this.setSingleStore(name, storeElement);
       return childStoreData.value.get();
     }
@@ -1562,18 +1710,36 @@ class StoreAdministration extends PreactObjectAdministration {
     this.reactionsUnsub.push(unsub);
     return unsub;
   }
-  mount(parent = null) {
-    this.parent = parent || null;
-    this.childStoreDataMap.forEach(({ value }) => {
-      const stores = value.get();
-      if (Array.isArray(stores)) {
-        stores?.forEach((s) => getStoreAdm(s)?.mount(this));
-      } else if (stores) {
-        getStoreAdm(stores)?.mount(this);
+  mount(parent = null, childName) {
+    const frame = {
+      storeName: this.proxy.constructor.name || "Store",
+      childName,
+      modelsKeys: Object.keys(this.proxy.props?.models ?? {})
+    };
+    if (mountingStack.length + 1 > MAX_MOUNT_DEPTH) {
+      throw createCircularMountError(frame);
+    }
+    mountingStack.push(frame);
+    try {
+      this.parent = parent || null;
+      this.childStoreDataMap.forEach(({ value }, name) => {
+        const stores = value.get();
+        if (Array.isArray(stores)) {
+          stores?.forEach((s) => getStoreAdm(s)?.mount(this, name));
+        } else if (stores) {
+          getStoreAdm(stores)?.mount(this, name);
+        }
+      });
+      this.mounted = true;
+      signalsCore.batch(() => this.proxy.storeDidMount?.());
+    } catch (error) {
+      if (error instanceof RangeError && /call stack/i.test(error.message)) {
+        throw createCircularMountError(frame);
       }
-    });
-    this.mounted = true;
-    signalsCore.batch(() => this.proxy.storeDidMount?.());
+      throw error;
+    } finally {
+      mountingStack.pop();
+    }
   }
   unmount() {
     this.proxy.storeWillUnmount?.();
@@ -1891,6 +2057,30 @@ function getSnapshotRefId(snapshot) {
   }
   return snapshot[keys[0]];
 }
+function validateModelChildValue(value, propertyName) {
+  if (value === null || value === void 0) {
+    return;
+  }
+  if (value instanceof Model) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    const invalidItem = value.find((item) => !(item instanceof Model));
+    if (invalidItem !== void 0) {
+      throw new Error(
+        `r-state-tree: child property '${String(
+          propertyName
+        )}' must be a Model instance, an array of Model instances, or null/undefined. Found invalid array item: ${typeof invalidItem}`
+      );
+    }
+    return;
+  }
+  throw new Error(
+    `r-state-tree: child property '${String(
+      propertyName
+    )}' must be a Model instance, an array of Model instances, or null/undefined. Found: ${typeof value}`
+  );
+}
 class ModelAdministration extends PreactObjectAdministration {
   static proxyTraps = Object.assign(
     {},
@@ -1924,6 +2114,7 @@ class ModelAdministration extends PreactObjectAdministration {
               return true;
             }
             case CommonCfgTypes.child: {
+              validateModelChildValue(value, name);
               if (Array.isArray(value)) {
                 adm.setModels(name, value);
                 return true;
@@ -1936,7 +2127,9 @@ class ModelAdministration extends PreactObjectAdministration {
               adm.setId(name, value);
               break;
             }
-            case ModelCfgTypes.state: {
+            case ModelCfgTypes.state:
+            case ModelCfgTypes.stateShallow:
+            case ModelCfgTypes.stateSignal: {
               adm.setState(name, value);
               break;
             }
@@ -2030,6 +2223,7 @@ class ModelAdministration extends PreactObjectAdministration {
     }
   }
   setModel(name, newModel) {
+    validateModelChildValue(newModel, name);
     const currentValue = this.proxy[name];
     if (currentValue === newModel) {
       return;
@@ -2049,6 +2243,7 @@ class ModelAdministration extends PreactObjectAdministration {
     }
   }
   setModels(name, newModelsSource) {
+    validateModelChildValue(newModelsSource, name);
     const newModels = createObservableWithCustomAdministration(
       [],
       ChildModelsAdministration
@@ -2204,6 +2399,8 @@ class ModelAdministration extends PreactObjectAdministration {
     return Object.keys(this.configuration).reduce((json, key) => {
       switch (this.configuration[key].type) {
         case ModelCfgTypes.state:
+        case ModelCfgTypes.stateShallow:
+        case ModelCfgTypes.stateSignal:
         case ModelCfgTypes.id:
           json[key] = clone(getSource(this.proxy[key]));
           break;
@@ -2269,6 +2466,8 @@ class ModelAdministration extends PreactObjectAdministration {
         const value = snapshot[key];
         switch (type) {
           case ModelCfgTypes.state:
+          case ModelCfgTypes.stateShallow:
+          case ModelCfgTypes.stateSignal:
             this.proxy[key] = value;
             break;
           case ModelCfgTypes.modelRef:
@@ -2484,10 +2683,9 @@ const child = makeChildDecorator(childType);
 const modelRef = makeChildDecorator(modelRefType);
 const model = makeDecorator(modelType);
 const id = makeDecorator(idType);
-const state = makeDecorator(stateType);
-Object.defineProperty(exports, "ReadonlySignal", {
-  enumerable: true,
-  get: () => signalsCore.ReadonlySignal
+const state = Object.assign(makeDecorator(stateType), {
+  shallow: makeDecorator(stateShallowType),
+  signal: makeDecorator(stateSignalType)
 });
 Object.defineProperty(exports, "Signal", {
   enumerable: true,