[core] Transition function

.changeset/lemon-needles-play.md

@@ -0,0 +1,23 @@
+---
+'xstate': minor
+---
+
+Added a new `transition` function that takes an actor logic, a snapshot, and an event, and returns a tuple containing the next snapshot and the actions to execute. This function is a pure function and does not execute the actions itself. It can be used like this:
+
+```ts
+import { transition } from 'xstate';
+
+const [nextState, actions] = transition(actorLogic, currentState, event);
+// Execute actions as needed
+```
+
+Added a new `initialTransition` function that takes an actor logic and an optional input, and returns a tuple containing the initial snapshot and the actions to execute from the initial transition. This function is also a pure function and does not execute the actions itself. It can be used like this:
+
+```ts
+import { initialTransition } from 'xstate';
+
+const [initialState, actions] = initialTransition(actorLogic, input);
+// Execute actions as needed
+```
+
+These new functions provide a way to separate the calculation of the next snapshot and actions from the execution of those actions, allowing for more control and flexibility in the transition process.

.vscode/launch.json

@@ -11,7 +11,7 @@
       "console": "integratedTerminal",
       "internalConsoleOptions": "neverOpen",
       "windows": {
-        "program": "${workspaceFolder}/node_modules/jest/bin/jest"
+        "program": "${workspaceFolder}/node_modules/jest/bin/jest.js"
       }
     },
     {
@@ -30,7 +30,7 @@
       "console": "integratedTerminal",
       "internalConsoleOptions": "neverOpen",
       "windows": {
-        "program": "${workspaceFolder}/node_modules/jest/bin/jest"
+        "program": "${workspaceFolder}/node_modules/jest/bin/jest.js"
       }
     }
   ]

README.md

@@ -181,16 +181,16 @@ Read [📽 the slides](http://slides.com/davidkhourshid/finite-state-machines) (
 
 ## Packages
 
-| Package                                                                                       | Description                                                                  |
-| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| 🤖 `xstate`                                                                                   | Core finite state machine and statecharts library + interpreter              |
-| [📉 `@xstate/graph`](https://github.com/statelyai/xstate/tree/main/packages/xstate-graph)     | Graph traversal and model-based testing utilities using XState               |
-| [⚛️ `@xstate/react`](https://github.com/statelyai/xstate/tree/main/packages/xstate-react)     | React hooks and utilities for using XState in React applications             |
-| [💚 `@xstate/vue`](https://github.com/statelyai/xstate/tree/main/packages/xstate-vue)         | Vue composition functions and utilities for using XState in Vue applications |
-| [🎷 `@xstate/svelte`](https://github.com/statelyai/xstate/tree/main/packages/xstate-svelte)   | Svelte utilities for using XState in Svelte applications                     |
-| [🥏 `@xstate/solid`](https://github.com/statelyai/xstate/tree/main/packages/xstate-solid)     | Solid hooks and utilities for using XState in Solid applications             |
-| [🔍 `@statelyai/inspect`](https://github.com/statelyai/inspect) | Inspection utilities for XState                                              |
-| [🏪 `@xstate/store`](https://github.com/statelyai/xstate/tree/main/packages/xstate-store) | Small library for simple state management |
+| Package                                                                                     | Description                                                                  |
+| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| 🤖 `xstate`                                                                                 | Core finite state machine and statecharts library + interpreter              |
+| [📉 `@xstate/graph`](https://github.com/statelyai/xstate/tree/main/packages/xstate-graph)   | Graph traversal and model-based testing utilities using XState               |
+| [⚛️ `@xstate/react`](https://github.com/statelyai/xstate/tree/main/packages/xstate-react)   | React hooks and utilities for using XState in React applications             |
+| [💚 `@xstate/vue`](https://github.com/statelyai/xstate/tree/main/packages/xstate-vue)       | Vue composition functions and utilities for using XState in Vue applications |
+| [🎷 `@xstate/svelte`](https://github.com/statelyai/xstate/tree/main/packages/xstate-svelte) | Svelte utilities for using XState in Svelte applications                     |
+| [🥏 `@xstate/solid`](https://github.com/statelyai/xstate/tree/main/packages/xstate-solid)   | Solid hooks and utilities for using XState in Solid applications             |
+| [🔍 `@statelyai/inspect`](https://github.com/statelyai/inspect)                             | Inspection utilities for XState                                              |
+| [🏪 `@xstate/store`](https://github.com/statelyai/xstate/tree/main/packages/xstate-store)   | Small library for simple state management                                    |
 
 ## Finite State Machines
 

jest.config.js

@@ -3,7 +3,7 @@ const { constants } = require('jest-config');
 /** @type {import('@jest/types').Config.InitialOptions} */
 module.exports = {
   prettierPath: null,
-  setupFilesAfterEnv: ['@xstate-repo/jest-utils/setup'],
+  setupFilesAfterEnv: ['<rootDir>/scripts/jest-utils/setup'],
   transform: {
     [constants.DEFAULT_JS_PATTERN]: 'babel-jest',
     '^.+\\.vue$': '@vue/vue3-jest',

packages/core/src/StateMachine.ts

@@ -9,6 +9,7 @@ import {
 } from './State.ts';
 import { StateNode } from './StateNode.ts';
 import {
+  executeAction,
   getAllStateNodes,
   getInitialStateNodes,
   getStateNodeByPath,
@@ -46,9 +47,11 @@ import type {
   StateMachineDefinition,
   StateValue,
   TransitionDefinition,
+  UnknownActionObject,
   ResolvedStateMachineTypes,
   StateSchema,
-  SnapshotStatus
+  SnapshotStatus,
+  ExecutableActionObject
 } from './types.ts';
 import { resolveReferencedActor, toStatePath } from './utils.ts';
 
@@ -293,7 +296,8 @@ export class StateMachine<
     TMeta,
     TConfig
   > {
-    return macrostep(snapshot, event, actorScope).snapshot as typeof snapshot;
+    return macrostep(snapshot, event, actorScope, [])
+      .snapshot as typeof snapshot;
   }
 
   /**
@@ -328,7 +332,7 @@ export class StateMachine<
       TConfig
     >
   > {
-    return macrostep(snapshot, event, actorScope).microstates;
+    return macrostep(snapshot, event, actorScope, []).microstates;
   }
 
   public getTransitionData(
@@ -385,8 +389,9 @@ export class StateMachine<
         preInitial,
         initEvent,
         actorScope,
-        [assign(assignment)],
-        internalQueue
+        [assign(assignment) as unknown as UnknownActionObject],
+        internalQueue,
+        undefined
       ) as SnapshotFrom<this>;
     }
 
@@ -629,4 +634,8 @@ export class StateMachine<
 
     return restoredSnapshot;
   }
+
+  public executeAction(action: ExecutableActionObject, actor?: AnyActorRef) {
+    return executeAction(action, actor);
+  }
 }

packages/core/src/StateNode.ts

@@ -4,6 +4,7 @@ import { NULL_EVENT, STATE_DELIMITER } from './constants.ts';
 import { evaluateGuard } from './guards.ts';
 import { memo } from './memo.ts';
 import {
+  convertAction,
   formatInitialTransition,
   formatTransition,
   formatTransitions,
@@ -30,7 +31,8 @@ import type {
   AnyStateNodeConfig,
   ProvidedActor,
   NonReducibleUnknown,
-  EventDescriptor
+  EventDescriptor,
+  UnknownActionObject
 } from './types.ts';
 import {
   createInvokeId,
@@ -41,21 +43,6 @@ import {
 
 const EMPTY_OBJECT = {};
 
-const toSerializableAction = (action: UnknownAction) => {
-  if (typeof action === 'string') {
-    return { type: action };
-  }
-  if (typeof action === 'function') {
-    if ('resolve' in action) {
-      return { type: (action as any).type };
-    }
-    return {
-      type: action.name
-    };
-  }
-  return action;
-};
-
 interface StateNodeOptions<
   TContext extends MachineContext,
   TEvent extends EventObject
@@ -98,9 +85,9 @@ export class StateNode<
    */
   public history: false | 'shallow' | 'deep';
   /** The action(s) to be executed upon entering the state node. */
-  public entry: UnknownAction[];
+  public entry: UnknownActionObject[];
   /** The action(s) to be executed upon exiting the state node. */
-  public exit: UnknownAction[];
+  public exit: UnknownActionObject[];
   /** The parent state node. */
   public parent?: StateNode<TContext, TEvent>;
   /** The root machine node. */
@@ -209,8 +196,32 @@ export class StateNode<
     this.history =
       this.config.history === true ? 'shallow' : this.config.history || false;
 
-    this.entry = toArray(this.config.entry).slice();
-    this.exit = toArray(this.config.exit).slice();
+    this.entry = toArray(this.config.entry as UnknownAction).map(
+      (action, actionIndex) => {
+        const actionObject = convertAction(
+          action,
+          this,
+          undefined,
+          'entry',
+          0,
+          actionIndex
+        );
+        return actionObject;
+      }
+    );
+    this.exit = toArray(this.config.exit as UnknownAction).map(
+      (action, actionIndex) => {
+        const actionObject = convertAction(
+          action,
+          this,
+          undefined,
+          'exit',
+          0,
+          actionIndex
+        );
+        return actionObject;
+      }
+    );
 
     this.meta = this.config.meta;
     this.output =
@@ -222,8 +233,8 @@ export class StateNode<
   public _initialize() {
     this.transitions = formatTransitions(this);
     if (this.config.always) {
-      this.always = toTransitionConfigArray(this.config.always).map((t) =>
-        formatTransition(this, NULL_EVENT, t)
+      this.always = toTransitionConfigArray(this.config.always).map((t, i) =>
+        formatTransition(this, NULL_EVENT, t, i)
       );
     }
 
@@ -243,13 +254,13 @@ export class StateNode<
         ? {
             target: this.initial.target,
             source: this,
-            actions: this.initial.actions.map(toSerializableAction),
+            actions: this.initial.actions,
             eventType: null as any,
             reenter: false,
             toJSON: () => ({
               target: this.initial.target.map((t) => `#${t.id}`),
               source: `#${this.id}`,
-              actions: this.initial.actions.map(toSerializableAction),
+              actions: this.initial.actions,
               eventType: null as any
             })
           }
@@ -261,10 +272,10 @@ export class StateNode<
       on: this.on,
       transitions: [...this.transitions.values()].flat().map((t) => ({
         ...t,
-        actions: t.actions.map(toSerializableAction)
+        actions: t.actions
       })),
-      entry: this.entry.map(toSerializableAction),
-      exit: this.exit.map(toSerializableAction),
+      entry: this.entry,
+      exit: this.exit,
       meta: this.meta,
       order: this.order || -1,
       output: this.output,
@@ -296,21 +307,25 @@ export class StateNode<
       toArray(this.config.invoke).map((invokeConfig, i) => {
         const { src, systemId } = invokeConfig;
         const resolvedId = invokeConfig.id ?? createInvokeId(this.id, i);
-        const resolvedSrc =
+        const sourceName =
           typeof src === 'string'
             ? src
             : `xstate.invoke.${createInvokeId(this.id, i)}`;
+        if (typeof src !== 'string') {
+          this.machine.implementations.actors[sourceName] = src;
+        }
+
         return {
           ...invokeConfig,
-          src: resolvedSrc,
+          src: sourceName,
           id: resolvedId,
           systemId: systemId,
           toJSON() {
             const { onDone, onError, ...invokeDefValues } = invokeConfig;
             return {
               ...invokeDefValues,
               type: 'xstate.invoke',
-              src: resolvedSrc,
+              src: sourceName,
               id: resolvedId
             };
           }
@@ -375,7 +390,7 @@ export class StateNode<
     event: TEvent
   ): TransitionDefinition<TContext, TEvent>[] | undefined {
     const eventType = event.type;
-    const actions: UnknownAction[] = [];
+    const actions: UnknownActionObject[] = [];
 
     let selectedTransition: TransitionDefinition<TContext, TEvent> | undefined;
 

packages/core/src/actions/assign.ts

@@ -1,7 +1,7 @@
 import isDevelopment from '#is-development';
 import { cloneMachineSnapshot } from '../State.ts';
+import { executingCustomAction } from '../createActor.ts';
 import { Spawner, createSpawner } from '../spawn.ts';
-import { executingCustomAction } from '../stateUtils.ts';
 import type {
   ActionArgs,
   AnyActorScope,
@@ -179,5 +179,9 @@ export function assign<
 
   assign.resolve = resolveAssign;
 
+  assign.toJSON = () => ({
+    ...assign
+  });
+
   return assign;
 }

packages/core/src/actions/cancel.ts

@@ -33,9 +33,7 @@ function resolveCancel(
 }
 
 function executeCancel(actorScope: AnyActorScope, resolvedSendId: string) {
-  actorScope.defer(() => {
-    actorScope.system.scheduler.cancel(actorScope.self, resolvedSendId);
-  });
+  actorScope.system.scheduler.cancel(actorScope.self, resolvedSendId);
 }
 
 export interface CancelAction<
@@ -102,5 +100,9 @@ export function cancel<
   cancel.resolve = resolveCancel;
   cancel.execute = executeCancel;
 
+  cancel.toJSON = () => ({
+    ...cancel
+  });
+
   return cancel;
 }

packages/core/src/actions/emit.ts

@@ -1,5 +1,5 @@
 import isDevelopment from '#is-development';
-import { executingCustomAction } from '../stateUtils.ts';
+import { executingCustomAction } from '../createActor.ts';
 import {
   ActionArgs,
   ActionFunction,
@@ -146,5 +146,9 @@ export function emit<
   emit.resolve = resolveEmit;
   emit.execute = executeEmit;
 
+  emit.toJSON = () => ({
+    ...emit
+  });
+
   return emit;
 }

packages/core/src/actions/enqueueActions.ts

@@ -1,5 +1,6 @@
 import isDevelopment from '#is-development';
 import { Guard, evaluateGuard } from '../guards.ts';
+import { convertAction } from '../stateUtils.ts';
 import {
   Action,
   ActionArgs,
@@ -135,7 +136,16 @@ function resolveEnqueueActions(
   const enqueue: Parameters<typeof collect>[0]['enqueue'] = function enqueue(
     action
   ) {
-    actions.push(action);
+    actions.push(
+      convertAction(
+        action as any,
+        snapshot.machine.root,
+        'enqueue' + Math.random(), // TODO: this should come from state node ID which isn't provided
+        undefined,
+        0,
+        actions.length
+      )
+    );
   };
   enqueue.assign = (...args) => {
     actions.push(assign(...args));
@@ -323,5 +333,9 @@ export function enqueueActions<
   enqueueActions.collect = collect;
   enqueueActions.resolve = resolveEnqueueActions;
 
+  enqueueActions.toJSON = () => ({
+    ...enqueueActions
+  });
+
   return enqueueActions;
 }