[core] Enqueue all the things

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
 

packages/core/src/actions/spawnChild.ts

@@ -172,17 +172,18 @@ type SpawnArguments<
   TExpressionEvent extends EventObject,
   TEvent extends EventObject,
   TActor extends ProvidedActor
-> = IsLiteralString<TActor['src']> extends true
-  ? DistributeActors<TContext, TExpressionEvent, TEvent, TActor>
-  : [
-      src: string | AnyActorLogic,
-      options?: {
-        id?: ResolvableActorId<TContext, TExpressionEvent, TEvent, string>;
-        systemId?: string;
-        input?: unknown;
-        syncSnapshot?: boolean;
-      }
-    ];
+> =
+  IsLiteralString<TActor['src']> extends true
+    ? DistributeActors<TContext, TExpressionEvent, TEvent, TActor>
+    : [
+        src: string | AnyActorLogic,
+        options?: {
+          id?: ResolvableActorId<TContext, TExpressionEvent, TEvent, string>;
+          systemId?: string;
+          input?: unknown;
+          syncSnapshot?: boolean;
+        }
+      ];
 
 export function spawnChild<
   TContext extends MachineContext,

packages/core/src/actors/transition.ts

@@ -196,11 +196,7 @@ export function fromTransition<
     transition: (snapshot, event, actorScope) => {
       return {
         ...snapshot,
-        context: transition(
-          snapshot.context,
-          event,
-          actorScope as any
-        )
+        context: transition(snapshot.context, event, actorScope as any)
       };
     },
     getInitialSnapshot: (_, input) => {

packages/core/src/setup.ts

@@ -75,7 +75,7 @@ export function setup<
   TEvent extends AnyEventObject, // TODO: consider using a stricter `EventObject` here
   TActors extends Record<string, UnknownActorLogic> = {},
   TChildrenMap extends Record<string, string> = {},
-  TActions extends Record<
+  TActionParams extends Record<
     string,
     ParameterizedObject['params'] | undefined
   > = {},
@@ -115,13 +115,13 @@ export function setup<
       : never;
   };
   actions?: {
-    [K in keyof TActions]: ActionFunction<
+    [K in keyof TActionParams]: ActionFunction<
       TContext,
+      TEvent, // Expression event
       TEvent,
-      TEvent,
-      TActions[K],
+      TActionParams[K],
       ToProvidedActor<TChildrenMap, TActors>,
-      ToParameterizedObject<TActions>,
+      ToParameterizedObject<TActionParams>,
       ToParameterizedObject<TGuards>,
       TDelay,
       TEmitted
@@ -139,7 +139,7 @@ export function setup<
     [K in TDelay]: DelayConfig<
       TContext,
       TEvent,
-      ToParameterizedObject<TActions>['params'],
+      ToParameterizedObject<TActionParams>['params'],
       TEvent
     >;
   };
@@ -151,7 +151,7 @@ export function setup<
       TContext,
       TEvent,
       ToProvidedActor<TChildrenMap, TActors>,
-      ToParameterizedObject<TActions>,
+      ToParameterizedObject<TActionParams>,
       ToParameterizedObject<TGuards>,
       TDelay,
       TTag,
@@ -170,7 +170,7 @@ export function setup<
       Record<string, AnyActorRef | undefined>
     >,
     ToProvidedActor<TChildrenMap, TActors>,
-    ToParameterizedObject<TActions>,
+    ToParameterizedObject<TActionParams>,
     ToParameterizedObject<TGuards>,
     TDelay,
     ToStateValue<TConfig>,

packages/core/src/stateUtils.ts

@@ -1,7 +1,7 @@
 import isDevelopment from '#is-development';
 import { MachineSnapshot, cloneMachineSnapshot } from './State.ts';
 import type { StateNode } from './StateNode.ts';
-import { raise } from './actions.ts';
+import { assign, raise, sendTo } from './actions.ts';
 import { createAfterEvent, createDoneStateEvent } from './eventUtils.ts';
 import { cancel } from './actions/cancel.ts';
 import { spawnChild } from './actions/spawnChild.ts';
@@ -37,7 +37,9 @@
   ActionFunction,
   AnyTransitionConfig,
   ProvidedActor,
-  AnyActorScope
+  AnyActorScope,
+  ActionFunctionEnqueuer,
+  AnyActorRef
 } from './types.ts';
 import {
   resolveOutput,
@@ -1550,17 +1552,63 @@
           params: actionParams
         }
       });
+      const actions: UnknownAction[] = [];
+      const enq: ActionFunctionEnqueuer<
+        any,
+        any,
+        any,
+        any,
+        any,
+        any,
+        any,
+        any
+      > = {
+        assign: (...args) => {
+          actions.push(assign(...args) as UnknownAction);
+        },
+        action: (actionFn) => {
+          actions.push(actionFn);
+        },
+        raise: (...args) => {
+          actions.push(raise(...args) as UnknownAction);
+        },
+        sendTo: (...args) => {
+          actions.push(sendTo(...args) as UnknownAction);
+        },
+        check: (guard) =>
+          evaluateGuard(
+            guard,
+            intermediateSnapshot.context,
+            event,
+            intermediateSnapshot
+          )
+      };
       try {
         executingCustomAction = resolvedAction;
-        resolvedAction(actionArgs, actionParams);
+        resolvedAction(actionArgs, actionParams, enq);
       } finally {
         executingCustomAction = false;
       }
+
+      if (actions.length) {
+        intermediateSnapshot = resolveAndExecuteActionsWithContext(
+          intermediateSnapshot,
+          event,
+          actorScope,
+          actions,
+          extra,
+          retries
+        );
+
+        return intermediateSnapshot;
+      }
     }
 
     if (!('resolve' in resolvedAction)) {
       if (actorScope.self._processingStatus === ProcessingStatus.Running) {
         executeAction();
+      } else if (resolvedAction.length === 3) {
+        executeAction();
       } else {
         actorScope.defer(() => {
           executeAction();

packages/core/src/system.ts

@@ -161,8 +161,8 @@ export function createSystem<T extends ActorSystemInfo>(
       ...event,
       rootId: rootActor.sessionId
     };
-    inspectionObservers.forEach(
-      (observer) => observer.next?.(resolvedInspectionEvent)
+    inspectionObservers.forEach((observer) =>
+      observer.next?.(resolvedInspectionEvent)
     );
   };
 

packages/core/src/types.ts

@@ -1,13 +1,14 @@
 import type { MachineSnapshot } from './State.ts';
 import type { StateMachine } from './StateMachine.ts';
 import type { StateNode } from './StateNode.ts';
-import { AssignArgs } from './actions/assign.ts';
+import { AssignArgs, assign } from './actions/assign.ts';
 import { PromiseActorLogic } from './actors/promise.ts';
 import { Guard, GuardPredicate, UnknownGuard } from './guards.ts';
 import type { Actor, ProcessingStatus } from './createActor.ts';
 import { Spawner } from './spawn.ts';
 import { AnyActorSystem, Clock } from './system.js';
 import { InspectionEvent } from './inspection.ts';
+import type { raise, sendTo } from './actions.ts';
 
 export type Identity<T> = { [K in keyof T]: T[K] };
 
@@ -169,6 +170,57 @@
       ? (TSnapshot & { status: 'done' })['output']
       : never;
 
+export interface ActionFunctionEnqueuer<
+  TContext extends MachineContext,
+  TExpressionEvent extends EventObject,
+  TEvent extends EventObject,
+  TActor extends ProvidedActor,
+  TAction extends ParameterizedObject,
+  TGuard extends ParameterizedObject,
+  TDelay extends string,
+  TEmitted extends EventObject
+> {
+  assign: (
+    ...args: Parameters<
+      typeof assign<TContext, TExpressionEvent, any, TEvent, any>
+    >
+  ) => void;
+  raise: (
+    ...args: Parameters<
+      typeof raise<
+        TContext,
+        TExpressionEvent,
+        TEvent,
+        undefined,
+        TDelay,
+        TDelay
+      >
+    >
+  ) => void;
+  action: (
+    actionFn:
+      | NoRequiredParams<TAction>
+      | WithDynamicParams<TContext, TExpressionEvent, TAction>
+      | ((args: ActionArgs<TContext, TExpressionEvent, TEvent>) => void)
+  ) => void;
+  check: (
+    guard: Guard<TContext, TExpressionEvent, undefined, TGuard>
+  ) => boolean;
+  sendTo: <TTargetActor extends AnyActorRef>(
+    ...args: Parameters<
+      typeof sendTo<
+        TContext,
+        TExpressionEvent,
+        undefined,
+        TTargetActor,
+        TEvent,
+        TDelay,
+        TDelay
+      >
+    >
+  ) => void;
+}
+
 export type ActionFunction<
   TContext extends MachineContext,
   TExpressionEvent extends EventObject,
@@ -180,7 +232,20 @@
   TDelay extends string,
   TEmitted extends EventObject
 > = {
-  (args: ActionArgs<TContext, TExpressionEvent, TEvent>, params: TParams): void;
+  (
+    args: ActionArgs<TContext, TExpressionEvent, TEvent>,
+    params: TParams,
+    enqueue: ActionFunctionEnqueuer<
+      TContext,
+      TExpressionEvent,
+      TEvent,
+      TActor,
+      TAction,
+      TGuard,
+      TDelay,
+      TEmitted
+    >
+  ): void;
   _out_TEvent?: TEvent; // TODO: it feels like we should be able to remove this since now `TEvent` is "observable" by `self`
   _out_TActor?: TActor;
   _out_TAction?: TAction;