Support for parameterized enqueueActions (statelyai#4777)

* Support for parameterized `enqueueActions`

* add missing context

.changeset/tasty-walls-heal.md

@@ -0,0 +1,5 @@
+---
+'xstate': minor
+---
+
+Added support for `params` to `enqueueActions`

packages/core/src/actions/enqueueActions.ts

@@ -92,13 +92,14 @@ function resolveEnqueueActions(
   actorScope: AnyActorScope,
   snapshot: AnyMachineSnapshot,
   args: ActionArgs<any, any, any>,
-  _actionParams: ParameterizedObject['params'] | undefined,
+  actionParams: ParameterizedObject['params'] | undefined,
   {
     collect
   }: {
     collect: CollectActions<
       MachineContext,
       EventObject,
+      ParameterizedObject['params'] | undefined,
       EventObject,
       ProvidedActor,
       ParameterizedObject,
@@ -136,29 +137,33 @@ function resolveEnqueueActions(
     actions.push(stopChild(...args));
   };
 
-  collect({
-    context: args.context,
-    event: args.event,
-    enqueue,
-    check: (guard) =>
-      evaluateGuard(guard, snapshot.context, args.event, snapshot),
-    self: actorScope.self,
-    system: actorScope.system
-  });
+  collect(
+    {
+      context: args.context,
+      event: args.event,
+      enqueue,
+      check: (guard) =>
+        evaluateGuard(guard, snapshot.context, args.event, snapshot),
+      self: actorScope.self,
+      system: actorScope.system
+    },
+    actionParams
+  );
 
   return [snapshot, undefined, actions];
 }
 
 export interface EnqueueActionsAction<
   TContext extends MachineContext,
   TExpressionEvent extends EventObject,
+  TParams extends ParameterizedObject['params'] | undefined,
   TEvent extends EventObject,
   TActor extends ProvidedActor,
   TAction extends ParameterizedObject,
   TGuard extends ParameterizedObject,
   TDelay extends string
 > {
-  (args: ActionArgs<TContext, TExpressionEvent, TEvent>, params: unknown): void;
+  (args: ActionArgs<TContext, TExpressionEvent, TEvent>, params: TParams): void;
   _out_TEvent?: TEvent;
   _out_TActor?: TActor;
   _out_TAction?: TAction;
@@ -192,26 +197,30 @@ interface CollectActionsArg<
 type CollectActions<
   TContext extends MachineContext,
   TExpressionEvent extends EventObject,
+  TParams extends ParameterizedObject['params'] | undefined,
   TEvent extends EventObject,
   TActor extends ProvidedActor,
   TAction extends ParameterizedObject,
   TGuard extends ParameterizedObject,
   TDelay extends string
-> = ({
-  context,
-  event,
-  check,
-  enqueue,
-  self
-}: CollectActionsArg<
-  TContext,
-  TExpressionEvent,
-  TEvent,
-  TActor,
-  TAction,
-  TGuard,
-  TDelay
->) => void;
+> = (
+  {
+    context,
+    event,
+    check,
+    enqueue,
+    self
+  }: CollectActionsArg<
+    TContext,
+    TExpressionEvent,
+    TEvent,
+    TActor,
+    TAction,
+    TGuard,
+    TDelay
+  >,
+  params: TParams
+) => void;
 
 /**
  * Creates an action object that will execute actions that are queued by the `enqueue(action)` function.
@@ -236,6 +245,7 @@ type CollectActions<
 export function enqueueActions<
   TContext extends MachineContext,
   TExpressionEvent extends EventObject,
+  TParams extends ParameterizedObject['params'] | undefined,
   TEvent extends EventObject = TExpressionEvent,
   TActor extends ProvidedActor = ProvidedActor,
   TAction extends ParameterizedObject = ParameterizedObject,
@@ -245,6 +255,7 @@ export function enqueueActions<
   collect: CollectActions<
     TContext,
     TExpressionEvent,
+    TParams,
     TEvent,
     TActor,
     TAction,
@@ -255,7 +266,7 @@ export function enqueueActions<
   TContext,
   TExpressionEvent,
   TEvent,
-  unknown,
+  TParams,
   TActor,
   TAction,
   TGuard,

packages/core/test/actions.test.ts

@@ -13,10 +13,12 @@ import {
   ActorRef,
   ActorRefFrom,
   EventObject,
+  Snapshot,
   assign,
   createActor,
   createMachine,
-  forwardTo
+  forwardTo,
+  setup
 } from '../src/index.ts';
 import { trackEntries } from './utils.ts';
 
@@ -2807,6 +2809,7 @@ describe('enqueueActions', () => {
       ]
     `);
   });
+
   it('should provide self', () => {
     expect.assertions(1);
     const machine = createMachine({
@@ -2817,6 +2820,66 @@ describe('enqueueActions', () => {
 
     createActor(machine).start();
   });
+
+  it('should be able to communicate with the parent using params', () => {
+    type ParentEvent = { type: 'FOO' };
+
+    const childMachine = setup({
+      types: {} as {
+        input: {
+          parent?: ActorRef<Snapshot<unknown>, ParentEvent>;
+        };
+        context: {
+          parent?: ActorRef<Snapshot<unknown>, ParentEvent>;
+        };
+      },
+      actions: {
+        mySendParent: enqueueActions(
+          ({ context, enqueue }, event: ParentEvent) => {
+            if (!context.parent) {
+              // it's here just for illustration purposes
+              console.log(
+                'WARN: an attempt to send an event to a non-existent parent'
+              );
+              return;
+            }
+            enqueue.sendTo(context.parent, event);
+          }
+        )
+      }
+    }).createMachine({
+      context: ({ input }) => ({ parent: input.parent }),
+      entry: {
+        type: 'mySendParent',
+        params: {
+          type: 'FOO'
+        }
+      }
+    });
+
+    const spy = jest.fn();
+
+    const parentMachine = setup({
+      types: {} as { events: ParentEvent },
+      actors: {
+        child: childMachine
+      }
+    }).createMachine({
+      on: {
+        FOO: {
+          actions: spy
+        }
+      },
+      invoke: {
+        src: 'child',
+        input: ({ self }) => ({ parent: self })
+      }
+    });
+
+    const actorRef = createActor(parentMachine).start();
+
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
 });
 
 describe('sendParent', () => {

packages/core/test/setup.types.test.ts

@@ -2017,6 +2017,70 @@ describe('setup()', () => {
     });
   });
 
+  it('should be able to use a parameterized `enqueueActions` action with its required params in the machine', () => {
+    setup({
+      actions: {
+        doStuff: enqueueActions((_, params: number) => {})
+      }
+    }).createMachine({
+      entry: {
+        type: 'doStuff',
+        params: 0
+      }
+    });
+  });
+
+  it('should not accept a string reference to parameterized `enqueueActions` without its required params in the machine', () => {
+    setup({
+      actions: {
+        doStuff: enqueueActions((_, params: number) => {})
+      }
+    }).createMachine({
+      // @ts-expect-error
+      entry: 'doStuff'
+    });
+  });
+
+  it('should not accept an object reference to parameterized `enqueueActions` without its required params in the machine', () => {
+    setup({
+      actions: {
+        doStuff: enqueueActions((_, params: number) => {})
+      }
+    }).createMachine({
+      // @ts-expect-error
+      entry: {
+        type: 'doStuff'
+      }
+    });
+  });
+
+  it('should not accept an object reference to parameterized `enqueueActions` without its required params in the machine', () => {
+    setup({
+      actions: {
+        doStuff: enqueueActions((_, params: number) => {})
+      }
+    }).createMachine({
+      // @ts-expect-error
+      entry: {
+        type: 'doStuff'
+      }
+    });
+  });
+
+  it('should not accept a reference to parameterized `enqueueActions` with wrong params in the machine', () => {
+    setup({
+      actions: {
+        doStuff: enqueueActions((_, params: number) => {})
+      }
+    }).createMachine({
+      // @ts-expect-error
+      entry: {
+        type: 'doStuff',
+        params: 'foo'
+      }
+    });
+  });
+
   it('should allow `cancel` action to be configured', () => {
     setup({
       actions: {