jotai-state-tree 1.2.1 → 1.3.1

package/README.md

@@ -67,6 +67,7 @@ Explore our detailed, exhaustive guides to master `jotai-state-tree`:
 5. **[React Integration](docs/react-integration.md)** - Observables HOCs, typed context Providers, hooks (`useSnapshot`, `useWatchPath`), and update batching.
 6. **[Advanced Features](docs/advanced-features.md)** - Undo/Redo managers, Time Travel, Action recorders, dynamic plugins/registry, and middleware pipelines.
 7. **[Migration from MobX-State-Tree](docs/mst-migration.md)** - Step-by-step replacement guide, performance comparisons, and key differences.
+8. **[Examples & Templates](docs/examples-and-templates.md)** - 6 pre-configured Vite starter templates, features breakdown, and project scaffolding instructions.
 
 ---
 

package/dist/{chunk-UOYV4J7H.mjs → chunk-OAXK4KFM.mjs}

@@ -617,6 +617,9 @@ function recordPatches(target) {
   };
 }
 var currentAction = null;
+function getCurrentAction() {
+  return currentAction;
+}
 var actionListeners = /* @__PURE__ */ new Set();
 var actionRecorderHooks = [];
 function registerActionRecorderHook(hook) {
@@ -882,6 +885,7 @@ export {
   onPatch,
   applyPatch,
   recordPatches,
+  getCurrentAction,
   registerActionRecorderHook,
   isActionRunning,
   trackAction,

package/dist/index.d.mts

@@ -362,9 +362,14 @@ interface IMiddlewareHandler {
     (call: IMiddlewareEvent, next: (call: IMiddlewareEvent, callback?: (value: unknown) => unknown) => unknown, abort: (value: unknown) => unknown): unknown;
 }
 /**
- * Add middleware to the global stack
+ * Add middleware to the stack/node
  */
 declare function addMiddleware(target: unknown, handler: IMiddlewareHandler, includeHooks?: boolean): IDisposer;
+/**
+ * Creates an async action (generator function) that can be yielded.
+ * Compatible with MST's flow().
+ */
+declare function flow<Args extends unknown[], R>(generator: (...args: Args) => Generator<Promise<unknown>, R, unknown>): (...args: Args) => Promise<R>;
 interface ISerializedActionCall {
     name: string;
     path: string;
@@ -646,11 +651,6 @@ declare const types: {
     safeDynamicReference: typeof safeDynamicReference;
 };
 
-/**
- * Creates an async action (generator function) that can be yielded.
- * Compatible with MST's flow().
- */
-declare function flow<Args extends unknown[], R>(generator: (...args: Args) => Generator<Promise<unknown>, R, unknown>): (...args: Args) => Promise<R>;
 /**
  * Cast a value to a different type.
  * Useful for working around TypeScript limitations.

package/dist/index.d.ts

@@ -362,9 +362,14 @@ interface IMiddlewareHandler {
     (call: IMiddlewareEvent, next: (call: IMiddlewareEvent, callback?: (value: unknown) => unknown) => unknown, abort: (value: unknown) => unknown): unknown;
 }
 /**
- * Add middleware to the global stack
+ * Add middleware to the stack/node
  */
 declare function addMiddleware(target: unknown, handler: IMiddlewareHandler, includeHooks?: boolean): IDisposer;
+/**
+ * Creates an async action (generator function) that can be yielded.
+ * Compatible with MST's flow().
+ */
+declare function flow<Args extends unknown[], R>(generator: (...args: Args) => Generator<Promise<unknown>, R, unknown>): (...args: Args) => Promise<R>;
 interface ISerializedActionCall {
     name: string;
     path: string;
@@ -646,11 +651,6 @@ declare const types: {
     safeDynamicReference: typeof safeDynamicReference;
 };
 
-/**
- * Creates an async action (generator function) that can be yielded.
- * Compatible with MST's flow().
- */
-declare function flow<Args extends unknown[], R>(generator: (...args: Args) => Generator<Promise<unknown>, R, unknown>): (...args: Args) => Promise<R>;
 /**
  * Cast a value to a different type.
  * Useful for working around TypeScript limitations.

package/dist/index.js

@@ -1048,6 +1048,9 @@ function recordPatches(target) {
   };
 }
 var currentAction = null;
+function getCurrentAction() {
+  return currentAction;
+}
 var actionListeners = /* @__PURE__ */ new Set();
 var actionRecorderHooks = [];
 function registerActionRecorderHook(hook) {
@@ -1318,8 +1321,26 @@ function runBeforeDestroy(node) {
     hooks.beforeDestroy();
   }
 }
+var activeMiddlewareEvent = null;
+var middlewareIdCounter = 0;
 var middlewareStack = [];
+var nodeMiddlewares = /* @__PURE__ */ new WeakMap();
 function addMiddleware(target, handler, includeHooks = true) {
+  if (target && isStateTreeNode(target)) {
+    const node = getStateTreeNode(target);
+    let middlewares = nodeMiddlewares.get(node);
+    if (!middlewares) {
+      middlewares = /* @__PURE__ */ new Set();
+      nodeMiddlewares.set(node, middlewares);
+    }
+    middlewares.add(handler);
+    return () => {
+      const current = nodeMiddlewares.get(node);
+      if (current) {
+        current.delete(handler);
+      }
+    };
+  }
   middlewareStack.push(handler);
   return () => {
     const index = middlewareStack.indexOf(handler);
@@ -1328,6 +1349,199 @@ function addMiddleware(target, handler, includeHooks = true) {
     }
   };
 }
+function getMiddlewaresForNode(node) {
+  const handlers = [];
+  let current = node;
+  while (current) {
+    const middlewares = nodeMiddlewares.get(current);
+    if (middlewares) {
+      handlers.unshift(...Array.from(middlewares));
+    }
+    current = current.$parent;
+  }
+  return [...Array.from(middlewareStack), ...handlers];
+}
+function runMiddlewares(node, event, fn) {
+  const handlers = getMiddlewaresForNode(node);
+  if (handlers.length === 0) {
+    const previousEvent = activeMiddlewareEvent;
+    activeMiddlewareEvent = event;
+    try {
+      return fn(event);
+    } finally {
+      activeMiddlewareEvent = previousEvent;
+    }
+  }
+  let index = 0;
+  let aborted = false;
+  let abortValue;
+  const abort = (value) => {
+    aborted = true;
+    abortValue = value;
+    return value;
+  };
+  const next = (call, callback) => {
+    if (aborted) return abortValue;
+    const previousEvent = activeMiddlewareEvent;
+    activeMiddlewareEvent = call;
+    try {
+      if (index >= handlers.length) {
+        const result = fn(call);
+        return callback ? callback(result) : result;
+      }
+      const middleware = handlers[index++];
+      return middleware(call, next, abort);
+    } finally {
+      activeMiddlewareEvent = previousEvent;
+    }
+  };
+  return next(event);
+}
+function createMiddlewareRunner(node, actionName, args) {
+  const id = ++middlewareIdCounter;
+  const parentEvent = activeMiddlewareEvent;
+  const event = {
+    type: "action",
+    name: actionName,
+    id,
+    parentId: parentEvent ? parentEvent.id : 0,
+    rootId: parentEvent ? parentEvent.rootId : id,
+    context: node.getInstance(),
+    tree: node.getRoot().getInstance(),
+    args,
+    parentEvent: parentEvent ?? void 0
+  };
+  return (fn) => {
+    return runMiddlewares(node, event, fn);
+  };
+}
+function flow(generator) {
+  return function flowAction(...args) {
+    const node = (this && typeof this === "object" && $treenode in this ? this[$treenode] : null) ?? getCurrentAction()?.tree;
+    if (!node) {
+      let step2 = function(nextFn) {
+        let result;
+        try {
+          result = nextFn();
+        } catch (e) {
+          return Promise.reject(e);
+        }
+        if (result.done) {
+          return Promise.resolve(result.value);
+        }
+        return Promise.resolve(result.value).then(
+          (value) => step2(() => gen2.next(value)),
+          (error) => step2(() => gen2.throw(error))
+        );
+      };
+      var step = step2;
+      const gen2 = generator.apply(this, args);
+      return step2(() => gen2.next(void 0));
+    }
+    const actionName = getCurrentAction()?.name ?? "anonymousFlow";
+    const gen = generator.apply(this, args);
+    const actionEvent = activeMiddlewareEvent;
+    const spawnEventId = ++middlewareIdCounter;
+    const spawnEvent = {
+      type: "flow_spawn",
+      name: actionName,
+      id: spawnEventId,
+      parentId: actionEvent ? actionEvent.id : 0,
+      rootId: actionEvent ? actionEvent.rootId : spawnEventId,
+      context: node.getInstance(),
+      tree: node.getRoot().getInstance(),
+      args,
+      parentEvent: actionEvent ?? void 0
+    };
+    return new Promise((resolve, reject) => {
+      runMiddlewares(node, spawnEvent, () => {
+        function step2(nextFn, isResume, resumeError) {
+          let result;
+          if (isResume) {
+            if (!node.$isAlive) {
+              gen.return(void 0);
+              handleThrow(new Error("FLOW_CANCELLED"));
+              return;
+            }
+            const resumeEventId = ++middlewareIdCounter;
+            const resumeEvent = {
+              type: resumeError !== void 0 ? "flow_resume_error" : "flow_resume",
+              name: actionName,
+              id: resumeEventId,
+              parentId: spawnEvent.id,
+              rootId: spawnEvent.rootId,
+              context: node.getInstance(),
+              tree: node.getRoot().getInstance(),
+              args: resumeError !== void 0 ? [resumeError] : [],
+              parentEvent: spawnEvent
+            };
+            runMiddlewares(node, resumeEvent, () => {
+              try {
+                result = trackAction(node, actionName, args, () => {
+                  return nextFn();
+                });
+              } catch (e) {
+                handleThrow(e);
+                return;
+              }
+              handleResult(result);
+            });
+          } else {
+            try {
+              result = nextFn();
+            } catch (e) {
+              handleThrow(e);
+              return;
+            }
+            handleResult(result);
+          }
+        }
+        function handleResult(result) {
+          if (result.done) {
+            const returnEventId = ++middlewareIdCounter;
+            const returnEvent = {
+              type: "flow_return",
+              name: actionName,
+              id: returnEventId,
+              parentId: spawnEvent.id,
+              rootId: spawnEvent.rootId,
+              context: node.getInstance(),
+              tree: node.getRoot().getInstance(),
+              args: [result.value],
+              parentEvent: spawnEvent
+            };
+            runMiddlewares(node, returnEvent, () => {
+              resolve(result.value);
+            });
+          } else {
+            Promise.resolve(result.value).then(
+              (value) => step2(() => gen.next(value), true),
+              (error) => step2(() => gen.throw(error), true, error)
+            );
+          }
+        }
+        function handleThrow(error) {
+          const throwEventId = ++middlewareIdCounter;
+          const throwEvent = {
+            type: "flow_throw",
+            name: actionName,
+            id: throwEventId,
+            parentId: spawnEvent.id,
+            rootId: spawnEvent.rootId,
+            context: node.getInstance(),
+            tree: node.getRoot().getInstance(),
+            args: [error],
+            parentEvent: spawnEvent
+          };
+          runMiddlewares(node, throwEvent, () => {
+            reject(error);
+          });
+        }
+        step2(() => gen.next(void 0), false);
+      });
+    });
+  };
+}
 var actionRecorders = /* @__PURE__ */ new WeakMap();
 function recordActions(target) {
   const node = getStateTreeNode(target);
@@ -1406,6 +1620,9 @@ function isProtected(target) {
   return !isNodeUnprotected(node);
 }
 function canWrite(node) {
+  if (!node.$isAlive) {
+    return false;
+  }
   if (typeof process !== "undefined" && process.env && process.env.NODE_ENV === "production") {
     return true;
   }
@@ -1578,6 +1795,9 @@ var ModelType = class _ModelType {
         if (prop === "$treenode") {
           return node;
         }
+        if (!node.$isAlive) {
+          throw new Error(`[jotai-state-tree] Cannot access '${String(prop)}' - the node is dead.`);
+        }
         const propStr = String(prop);
         if (propertyAtoms.has(propStr)) {
           const childNode = node.getChild(propStr);
@@ -1614,6 +1834,9 @@ var ModelType = class _ModelType {
       set(target, prop, value) {
         const propStr = String(prop);
         if (propertyAtoms.has(propStr)) {
+          if (!node.$isAlive) {
+            throw new Error(`[jotai-state-tree] Cannot modify '${propStr}' - the node is dead.`);
+          }
           if (!canWrite(node)) {
             throw new Error(`Cannot modify '${propStr}' - the object is protected and can only be modified inside an action.`);
           }
@@ -1665,6 +1888,9 @@ var ModelType = class _ModelType {
           return true;
         }
         if (propStr in node.volatileState) {
+          if (!node.$isAlive) {
+            throw new Error(`[jotai-state-tree] Cannot modify volatile property '${propStr}' - the node is dead.`);
+          }
           if (!canWrite(node)) {
             throw new Error(`Cannot modify volatile property '${propStr}' - the object is protected and can only be modified inside an action.`);
           }
@@ -1714,8 +1940,11 @@ var ModelType = class _ModelType {
       for (const [key, value] of Object.entries(actions)) {
         if (typeof value === "function") {
           allActions[key] = (...args) => {
-            return trackAction(node, key, args, () => {
-              return value.apply(proxy, args);
+            const runner = createMiddlewareRunner(node, key, args);
+            return runner((currEvent) => {
+              return trackAction(node, currEvent.name, currEvent.args, () => {
+                return value.apply(proxy, currEvent.args);
+              });
             });
           };
           if (key === "afterCreate" || key === "afterAttach" || key === "beforeDetach" || key === "beforeDestroy") {
@@ -2016,6 +2245,9 @@ var MSTArray = class _MSTArray extends Array {
     Object.setPrototypeOf(this, _MSTArray.prototype);
   }
   checkWrite() {
+    if (!this.node.$isAlive) {
+      throw new Error("[jotai-state-tree] Cannot modify array - the node is dead.");
+    }
     if (!canWrite(this.node)) {
       throw new Error(
         `Cannot modify the array - the parent object is protected and can only be modified inside an action.`
@@ -2277,12 +2509,18 @@ var ArrayType = class {
         if (prop === $treenode) {
           return node;
         }
+        if (!node.$isAlive) {
+          throw new Error("[jotai-state-tree] Cannot access array - the node is dead.");
+        }
         return Reflect.get(target, prop, receiver);
       },
       set(target, prop, value) {
         const propStr = String(prop);
         const isIndex = /^\d+$/.test(propStr);
         if (isIndex || propStr === "length") {
+          if (!node.$isAlive) {
+            throw new Error("[jotai-state-tree] Cannot modify array - the node is dead.");
+          }
           if (!canWrite(node)) {
             throw new Error(
               `Cannot modify the array - the parent object is protected and can only be modified inside an action.`
@@ -2357,6 +2595,9 @@ var MSTMap = class extends Map {
     }
   }
   checkWrite() {
+    if (!this.node.$isAlive) {
+      throw new Error("[jotai-state-tree] Cannot modify map - the node is dead.");
+    }
     if (!canWrite(this.node)) {
       throw new Error(
         `Cannot modify the map - the parent object is protected and can only be modified inside an action.`
@@ -2403,8 +2644,10 @@ var MSTMap = class extends Map {
     }
     return this;
   }
-  // Override get to return the instance from child node for complex types
   get(key) {
+    if (!this.node.$isAlive) {
+      throw new Error("[jotai-state-tree] Cannot access map - the node is dead.");
+    }
     if (this.valueType._kind === "model" || this.valueType._kind === "array" || this.valueType._kind === "map") {
       const childNode = this.node.getChild(key);
       if (childNode) {
@@ -3669,27 +3912,6 @@ var types = {
   dynamicReference,
   safeDynamicReference
 };
-function flow(generator) {
-  return function flowAction(...args) {
-    const gen = generator(...args);
-    function step(nextFn) {
-      let result;
-      try {
-        result = nextFn();
-      } catch (e) {
-        return Promise.reject(e);
-      }
-      if (result.done) {
-        return Promise.resolve(result.value);
-      }
-      return Promise.resolve(result.value).then(
-        (value) => step(() => gen.next(value)),
-        (error) => step(() => gen.throw(error))
-      );
-    }
-    return step(() => gen.next(void 0));
-  };
-}
 function cast(value) {
   return value;
 }