xstate 6.0.0-alpha.65 → 6.0.0-alpha.66

package/README.md

@@ -54,7 +54,7 @@ The helper requires input for actors whose input excludes `undefined`, and check
 
 <!-- JSON loading and runtime validation from packages/core/src/createMachineFromConfig.ts -->
 
-Revive JSON definitions with `createMachineFromConfig(json, { schemas, validator, ...sources })` to restore runtime validation. The loader validates structural keys and references and copies its input; serialized definitions are independent copies. See [serialization](../../docs/serialization.md).
+Revive JSON definitions with `createMachineFromConfig(json, { schemas, validator, ...sources })` to restore runtime validation. The loader validates config keys and references. See [serialization](../../docs/serialization.md).
 
 For flat finite state machines, `xstate/fsm` provides a tiny pure transition
 table with context and TypeScript support:
@@ -659,6 +659,6 @@ explicitly configured routes. Payload checks require runtime schemas;
 
 <!-- entry effects and terminal transition behavior from packages/core/src/stateUtils.ts and transitionActions.ts -->
 
-Functions passed to `enq(...)` run as effects; their returned context or child patches are ignored, with a development warning. Return a computed patch from the transition, entry, or exit function instead. Entry/exit functions using enqueue must declare exactly `(args, enq)`; default/rest parameter wrappers receive a development diagnostic. See [actions](../../docs/actions.md).
+Use the `enq` argument in transition, entry and exit functions to queue effects. Return context or child patches from those functions; the return value of an enqueued effect is ignored, with a development warning. See [actions](../../docs/actions.md).
 
-Pure transitions preserve terminal snapshots and return no effects. `snapshot.can(...)` returns `false` for terminal snapshots; active dry runs propagate evaluation errors. See [snapshots](../../docs/snapshots.md) and [states](../../docs/states.md).
+For actors that are done, stopped or failed, pure transitions return the same snapshot and no effects, and `snapshot.can(...)` returns `false`. See [snapshots](../../docs/snapshots.md) and [states](../../docs/states.md).

package/dist/{createActor-4629a290.esm.js → createActor-18a56099.esm.js}

@@ -451,81 +451,6 @@ function createSubscriptionLogic() {
 /** @public */
 const subscriptionLogic = /* #__PURE__ */createSubscriptionLogic();
 
-/** Marks the internal lazy scope without imposing structure on custom runtimes. @internal */
-const lazyActorScope = Symbol();
-/** Whether actor capabilities are represented by a lazy pure-transition scope. @internal */
-function isLazyActorScope(actorScope) {
-  return !!actorScope[lazyActorScope];
-}
-
-/** Reads parent metadata without otherwise touching actor capabilities. @internal */
-function getActorScopeParent(actorScope) {
-  return isLazyActorScope(actorScope) ? actorScope._parent : actorScope.self._parent;
-}
-
-/** Adds only `self`, preserving callback surfaces that expose no other capabilities. @internal */
-function withActorSelf(args, actorScope) {
-  if (!isLazyActorScope(actorScope)) {
-    return Object.assign(args, {
-      self: actorScope.self
-    });
-  }
-  Object.defineProperty(args, 'self', {
-    enumerable: true,
-    get: () => actorScope.self
-  });
-  return args;
-}
-
-/** Adds the actor reference and parent without exposing the system. @internal */
-function withActorSelfAndParent(args, actorScope) {
-  if (!isLazyActorScope(actorScope)) {
-    const self = actorScope.self;
-    return Object.assign(args, {
-      self,
-      parent: self._parent
-    });
-  }
-  Object.defineProperties(args, {
-    self: {
-      enumerable: true,
-      get: () => actorScope.self
-    },
-    parent: {
-      enumerable: true,
-      get: () => getActorScopeParent(actorScope)
-    }
-  });
-  return args;
-}
-
-/** Adds actor capabilities without reading them until the callback does. @internal */
-function withActorScope(args, actorScope) {
-  if (!isLazyActorScope(actorScope)) {
-    const actorArgs = args;
-    const self = actorScope.self;
-    actorArgs.self = self;
-    actorArgs.system = actorScope.system;
-    actorArgs.parent = self._parent;
-    return actorArgs;
-  }
-  Object.defineProperties(args, {
-    self: {
-      enumerable: true,
-      get: () => actorScope.self
-    },
-    system: {
-      enumerable: true,
-      get: () => actorScope.system
-    },
-    parent: {
-      enumerable: true,
-      get: () => getActorScopeParent(actorScope)
-    }
-  });
-  return args;
-}
-
 function execCustomEffect() {
   const result = this.action?.(...this.args);
   return result;
@@ -1316,28 +1241,10 @@ async function executeEffects(effects, runtime) {
     await effect.exec(runtime);
   }
 }
-function resolveActionsWithContext(currentSnapshot, event, actorScope, actions) {
+function resolveActionsWithContext(currentSnapshot, _event, actorScope, actions) {
   let intermediateSnapshot = currentSnapshot;
   const executableActions = [];
   for (const action of actions) {
-    const actionArgs = isLazyActorScope(actorScope) ? withActorScope({
-      context: intermediateSnapshot.context,
-      event,
-      output: getEventOutput(event),
-      children: intermediateSnapshot.children,
-      actions: currentSnapshot.machine.sources.actions,
-      actors: currentSnapshot.machine.sources.actors
-    }, actorScope) : {
-      context: intermediateSnapshot.context,
-      event,
-      output: getEventOutput(event),
-      self: actorScope.self,
-      system: actorScope.system,
-      parent: actorScope.self._parent,
-      children: intermediateSnapshot.children,
-      actions: currentSnapshot.machine.sources.actions,
-      actors: currentSnapshot.machine.sources.actors
-    };
     const isInline = typeof action === 'function';
     const actionRecord = getTransitionActionRecord(action);
     let resolvedActionArgs = actionRecord?.args;
@@ -1365,33 +1272,6 @@ function resolveActionsWithContext(currentSnapshot, event, actorScope, actions)
     if (actionRecord?.childUpdate) {
       intermediateSnapshot = applyChildUpdate(intermediateSnapshot, actionRecord.childUpdate, actorScope);
     }
-    if (resolvedAction && '_special' in resolvedAction) {
-      executableActions.push({
-        kind: 'action',
-        exec: execCustomEffect,
-        type: typeof action === 'object' ? 'action' in action && typeof action.action === 'function' ? action.action.name ?? '(anonymous)' : action.type ?? '(anonymous)' : action.name || '(anonymous)',
-        params: actionParams,
-        args: [],
-        action: undefined
-      });
-      const specialAction = resolvedAction;
-      const res = specialAction(actionArgs, emptyEnqueueObject);
-      if (res && ('context' in res || 'children' in res)) {
-        // Special-action patches never change `nodes`, so a shallow clone is
-        // equivalent to `cloneMachineSnapshot` — and keeps this module (and
-        // non-machine logic like `createFSM`) independent of State.ts.
-        intermediateSnapshot = {
-          ...intermediateSnapshot,
-          ...(res.context !== undefined ? {
-            context: mergeContextPatch(intermediateSnapshot.context, res.context)
-          } : {}),
-          ...('children' in res ? {
-            children: res.children
-          } : {})
-        };
-      }
-      continue;
-    }
     if (!resolvedAction || !('resolve' in resolvedAction)) {
       const builtInFields = typeof action === 'object' && action !== null && 'action' in action && typeof action.action === 'function' ? getBuiltInActionFields(action.action, resolvedActionArgs) : undefined;
       const isEmittedEvent = typeof action === 'object' && action !== null && !actionRecord;
@@ -1439,7 +1319,6 @@ function createEnqueueObject(props, action) {
 }
 const noop = () => {};
 const emptyActor = () => ({});
-const emptyEnqueueObject = createEnqueueObject({}, noop);
 
 function parseDurationToMilliseconds(duration) {
   const normalizedDuration = duration.trim();
@@ -1771,6 +1650,81 @@ function setSnapshotActorRef(snapshot, actor, baseSystem = actor.system, previou
   });
 }
 
+/** Marks the internal lazy scope without imposing structure on custom runtimes. @internal */
+const lazyActorScope = Symbol();
+/** Whether actor capabilities are represented by a lazy pure-transition scope. @internal */
+function isLazyActorScope(actorScope) {
+  return !!actorScope[lazyActorScope];
+}
+
+/** Reads parent metadata without otherwise touching actor capabilities. @internal */
+function getActorScopeParent(actorScope) {
+  return isLazyActorScope(actorScope) ? actorScope._parent : actorScope.self._parent;
+}
+
+/** Adds only `self`, preserving callback surfaces that expose no other capabilities. @internal */
+function withActorSelf(args, actorScope) {
+  if (!isLazyActorScope(actorScope)) {
+    return Object.assign(args, {
+      self: actorScope.self
+    });
+  }
+  Object.defineProperty(args, 'self', {
+    enumerable: true,
+    get: () => actorScope.self
+  });
+  return args;
+}
+
+/** Adds the actor reference and parent without exposing the system. @internal */
+function withActorSelfAndParent(args, actorScope) {
+  if (!isLazyActorScope(actorScope)) {
+    const self = actorScope.self;
+    return Object.assign(args, {
+      self,
+      parent: self._parent
+    });
+  }
+  Object.defineProperties(args, {
+    self: {
+      enumerable: true,
+      get: () => actorScope.self
+    },
+    parent: {
+      enumerable: true,
+      get: () => getActorScopeParent(actorScope)
+    }
+  });
+  return args;
+}
+
+/** Adds actor capabilities without reading them until the callback does. @internal */
+function withActorScope(args, actorScope) {
+  if (!isLazyActorScope(actorScope)) {
+    const actorArgs = args;
+    const self = actorScope.self;
+    actorArgs.self = self;
+    actorArgs.system = actorScope.system;
+    actorArgs.parent = self._parent;
+    return actorArgs;
+  }
+  Object.defineProperties(args, {
+    self: {
+      enumerable: true,
+      get: () => actorScope.self
+    },
+    system: {
+      enumerable: true,
+      get: () => actorScope.system
+    },
+    parent: {
+      enumerable: true,
+      get: () => getActorScopeParent(actorScope)
+    }
+  });
+  return args;
+}
+
 /** @internal */
 function setInertActorScopeSnapshot(actorScope, snapshot, attachActorRef = true) {
   const lazyState = getLazyInertActorState(actorScope);
@@ -2857,75 +2811,47 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
       return !!targets?.length || !!reenter;
     });
     const getStateActionsAndContext = (transitionFn, context, children, input, kind, stateNode) => {
-      if (transitionFn.length === 2) {
-        // enqueue action; retrieve
-        const actions = [];
-        const internalEvents = [];
-        let updatedContext;
-        const enqueue = createTransitionEnqueue(actorScope, actions, internalEvents, true);
-        const args = isLazyActorScope(actorScope) ? withActorScope({
-          context,
-          event,
-          children,
-          actions: currentSnapshot.machine.sources.actions,
-          actors: currentSnapshot.machine.sources.actors,
-          guards: currentSnapshot.machine.sources.guards,
-          delays: currentSnapshot.machine.sources.delays,
-          input,
-          stateNode
-        }, actorScope) : {
-          context,
-          event,
-          parent: actorScope.self._parent,
-          self: actorScope.self,
-          children,
-          system: actorScope.system,
-          actions: currentSnapshot.machine.sources.actions,
-          actors: currentSnapshot.machine.sources.actors,
-          guards: currentSnapshot.machine.sources.guards,
-          delays: currentSnapshot.machine.sources.delays,
-          input,
-          stateNode
-        };
-        let res;
-        try {
-          res = transitionFn(args, enqueue);
-        } finally {
-          closeTransitionEnqueue(enqueue);
-        }
-        assertSyncTransitionResult(res, event, stateNode.id, kind);
-        if (res?.context !== undefined) {
-          updatedContext = mergeContextPatch(context, res.context);
-        }
-        return [actions, updatedContext, internalEvents];
-      }
-
-      // For 1-argument actions, wrap them to include input
-      // Preserve _special flag if present (for entry/exit actions)
-      const wrappedAction = Object.assign((args, enqueue) => transitionFn(isLazyActorScope(actorScope) ? withActorScope({
-        context: args.context,
-        event: args.event,
-        output: args.output,
-        children: args.children,
-        actions: args.actions,
-        actors: args.actors,
+      const actions = [];
+      const internalEvents = [];
+      let updatedContext;
+      const enqueue = createTransitionEnqueue(actorScope, actions, internalEvents, true);
+      const args = isLazyActorScope(actorScope) ? withActorScope({
+        context,
+        event,
+        output: getEventOutput(event),
+        children,
+        actions: currentSnapshot.machine.sources.actions,
+        actors: currentSnapshot.machine.sources.actors,
         guards: currentSnapshot.machine.sources.guards,
         delays: currentSnapshot.machine.sources.delays,
         input,
         stateNode
       }, actorScope) : {
-        ...args,
+        context,
+        event,
+        output: getEventOutput(event),
+        parent: actorScope.self._parent,
+        self: actorScope.self,
+        children,
+        system: actorScope.system,
+        actions: currentSnapshot.machine.sources.actions,
+        actors: currentSnapshot.machine.sources.actors,
         guards: currentSnapshot.machine.sources.guards,
         delays: currentSnapshot.machine.sources.delays,
         input,
         stateNode
-      },
-      // This function runs during action resolution, where enqueued
-      // effects are no longer collected.
-      enqueue), '_special' in transitionFn ? {
-        _special: true
-      } : {});
-      return [[wrappedAction], undefined, undefined];
+      };
+      let res;
+      try {
+        res = transitionFn(args, enqueue);
+      } finally {
+        closeTransitionEnqueue(enqueue);
+      }
+      assertSyncTransitionResult(res, event, stateNode.id, kind);
+      if (res?.context !== undefined) {
+        updatedContext = mergeContextPatch(context, res.context);
+      }
+      return [actions, updatedContext, internalEvents, res?.children];
     };
     let nextState = currentSnapshot;
     const getInvokeStopActions = (stateNode, children) => {
@@ -2960,13 +2886,18 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
       }
       for (const exitStateNode of statesToExit) {
         const stateInput = getStateInput(currentSnapshot, exitStateNode.id);
-        const [exitActions, nextContext, internalEvents] = exitStateNode.exit ? getStateActionsAndContext(exitStateNode.exit, nextState.context, nextState.children, stateInput, 'exit', exitStateNode) : [[], undefined, undefined];
+        const [exitActions, nextContext, internalEvents, nextChildren] = exitStateNode.exit ? getStateActionsAndContext(exitStateNode.exit, nextState.context, nextState.children, stateInput, 'exit', exitStateNode) : [[], undefined, undefined, undefined];
         if (internalEvents?.length) {
           internalQueue.push(...internalEvents);
         }
-        if (nextContext) {
+        if (nextContext || nextChildren) {
           nextState = cloneMachineSnapshot(nextState, {
-            context: nextContext
+            ...(nextContext ? {
+              context: nextContext
+            } : {}),
+            ...(nextChildren ? {
+              children: nextChildren
+            } : {})
           });
         }
         const [resolvedState, resolvedActions] = resolveActionsWithContext(nextState, event, actorScope, exitActions);
@@ -3227,7 +3158,7 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
         let contextChangedByEntry = false;
         const stateInput = stateInputMap[stateNodeToEnter.id];
         if (stateNodeToEnter.entry) {
-          const [resultActions, nextContext, nextInternalEvents] = getStateActionsAndContext(stateNodeToEnter.entry, context, children, stateInput, 'entry', stateNodeToEnter);
+          const [resultActions, nextContext, nextInternalEvents, nextChildren] = getStateActionsAndContext(stateNodeToEnter.entry, context, children, stateInput, 'entry', stateNodeToEnter);
           actions.push(...resultActions);
           if (nextInternalEvents?.length) {
             internalQueue.push(...nextInternalEvents);
@@ -3236,6 +3167,11 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
             context = nextContext;
             contextChangedByEntry = true;
           }
+          if (nextChildren) {
+            nextState = cloneMachineSnapshot(nextState, {
+              children: nextChildren
+            });
+          }
         }
         if (contextChangedByEntry) {
           nextState.context = context;
@@ -3335,10 +3271,15 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
       nextStateNodesToExit.forEach(stateNode => {
         if (stateNode.exit) {
           const stateInput = getStateInput(nextState, stateNode.id);
-          const [exitActions, nextContext, nextInternalEvents] = getStateActionsAndContext(stateNode.exit, nextState.context, nextState.children, stateInput, 'exit', stateNode);
-          if (nextContext) {
+          const [exitActions, nextContext, nextInternalEvents, nextChildren] = getStateActionsAndContext(stateNode.exit, nextState.context, nextState.children, stateInput, 'exit', stateNode);
+          if (nextContext || nextChildren) {
             nextState = cloneMachineSnapshot(nextState, {
-              context: nextContext
+              ...(nextContext ? {
+                context: nextContext
+              } : {}),
+              ...(nextChildren ? {
+                children: nextChildren
+              } : {})
             });
           }
           allExitActions.push(...exitActions);