@mnbroatch/boardgame.io 0.0.1

package/src/plugins/events/events.ts

@@ -0,0 +1,209 @@
+/*
+ * Copyright 2018 The boardgame.io Authors
+ *
+ * Use of this source code is governed by a MIT-style
+ * license that can be found in the LICENSE file or at
+ * https://opensource.org/licenses/MIT.
+ */
+
+import type { State, Ctx, PlayerID, Game, ActivePlayersArg } from '../../types';
+import { automaticGameEvent } from '../../core/action-creators';
+import { GameMethod } from '../../core/game-methods';
+
+enum Errors {
+  CalledOutsideHook = 'Events must be called from moves or the `onBegin`, `onEnd`, and `onMove` hooks.\n' +
+    'This error probably means you called an event from other game code, like an `endIf` trigger or one of the `turn.order` methods.',
+
+  EndTurnInOnEnd = '`endTurn` is disallowed in `onEnd` hooks — the turn is already ending.',
+
+  MaxTurnEndings = 'Maximum number of turn endings exceeded for this update.\n' +
+    'This likely means game code is triggering an infinite loop.',
+
+  PhaseEventInOnEnd = '`setPhase` & `endPhase` are disallowed in a phase’s `onEnd` hook — the phase is already ending.\n' +
+    'If you’re trying to dynamically choose the next phase when a phase ends, use the phase’s `next` trigger.',
+
+  StageEventInOnEnd = '`setStage`, `endStage` & `setActivePlayers` are disallowed in `onEnd` hooks.',
+
+  StageEventInPhaseBegin = '`setStage`, `endStage` & `setActivePlayers` are disallowed in a phase’s `onBegin` hook.\n' +
+    'Use `setActivePlayers` in a `turn.onBegin` hook or declare stages with `turn.activePlayers` instead.',
+
+  StageEventInTurnBegin = '`setStage` & `endStage` are disallowed in `turn.onBegin`.\n' +
+    'Use `setActivePlayers` or declare stages with `turn.activePlayers` instead.',
+}
+
+export interface EventsAPI {
+  endGame(gameover?: any): void;
+  endPhase(): void;
+  endStage(): void;
+  endTurn(arg?: { next: PlayerID }): void;
+  pass(arg?: { remove: true }): void;
+  setActivePlayers(arg: ActivePlayersArg): void;
+  setPhase(newPhase: string): void;
+  setStage(newStage: string): void;
+}
+
+export interface PrivateEventsAPI {
+  _private: {
+    isUsed(): boolean;
+    updateTurnContext(ctx: Ctx, methodType: GameMethod | undefined): void;
+    unsetCurrentMethod(): void;
+    update(state: State): State;
+  };
+}
+
+/**
+ * Events
+ */
+export class Events {
+  flow: Game['flow'];
+  playerID: PlayerID | undefined;
+  dispatch: Array<{
+    type: string;
+    args: any[];
+    phase: string;
+    turn: number;
+    calledFrom: GameMethod | undefined;
+    error: Error;
+  }>;
+  maxEndedTurnsPerAction: number;
+  initialTurn: number;
+  currentPhase: string;
+  currentTurn: number;
+  currentMethod?: GameMethod;
+
+  constructor(flow: Game['flow'], ctx: Ctx, playerID?: PlayerID) {
+    this.flow = flow;
+    this.playerID = playerID;
+    this.dispatch = [];
+    this.initialTurn = ctx.turn;
+    this.updateTurnContext(ctx, undefined);
+    // This is an arbitrarily large upper threshold, which could be made
+    // configurable via a game option if the need arises.
+    this.maxEndedTurnsPerAction = ctx.numPlayers * 100;
+  }
+
+  api() {
+    const events = {
+      _private: this,
+    } as unknown as EventsAPI & PrivateEventsAPI;
+    for (const type of this.flow.eventNames) {
+      events[type] = (...args: any[]) => {
+        this.dispatch.push({
+          type,
+          args,
+          phase: this.currentPhase,
+          turn: this.currentTurn,
+          calledFrom: this.currentMethod,
+          // Used to capture a stack trace in case it is needed later.
+          error: new Error('Events Plugin Error'),
+        });
+      };
+    }
+
+    return events;
+  }
+
+  isUsed() {
+    return this.dispatch.length > 0;
+  }
+
+  updateTurnContext(ctx: Ctx, methodType: GameMethod | undefined) {
+    this.currentPhase = ctx.phase;
+    this.currentTurn = ctx.turn;
+    this.currentMethod = methodType;
+  }
+
+  unsetCurrentMethod() {
+    this.currentMethod = undefined;
+  }
+
+  /**
+   * Updates ctx with the triggered events.
+   * @param {object} state - The state object { G, ctx }.
+   */
+  update(state: State): State {
+    const initialState = state;
+    const stateWithError = ({ stack }: Error, message: Errors) => ({
+      ...initialState,
+      plugins: {
+        ...initialState.plugins,
+        events: {
+          ...initialState.plugins.events,
+          data: { error: message + '\n' + stack },
+        },
+      },
+    });
+
+    EventQueue: for (let i = 0; i < this.dispatch.length; i++) {
+      const event = this.dispatch[i];
+      const turnHasEnded = event.turn !== state.ctx.turn;
+
+      // This protects against potential infinite loops if specific events are called on hooks.
+      // The moment we exceed the defined threshold, we just bail out of all phases.
+      const endedTurns = this.currentTurn - this.initialTurn;
+      if (endedTurns >= this.maxEndedTurnsPerAction) {
+        return stateWithError(event.error, Errors.MaxTurnEndings);
+      }
+
+      if (event.calledFrom === undefined) {
+        return stateWithError(event.error, Errors.CalledOutsideHook);
+      }
+
+      // Stop processing events once the game has finished.
+      if (state.ctx.gameover) break EventQueue;
+
+      switch (event.type) {
+        case 'endStage':
+        case 'setStage':
+        case 'setActivePlayers': {
+          switch (event.calledFrom) {
+            // Disallow all stage events in onEnd and phase.onBegin hooks.
+            case GameMethod.TURN_ON_END:
+            case GameMethod.PHASE_ON_END:
+              return stateWithError(event.error, Errors.StageEventInOnEnd);
+            case GameMethod.PHASE_ON_BEGIN:
+              return stateWithError(event.error, Errors.StageEventInPhaseBegin);
+            // Disallow setStage & endStage in turn.onBegin hooks.
+            case GameMethod.TURN_ON_BEGIN:
+              if (event.type === 'setActivePlayers') break;
+              return stateWithError(event.error, Errors.StageEventInTurnBegin);
+          }
+
+          // If the turn already ended, don't try to process stage events.
+          if (turnHasEnded) continue EventQueue;
+          break;
+        }
+
+        case 'endTurn': {
+          if (
+            event.calledFrom === GameMethod.TURN_ON_END ||
+            event.calledFrom === GameMethod.PHASE_ON_END
+          ) {
+            return stateWithError(event.error, Errors.EndTurnInOnEnd);
+          }
+
+          // If the turn already ended some other way,
+          // don't try to end the turn again.
+          if (turnHasEnded) continue EventQueue;
+          break;
+        }
+
+        case 'endPhase':
+        case 'setPhase': {
+          if (event.calledFrom === GameMethod.PHASE_ON_END) {
+            return stateWithError(event.error, Errors.PhaseEventInOnEnd);
+          }
+
+          // If the phase already ended some other way,
+          // don't try to end the phase again.
+          if (event.phase !== state.ctx.phase) continue EventQueue;
+          break;
+        }
+      }
+
+      const action = automaticGameEvent(event.type, event.args, this.playerID);
+      state = this.flow.processEvent(state, action);
+    }
+    return state;
+  }
+}

package/src/plugins/main.test.ts

@@ -0,0 +1,411 @@
+/*
+ * Copyright 2019 The boardgame.io Authors
+ *
+ * Use of this source code is governed by a MIT-style
+ * license that can be found in the LICENSE file or at
+ * https://opensource.org/licenses/MIT.
+ */
+
+import { Client } from '../client/client';
+import { Local } from '../client/transport/local';
+import type { Game, Plugin } from '../types';
+import { GameMethod } from '../../packages/core';
+
+describe('basic', () => {
+  let client: ReturnType<typeof Client>;
+
+  beforeAll(() => {
+    interface TestPluginAPI {
+      get(): number;
+      increment(): number;
+    }
+
+    const TestPlugin = (init: {
+      n: number;
+    }): Plugin<TestPluginAPI, { n: number }> => ({
+      name: 'test',
+
+      setup: () => init,
+
+      api: ({ data }) => {
+        const state = { value: data.n };
+        const increment = () => state.value++;
+        const get = () => state.value;
+        return { increment, get };
+      },
+
+      flush: ({ api }) => ({ n: api.get() }),
+
+      fnWrap: (fn) => (context) => {
+        const G = fn(context);
+        return { ...G, wrap: true };
+      },
+    });
+
+    const game: Game<
+      { beginA: number; endA: number; onMove: number; onTurnEnd: number },
+      { test: TestPluginAPI }
+    > = {
+      moves: {
+        A: ({ G, test }) => {
+          G.beginA = test.get();
+          test.increment();
+          G.endA = test.get();
+        },
+      },
+
+      endIf: ({ test }) => {
+        if (test === undefined) {
+          throw new Error('API is not defined');
+        }
+      },
+
+      turn: {
+        onMove: ({ G, test }) => {
+          G.onMove = test.get();
+          test.increment();
+        },
+
+        onEnd: ({ G, test }) => {
+          G.onTurnEnd = test.get();
+          test.increment();
+        },
+      },
+
+      plugins: [TestPlugin({ n: 10 })],
+    };
+
+    client = Client({ game });
+  });
+
+  test('setup', () => {
+    expect(client.getState().plugins.test.data).toEqual({
+      n: 10,
+    });
+  });
+
+  test('make move', () => {
+    client.moves.A();
+    expect(client.getState().G).toEqual({
+      beginA: 10,
+      endA: 11,
+      onMove: 11,
+      wrap: true,
+    });
+    expect(client.getState().plugins.test.data).toEqual({ n: 12 });
+  });
+
+  test('make another move', () => {
+    client.moves.A();
+    expect(client.getState().G).toEqual({
+      beginA: 12,
+      endA: 13,
+      onMove: 13,
+      wrap: true,
+    });
+    expect(client.getState().plugins.test.data).toEqual({ n: 14 });
+  });
+
+  test('event', () => {
+    client.events.endTurn();
+    expect(client.getState().G).toMatchObject({ onTurnEnd: 14 });
+    expect(client.getState().plugins.test.data).toEqual({ n: 15 });
+  });
+
+  test('does not make it into undo state', () => {
+    client.moves.A();
+    client.undo();
+    expect(Object.keys(client.getState()._undo[0].ctx)).not.toContain('test');
+  });
+});
+
+describe('default values', () => {
+  const pluginData = { value: true };
+
+  const plugin = {
+    name: 'test',
+    flush: () => pluginData,
+  };
+
+  const anotherPlugin = {
+    name: 'test2',
+    noClient: () => false,
+  };
+
+  const game: Game = {
+    moves: { A: () => {} },
+    plugins: [plugin, anotherPlugin],
+  };
+
+  test('are used if no setup is present', () => {
+    const client = Client({ game, playerID: '0', multiplayer: Local() });
+    client.start();
+    client.moves.A();
+    expect(client.getState().plugins.test.data).toEqual(pluginData);
+  });
+});
+
+describe('isInvalid method', () => {
+  // Silence expected error logging and restore when finished.
+  const stderr = console.error;
+  beforeAll(() => (console.error = () => {}));
+  afterAll(() => (console.error = stderr));
+
+  test('basic plugin', () => {
+    const goodG = { good: 'nice' };
+    const game: Game = {
+      plugins: [
+        {
+          name: 'test',
+          isInvalid: ({ G }) => 'bad' in G && 'not ok',
+        },
+      ],
+      moves: {
+        good: () => goodG,
+        bad: () => ({ bad: 'not ok' }),
+      },
+    };
+
+    const client = Client({ game, playerID: '0' });
+    client.start();
+    client.moves.good();
+    expect(client.getState().G).toEqual(goodG);
+    client.moves.bad();
+    expect(client.getState().G).toEqual(goodG);
+  });
+
+  test('plugin with API and data', () => {
+    const game: Game<any, any> = {
+      plugins: [
+        {
+          name: 'test',
+          setup: () => ({}),
+          api: ({ data }) => ({
+            set: (key, val) => {
+              data[key] = val;
+            },
+          }),
+          isInvalid: ({ data }) => 'bad' in data && 'not ok',
+        },
+      ],
+      moves: {
+        good: ({ test }) => {
+          test.set('good', 'nice');
+        },
+        bad: ({ test }) => {
+          test.set('bad', 'not ok');
+        },
+      },
+    };
+
+    const client = Client({ game, playerID: '0' });
+    client.start();
+    expect(client.getState().ctx.numMoves).toBe(0);
+    client.moves.good();
+    expect(client.getState().ctx.numMoves).toBe(1);
+    client.moves.bad();
+    expect(client.getState().ctx.numMoves).toBe(1);
+  });
+});
+
+describe('actions', () => {
+  let client: ReturnType<typeof Client>;
+
+  beforeAll(() => {
+    const game: Game = {
+      plugins: [
+        {
+          name: 'test',
+
+          setup: () => ({
+            initial: true,
+          }),
+
+          action: (_, payload) => {
+            return payload.args[0];
+          },
+        },
+        {
+          name: 'nosetup',
+          action: () => ({ action: true }),
+        },
+      ],
+    };
+
+    client = Client({ game });
+  });
+
+  test('setup', () => {
+    expect(client.getState().plugins.test.data).toEqual({
+      initial: true,
+    });
+    expect(client.getState().plugins.nosetup).toBeUndefined();
+  });
+
+  test('take action', () => {
+    const payload = { payload: true };
+
+    client.plugins.test(payload);
+    client.plugins.nosetup(payload);
+
+    expect(client.getState().plugins.test.data).toEqual(payload);
+    expect(client.getState().plugins.nosetup.data).toEqual({ action: true });
+  });
+});
+
+describe('plugins are accessible in events triggered from moves', () => {
+  type TestPluginAPI = { get: () => boolean };
+  type PluginAPIs = { test: TestPluginAPI };
+  const plugins = [
+    {
+      name: 'test',
+
+      setup: () => ({
+        initial: true,
+      }),
+
+      flush: () => ({ initial: true }),
+
+      api: ({ data }): TestPluginAPI => {
+        return {
+          get: () => data.initial,
+        };
+      },
+    },
+  ];
+
+  test('turn/onBegin', () => {
+    const game: Game<any, PluginAPIs> = {
+      plugins,
+      moves: {
+        stop: ({ events }) => events.endTurn(),
+      },
+      turn: {
+        onBegin: ({ G, random, test }) => {
+          G.onBegin = random.Die(1);
+          G.test = test.get();
+        },
+      },
+    };
+
+    const client = Client({ game });
+    client.moves.stop();
+    expect(client.getState().G).toEqual({
+      onBegin: 1,
+      test: true,
+    });
+  });
+
+  test('turn/onEnd', () => {
+    const game: Game<any, PluginAPIs> = {
+      plugins,
+      moves: {
+        stop: ({ events }) => events.endTurn(),
+      },
+      turn: {
+        onEnd: ({ G, random, test }) => {
+          G.onEnd = random.Die(1);
+          G.test = test.get();
+        },
+      },
+    };
+
+    const client = Client({ game });
+    client.moves.stop();
+    expect(client.getState().G).toEqual({
+      onEnd: 1,
+      test: true,
+    });
+  });
+
+  test('phase/onBegin', () => {
+    const game: Game<any, PluginAPIs> = {
+      plugins,
+      moves: {
+        stop: ({ events }) => events.setPhase('second'),
+      },
+      phases: {
+        first: {
+          start: true,
+        },
+        second: {
+          onBegin: ({ G, random, test }) => {
+            G.onBegin = random.Die(1);
+            G.test = test.get();
+          },
+        },
+      },
+    };
+
+    const client = Client({ game });
+    client.moves.stop();
+    expect(client.getState().G).toEqual({
+      onBegin: 1,
+      test: true,
+    });
+  });
+
+  test('phase/onEnd', () => {
+    const game: Game<any, PluginAPIs> = {
+      plugins,
+      moves: {
+        stop: ({ events }) => events.endPhase(),
+      },
+      phases: {
+        first: {
+          start: true,
+          onEnd: ({ G, random, test }) => {
+            G.onEnd = random.Die(1);
+            G.test = test.get();
+          },
+        },
+      },
+    };
+
+    const client = Client({ game });
+    client.moves.stop();
+    expect(client.getState().G).toEqual({
+      onEnd: 1,
+      test: true,
+    });
+  });
+});
+
+describe('plugins can use events in fnWrap', () => {
+  const game: Game = {
+    plugins: [
+      {
+        name: 'test',
+        fnWrap:
+          (fn, type) =>
+          (context, ...args) => {
+            const G = fn(context, ...args);
+            if (G.endTurn && type === GameMethod.MOVE) {
+              context.events.endTurn();
+            }
+            if (G.endGame) {
+              context.events.endGame(G.endGame);
+            }
+            return G;
+          },
+      },
+    ],
+    moves: {
+      endGame: () => ({ endGame: true }),
+      endTurn: () => ({ endTurn: true }),
+    },
+  };
+
+  test('plugin can end turn', () => {
+    const client = Client({ game });
+    client.moves.endTurn();
+    expect(client.getState().ctx.turn).toBe(2);
+    expect(client.getState().ctx.currentPlayer).toBe('1');
+  });
+
+  test('plugin can end game', () => {
+    const client = Client({ game });
+    client.moves.endGame();
+    expect(client.getState().ctx.gameover).toBe(true);
+  });
+});