Add state transformer

[GabrielCTroia]

What/Why

Sometimes the Master (server) State needs to change based on something else than a client Action dispatch, such as time, or an external event.

Normally, on an in-house server, this would be handled by CRON jobs or by other event listeners, but since Movex abstracts the server away and to keep things as simple as possible, I chose the idea of the state being transformed on read – enter the $transformState().

What this means, is that the state doesn't change unless it's read, which is when the stateTransformer gets involved.

What is a $stateTransformer

A state transformer is a simple function of following type, and can be attached to any MovexReducer.

$transformState?: (state: S, context: MovexMasterContext) => S;

It gets called every time the reducer runs, meaning on each Action Dispatch or on each MovexResource.get() or even via the Movex API.

If you notice it takes a secondary argument masterContext, that looks like this:

export type MovexMasterContext = {
  requestAt: number; // timestamp
};

The MovexMasterContext provides a way to access the context of the Movex Master (Server) while keeping things pure in the reducer.

Keep in mind that context.requestAt will always return a new timestamp per request, which means that the requestAt value changes only on new requests, but not if it's called multiple times during the same event by Movex internally, to ensure the accuracy of the transformed state just as in a pure function.

Example

// See libs/movex-specs-util/src/lib/resources/speedPushGame.ts

speedPushGameReducer.$transformState = (state: State, context) => {
  const NOW = context.requestAt;

  if (
    state.status === 'ongoing' &&
    NOW > state.lastPushAt + state.timeToNextPushMs
  ) {
    return {
      status: 'completed',
      winner: state.lastPushBy,
      lastPushAt: state.lastPushAt,
      lastPushBy: state.lastPushBy,
      timeToNextPushMs: state.timeToNextPushMs,
    };
  }

  return state;
};

In this example above, the logic checks wether enough time has passed since last action and change the status of the game state if so. Take a look at the full example here libs/movex-specs-util/src/lib/resources/speedPushGame.ts.