Are moves actually pure - or how are events actually handled?

[on3iro]

I am currently trying to wrap my head around moves.
The docs say I should build them in an immutable fashion (which I absolute prefer - so no issues with that at all), however I am also allowed to call ctx.events inside a move. I did not have the time to have a look inside the boardgame.io codebase, so I don't know how these are actually implemented, however from a users perspective these look a whole lot like side effects (and the docs unfortunately are not very specific about how events work).

The issues I have with this are twofold:

1. I usually prefer to circumvent Immers draft magic (in non-boardgame.io projects) and explicitely update my state manually. However because I can't directly divide my redux store into very granular slices and because of the event-sideffects actually returning values feels cumbersome and makes move readability even harder. I am also unsure if I am allowed to call an event directly before returning a value from a move.
2. I am not quite sure how I would go about testing a move which also triggers an event (which most of my games moves do). As far as I can see it, I have basically two options:
   a. I could unit test the move and mock the ctx.events-API
   b. I could write integration tests instead of unit tests for my moves (which feels weird, considering that the docs explicitly state that moves should be pure).

But maybe I just have a lot of misconceptions about how the events-API actually works.

If you explain it to me I could also contribute some new docs clarifying the API :)

Thanks in advance!

[delucis]

Question 1

A move should be pure in the sense that it should rely only on the state provided by its inputs. (It is also OK to rely on some immutable data in scope, but not something stateful that gets mutated.)

I’m not sure I would think of events as side effects exactly. Think of the full state object: { G, ctx, ... }. G is yours. You can do what you want with it. The rest of the state object — ctx, the undo/redo stack, etc. — is managed by boardgame.io and shouldn’t be touched directly. When you dispatch a move on the client, you are actually sending an action to a reducer that operates on this whole state, not just G. The framework would be unhelpful if you couldn’t also update the non-G state somehow. Events provide an imperative API for updating the state boardgame.io is responsible for from moves.

With an example move like this

function move(G, ctx, arg) {
  ctx.events.endTurn();
  G.arg = arg;
}

You can kind of think of this as dispatching two things to the reducer:

1. Mutate G using the code in move.
2. Run the endTurn event.

As per the docs:

Events are queued up and triggered after a move. Any changes you make to G will be applied before events are triggered, even if the event is called first in your move function.

So you can call events and know that the ctx you’re using in the move will remain the same — the events only get processed once your move is complete.

Question 2

This depends a bit what you want to test. If you want to test that a move that calls endTurn, increments ctx.turn, then you would need to use the client in the tests as described under Scenario Tests in the docs.

However if you want to test a move mutates G as expected, you could definitely just provide a mock ctx.effects API. It won’t make any difference to how the move runs in terms of operating on G. If I’m honest, I tend to find using the client in tests simplest, but either approach is viable.

[on3iro]

@delucis Ah, I somehow missed that part in the docs - sorry 😅 my bad.

Thanks for the super quick response and great explanation!