Include `stopChild` in the first argument of the assign function

[devanfarrell]

Details

Due to the way child actors need to be stopped in V5 with the stopChild action. There is a lot of pain surrounding stopping actors on the whole. Presently you can spawn an actor in assign with the spawn function and assign it to context but you can't both stop an actor and remove it from context in the same action in the same manner. This causes some serious pain points when you need to potentially stop multiple actors. In order to do so correctly you need to enqueue a bunch of actions. Below is an example of me trying to spawn and remove actors in the setup function. I haven't actually had any luck getting this working.

spawning n actors

addNActors: assign(({context, spawn}, actorArgs: input[] ) => {
 const actorMap = new Map(context.actorMap);
 actorArgs.forEach( input => actorMap.set(input.id, spawn(machine, {input}));
 return { actorMap };
 }

stopping n actors

 stopActor: stopChild((_, actor: CalloutFormActor) => actor),
    removeActor: assign(({ context }, id: UUID) => {
      const actorMap = new Map(context.actorMap);
      actorMap.delete(id);
      return { actorMap };
    }),
    // @ts-expect-error angry because it doesn't know what the possible actions are
    killActor: enqueueActions(({ enqueueActions, context }, id: UUID) => {
      const actor = context.actorMap.get(id);
      if (actor) {
        enqueueActions({ type: 'stopActor', params: actor });
        enqueueActions({ type: 'removeActor', params: id });
      }
    }),
    // @ts-expect-error angry because it doesn't know what the possible actions are
    killNActors: enqueueActions(({ enqueueActions }, ids: UUID[]) => {
      ids.forEach((id) => enqueueActions({ type: 'killActor', params: id }));
    }),

Proposed

It would be a lot cleaner if the pattern looked something more similar to spawn.

     killNActors: assign(({ context, stopChild }, ids: UUID[]) => {
      const actorMap = new Map(context.actorMap);
      ids.forEach((id) => {
          const actor = context.actorMap.get(id);
          if(actor) {
            context.actorMap.delete(id);
            stopChild(actor);
          }
      return { actorMap };
      })

Category

XState

[devanfarrell]

I realized there are more issues with the things I wrote. You can't actually pass a param to enqueue actions so I don't even think you can stop an actor and remove it from context without doing so imperatively. I did figure out you can enqueue an assign in place to assign and kill the child machine if I do so within the createMachine definition but I have to reuse this function 17 times in the code I'm trying to refactor so copying and pasting it that many times is kind of gross.

[Andarist]

To be fair, this isn't a v5 problem. This was always quirky/incoherent. Even if you were able to call child.stop() in assign... that wasn't the right thing to do. assign is really meant to be pure and .stop() is not.

I wonder - do you even need to keep those actors in context? We were wondering about soft-deprecating the spawn in assign. To do that we need to figure out some pieces around spawnChild/stopChild to make it fit more use cases. Do you imagine that could fix your problems? In my opinion, it's kinda quirky that you need to remove an actor from the context and stop it manually in the first place. So I don't exactly see stopChild being exposed to assign as a solution. It would be better if those things would just work automatically out of the box and if they could be treated as a single operation - to achieve that we'd have to recommend using spawnChild/stopChild alone since that would shift the responsibility of storing actors completely on us.

[devanfarrell]

I think that would cause a bunch of different problems. The nice part about having them in context is that we don't have to discriminate unions in typescript if we need to interact with an actor directly. On top of that I can easily communicate with context how the various actor instances are maintained, I might have a single instance of one type of actor upon initialization, another conditionally, and n of this other type of actor. If you have to discriminate those unions any time you interact with them in the client or the machine itself it's going to be really painful.

Imagine this scenario, I create a machine that schedules appointments. It spawns an actor that connects to my date picker component. In order to wire up those machines right now looks something like this.

const Scheduler = () => {
const [state, send] = useMachine(myMachine);
  return <><DatePicker actor={state.context.datePicker}/><>
}

If I had to do that imperatively I imagine my code would end up looking something like this. I would actually put isDatePickerActor in the machine file but this is for brevity.

import { DatePickerActor, DATE_PICKER_ID } from '@components/datePicker/DatePicker.machine.ts';

const isDatePickerActor = (actor: DatePickerActor | AnyActor | undefined): actor is DatePickerActor => 'id' in actor && actor.id === DATE_PICKER_ID;

const Scheduler = () => {
const [state, send] = useMachine(myMachine);
 const datePickerActor = state.children.get(DATE_PICKER_ID)
 if(!isDatePickerActor(datePickerActor)) throw new Error("DatePicker actor improperly connected");

  return <><DatePicker actor={datePickerActor}/><>
}

This is how we use actors all the time which is also why the previous behavior of useActor actually made a lot of sense for use. The scenario where you have actors that live for the duration of their parent actor, others that are conditionally spawned, and we actually have n number of a union of actor types on certain machines.

[devanfarrell]

The union of actor types does actually cause problems too. It causes issues with matches and can specifically. typescriptlang demo

[Andarist]

Ideally, you wouldn't need isDatePickerActor at all there. Its type should already be derived from whatever you have defined in the setup, see an example here

The union of actor types does actually cause problems too. It causes issues with matches and can specifically. typescriptlang demo

This is fixable, we just need to remove this type from those methods. Could you open an issue about this?

[devanfarrell]

Been playing around with the children property directly instead of using context. It doesn't seem to be too bad if you rely on typescript template strings. I think it does raise the barrier of entry slightly as far as typing goes but I can't really think of anything that couldn't be achieved with this pattern and template strings. Here is what I would consider a pretty heavy edge case where you needed to split all the book and news actors from our previous discussions. typescriptlang demo

[devanfarrell]

Are these typings intentional on children? It does make using useSelector kind of a pain types wise. You have to use layers of components in React since hooks can't be called conditionally. There is a benefit of using refs in this scenario because you can ensure an actor is spawned in context and explicitly communicate that the actor is always defined.

children: {
  news: 'news',
  book?: 'book
}
^ {news: NewsMachine | undefined, book: BookMachine | undefined}

[davidkpiano]

@devanfarrell You will soon be able to use maybe-undefined actors in useSelector(actor?): https://github.com/statelyai/xstate/pull/4231

That should make things a lot easier.

[AloraO]

In the context of programming, the directive to "include stopChild in the first argument of the assign function" suggests that you need to modify a function call to include a parameter named stopChild within its first argument.

The assign function is likely part of a specific programming language or framework, and it seems that you need to pass the stopChild parameter to this function. This parameter could be used to control or stop certain child processes or operations within the function.

[AloraO]

Here's an example of how you might modify the function call to include stopChild:

// Original function call assign(target, source);

// Modified function call with stopChild parameter included assign({ stopChild: true }, target, source);