Implement predictableActionArguments feature flag

.changeset/nine-frogs-grow.md

@@ -0,0 +1,10 @@
+---
+'xstate': minor
+---
+
+A new [`predictableActionArguments`](https://xstate.js.org/docs/guides/actions.html) feature flag has been added that allows you to opt into some fixed behaviors that will be the default in v5. With this flag:
+
+- XState will always call an action with the event directly responsible for the related transition,
+- you also automatically opt-into [`preserveActionOrder`](https://xstate.js.org/docs/guides/context.html#action-order).
+
+Please be aware that you might not able to use `state` from the `meta` argument when using this flag.

docs/guides/actions.md

@@ -1,5 +1,25 @@
 # Actions
 
+::: warning
+
+It is advised to configure `predictableActionArguments: true` at the top-level of your machine config, like this:
+
+```js
+createMachine({
+  predictableActionArguments: true
+  // ...
+});
+```
+
+This flag is an opt into some fixed behaviors that will be the default in v5. With this flag:
+
+- XState will always call an action with the event directly responsible for the related transition,
+- you also automatically opt-into [`preserveActionOrder`](https://xstate.js.org/docs/guides/context.html#action-order).
+
+Please be aware that you might not able to use `state` from the `meta` argument when using this flag.
+
+:::
+
 Actions are fire-and-forget [effects](./effects.md). They can be declared in three ways:
 
 - `entry` actions are executed upon entering a state

packages/core/src/Machine.ts

@@ -17,6 +17,9 @@ import {
   TypegenDisabled,
   ResolveTypegenMeta
 } from './typegenTypes';
+import { IS_PRODUCTION } from './environment';
+
+let warned = false;
 
 /**
  * @deprecated Use `createMachine(...)` instead.
@@ -139,5 +142,11 @@ export function createMachine<
   TServiceMap,
   TTypesMeta
 > {
+  if (!IS_PRODUCTION && !config.predictableActionArguments && !warned) {
+    warned = true;
+    console.warn(
+      'It is highly recommended to set `predictableActionArguments` to `true` when using `createMachine`. https://xstate.js.org/docs/guides/actions.html'
+    );
+  }
   return new StateNode(config, options as any) as any;
 }

packages/core/src/StateNode.ts

@@ -69,7 +69,8 @@ import {
   InternalMachineOptions,
   ServiceMap,
   StateConfig,
-  AnyStateMachine
+  AnyStateMachine,
+  PredictableActionArgumentsExec
 } from './types';
 import { matchesState } from './utils';
 import { State, stateValuesEqual } from './State';
@@ -1119,9 +1120,11 @@ class StateNode<
       | State<TContext, TEvent, any, TTypestate, TResolvedTypesMeta> = this
       .initialState,
     event: Event<TEvent> | SCXML.Event<TEvent>,
-    context?: TContext
+    context?: TContext,
+    exec?: PredictableActionArgumentsExec
   ): State<TContext, TEvent, TStateSchema, TTypestate, TResolvedTypesMeta> {
     const _event = toSCXMLEvent(event);
+
     let currentState: State<
       TContext,
       TEvent,
@@ -1185,6 +1188,7 @@ class StateNode<
       stateTransition,
       currentState,
       currentState.context,
+      exec,
       _event
     );
   }
@@ -1198,11 +1202,17 @@ class StateNode<
       TResolvedTypesMeta
     >,
     _event: SCXML.Event<TEvent> | NullEvent,
-    originalEvent: SCXML.Event<TEvent>
+    originalEvent: SCXML.Event<TEvent>,
+    predictableExec?: PredictableActionArgumentsExec
   ): State<TContext, TEvent, TStateSchema, TTypestate, TResolvedTypesMeta> {
     const currentActions = state.actions;
 
-    state = this.transition(state, _event as SCXML.Event<TEvent>);
+    state = this.transition(
+      state,
+      _event as SCXML.Event<TEvent>,
+      undefined,
+      predictableExec
+    );
     // Save original event to state
     // TODO: this should be the raised event! Delete in V5 (breaking)
     state._event = originalEvent;
@@ -1216,9 +1226,11 @@ class StateNode<
     stateTransition: StateTransition<TContext, TEvent>,
     currentState: State<TContext, TEvent, any, any, any> | undefined,
     context: TContext,
+    predictableExec?: PredictableActionArgumentsExec,
     _event: SCXML.Event<TEvent> = initEvent as SCXML.Event<TEvent>
   ): State<TContext, TEvent, TStateSchema, TTypestate, TResolvedTypesMeta> {
     const { configuration } = stateTransition;
+
     // Transition will "apply" if:
     // - this is the initial state (there is no current state)
     // - OR there are transitions
@@ -1268,7 +1280,9 @@ class StateNode<
       context,
       _event,
       actions,
-      this.machine.config.preserveActionOrder
+      predictableExec,
+      this.machine.config.predictableActionArguments ||
+        this.machine.config.preserveActionOrder
     );
 
     const [raisedEvents, nonRaisedActions] = partition(
@@ -1358,7 +1372,7 @@ class StateNode<
 
     // There are transient transitions if the machine is not in a final state
     // and if some of the state nodes have transient ("always") transitions.
-    const isTransient =
+    const hasAlwaysTransitions =
       !isDone &&
       (this._transient ||
         configuration.some((stateNode) => {
@@ -1370,24 +1384,27 @@ class StateNode<
     // because an transient transition should be triggered even if there are no
     // enabled transitions.
     //
-    // If we're already working on an transient transition (by checking
-    // if the event is a NULL_EVENT), then stop to prevent an infinite loop.
+    // If we're already working on an transient transition then stop to prevent an infinite loop.
     //
     // Otherwise, if there are no enabled nor transient transitions, we are done.
-    if (!willTransition && (!isTransient || _event.name === NULL_EVENT)) {
+    if (
+      !willTransition &&
+      (!hasAlwaysTransitions || _event.name === NULL_EVENT)
+    ) {
       return nextState;
     }
 
     let maybeNextState = nextState;
 
     if (!isDone) {
-      if (isTransient) {
+      if (hasAlwaysTransitions) {
         maybeNextState = this.resolveRaisedTransition(
           maybeNextState,
           {
             type: actionTypes.nullEvent
           },
-          _event
+          _event,
+          predictableExec
         );
       }
 
@@ -1396,7 +1413,8 @@ class StateNode<
         maybeNextState = this.resolveRaisedTransition(
           maybeNextState,
           raisedEvent._event,
-          _event
+          _event,
+          predictableExec
         );
       }
     }

packages/core/src/actions.ts

@@ -39,7 +39,8 @@ import {
   StopActionObject,
   Cast,
   EventFrom,
-  AnyActorRef
+  AnyActorRef,
+  PredictableActionArgumentsExec
 } from './types';
 import * as actionTypes from './actionTypes';
 import {
@@ -628,6 +629,7 @@ export function resolveActions<TContext, TEvent extends EventObject>(
   currentContext: TContext,
   _event: SCXML.Event<TEvent>,
   actions: Array<ActionObject<TContext, TEvent>>,
+  predictableExec?: PredictableActionArgumentsExec,
   preserveActionOrder: boolean = false
 ): [Array<ActionObject<TContext, TEvent>>, TContext] {
   const [assignActions, otherActions] = preserveActionOrder
@@ -650,15 +652,16 @@ export function resolveActions<TContext, TEvent extends EventObject>(
     otherActions
       .map((actionObject) => {
         switch (actionObject.type) {
-          case actionTypes.raise:
+          case actionTypes.raise: {
             return resolveRaise(actionObject as RaiseAction<TEvent>);
+          }
           case actionTypes.send:
             const sendAction = resolveSend(
               actionObject as SendAction<TContext, TEvent, AnyEventObject>,
               updatedContext,
               _event,
               machine.options.delays as any
-            ) as ActionObject<TContext, TEvent>; // TODO: fix ActionTypes.Init
+            ) as SendActionObject<TContext, TEvent>; // TODO: fix ActionTypes.Init
 
             if (!IS_PRODUCTION) {
               // warn after resolving as we can create better contextual message here
@@ -670,13 +673,20 @@ export function resolveActions<TContext, TEvent extends EventObject>(
               );
             }
 
+            if (sendAction.to !== SpecialTargets.Internal) {
+              predictableExec?.(sendAction, updatedContext, _event);
+            }
+
             return sendAction;
-          case actionTypes.log:
-            return resolveLog(
+          case actionTypes.log: {
+            const resolved = resolveLog(
               actionObject as LogAction<TContext, TEvent>,
               updatedContext,
               _event
             );
+            predictableExec?.(resolved, updatedContext, _event);
+            return resolved;
+          }
           case actionTypes.choose: {
             const chooseAction = actionObject as ChooseAction<TContext, TEvent>;
             const matchedActions = chooseAction.conds.find((condition) => {
@@ -691,7 +701,7 @@ export function resolveActions<TContext, TEvent extends EventObject>(
                   guard,
                   updatedContext,
                   _event,
-                  currentState as any
+                  (!predictableExec ? currentState : undefined) as any
                 )
               );
             })?.actions;
@@ -712,6 +722,7 @@ export function resolveActions<TContext, TEvent extends EventObject>(
                 toArray(matchedActions),
                 machine.options.actions as any
               ),
+              predictableExec,
               preserveActionOrder
             );
             updatedContext = resolvedContextFromChoose;
@@ -735,25 +746,28 @@ export function resolveActions<TContext, TEvent extends EventObject>(
                 toArray(matchedActions),
                 machine.options.actions as any
               ),
+              predictableExec,
               preserveActionOrder
             );
             updatedContext = resolvedContext;
             preservedContexts?.push(updatedContext);
             return resolvedActionsFromPure;
           }
           case actionTypes.stop: {
-            return resolveStop(
+            const resolved = resolveStop(
               actionObject as StopAction<TContext, TEvent>,
               updatedContext,
               _event
             );
+            predictableExec?.(resolved, updatedContext, _event);
+            return resolved;
           }
           case actionTypes.assign: {
             updatedContext = updateContext(
               updatedContext,
               _event,
               [actionObject as AssignAction<TContext, TEvent>],
-              currentState
+              !predictableExec ? currentState : undefined
             );
             preservedContexts?.push(updatedContext);
             break;
@@ -764,7 +778,9 @@ export function resolveActions<TContext, TEvent extends EventObject>(
               machine.options.actions as any
             );
             const { exec } = resolvedActionObject;
-            if (exec && preservedContexts) {
+            if (predictableExec) {
+              predictableExec(resolvedActionObject, updatedContext, _event);
+            } else if (exec && preservedContexts) {
               const contextIndex = preservedContexts.length - 1;
               resolvedActionObject = {
                 ...resolvedActionObject,