rename plugin api functions

Author: nicolodavis

docs/plugins.md

@@ -8,29 +8,47 @@ in `G` and much more.
 #### Creating a Plugin
 
 A plugin is an object that contains the following fields.
+All fields are optional and typically accept the `game`
+object as a parameter.
 
 ```js
 {
-  // Optional.
   // Function that accepts a move / trigger function
   // and returns another function that wraps it. This
   // wrapper can modify G before passing it down to
   // the wrapped function. It is a good practice to
-  // undo the change at the end of the call.
-  fnWrap: (fn) => (G, ctx, ...args) => {
+  // undo the change at the end of the call. You can
+  // also use the more convenient preMove / postMove
+  // hooks below if all you desire is to preprocess
+  // and postprocess G.
+  fnWrap: (fn, game) => (G, ctx, ...args) => {
     G = preprocess(G);
     G = fn(G, ctx, ...args);
     G = postprocess(G);
     return G;
   },
 
-  // Optional.
-  // Called during setup in order to add state to G.
-  setupG: (G, ctx) => G,
+  G: {
+    // Called during setup in order to add state to G.
+    setup: (G, ctx, game) => G,
 
-  // Optional.
-  // Called during setup in order to add state to ctx.
-  setupCtx: (ctx) => ctx,
+    // Called right before a move / event in order to preprocess G.
+    preMove: (G, game) => G,
+
+    // Called right after a move / event in order to postprocess G.
+    postMove: (G, game) => G,
+  },
+
+  ctx: {
+    // Called during setup in order to add state to ctx.
+    setup: (ctx, game) => ctx,
+
+    // Called right before a move / event in order to preprocess ctx.
+    preMove: (ctx, game) => ctx,
+
+    // Called right after a move / event in order to postprocess ctx.
+    postMove: (ctx, game) => ctx,
+  },
 }
 ```
 

src/plugins/main.js

@@ -21,9 +21,10 @@ const DEFAULT_PLUGINS = [PluginImmer];
  */
 export const SetupCtx = (ctx, game) => {
   [...DEFAULT_PLUGINS, ...game.plugins]
-    .filter(plugin => plugin.setupCtx !== undefined)
+    .filter(plugin => plugin.ctx !== undefined)
+    .filter(plugin => plugin.ctx.setup !== undefined)
     .forEach(plugin => {
-      ctx = plugin.setupCtx(ctx, game);
+      ctx = plugin.ctx.setup(ctx, game);
     });
   return ctx;
 };
@@ -37,9 +38,10 @@ export const SetupCtx = (ctx, game) => {
  */
 export const SetupG = (G, ctx, game) => {
   [...DEFAULT_PLUGINS, ...game.plugins]
-    .filter(plugin => plugin.setupG !== undefined)
+    .filter(plugin => plugin.G !== undefined)
+    .filter(plugin => plugin.G.setup !== undefined)
     .forEach(plugin => {
-      G = plugin.setupG(G, ctx, game);
+      G = plugin.G.setup(G, ctx, game);
     });
   return G;
 };
@@ -50,26 +52,28 @@ export const SetupG = (G, ctx, game) => {
  * @param {object} ctx - The ctx object.
  * @param {object} game - The game object.
  */
-export const AddToCtx = (ctx, game) => {
+export const CtxPreMove = (ctx, game) => {
   [...DEFAULT_PLUGINS, ...game.plugins]
-    .filter(plugin => plugin.addToCtx !== undefined)
+    .filter(plugin => plugin.ctx !== undefined)
+    .filter(plugin => plugin.ctx.preMove !== undefined)
     .forEach(plugin => {
-      ctx = plugin.addToCtx(ctx, game);
+      ctx = plugin.ctx.preMove(ctx, game);
     });
   return ctx;
 };
 
 /**
- * Removes the provided plugins to ctx after processing a move / event.
+ * Postprocesses ctx after a move / event.
  *
  * @param {object} ctx - The ctx object.
  * @param {object} game - The game object.
  */
-export const RemoveFromCtx = (ctx, game) => {
+export const CtxPostMove = (ctx, game) => {
   [...DEFAULT_PLUGINS, ...game.plugins]
-    .filter(plugin => plugin.removeFromCtx !== undefined)
+    .filter(plugin => plugin.ctx !== undefined)
+    .filter(plugin => plugin.ctx.postMove !== undefined)
     .forEach(plugin => {
-      ctx = plugin.removeFromCtx(ctx, game);
+      ctx = plugin.ctx.postMove(ctx, game);
     });
   return ctx;
 };
@@ -80,26 +84,28 @@ export const RemoveFromCtx = (ctx, game) => {
  * @param {object} G - The G object.
  * @param {object} game - The game object.
  */
-export const AddToG = (G, game) => {
+export const GPreMove = (G, game) => {
   [...DEFAULT_PLUGINS, ...game.plugins]
-    .filter(plugin => plugin.addToG !== undefined)
+    .filter(plugin => plugin.G !== undefined)
+    .filter(plugin => plugin.G.preMove !== undefined)
     .forEach(plugin => {
-      G = plugin.addToG(G, game);
+      G = plugin.G.preMove(G, game);
     });
   return G;
 };
 
 /**
- * Removes the provided plugins to G after processing a move / event.
+ * Postprocesses G after a move / event.
  *
  * @param {object} G - The G object.
  * @param {object} game - The game object.
  */
-export const RemoveFromG = (G, game) => {
+export const GPostMove = (G, game) => {
   [...DEFAULT_PLUGINS, ...game.plugins]
-    .filter(plugin => plugin.removeFromG !== undefined)
+    .filter(plugin => plugin.G !== undefined)
+    .filter(plugin => plugin.G.postMove !== undefined)
     .forEach(plugin => {
-      G = plugin.removeFromG(G, game);
+      G = plugin.G.postMove(G, game);
     });
   return G;
 };
@@ -111,17 +117,17 @@ export const RemoveFromG = (G, game) => {
  * @param {object} game - The game object.
  */
 export const FnWrap = (fn, game) => {
-  const reducer = (acc, { fnWrap }) => fnWrap(acc);
+  const reducer = (acc, { fnWrap }) => fnWrap(acc, game);
   const g = [...DEFAULT_PLUGINS, ...game.plugins]
     .filter(plugin => plugin.fnWrap !== undefined)
     .reduce(reducer, fn);
 
   return (G, ctx, ...args) => {
-    G = AddToG(G, game);
-    ctx = AddToCtx(ctx, game);
+    G = GPreMove(G, game);
+    ctx = CtxPreMove(ctx, game);
     G = g(G, ctx, ...args);
-    ctx = RemoveFromCtx(ctx, game);
-    ctx = RemoveFromG(G, game);
+    ctx = CtxPostMove(ctx, game);
+    ctx = GPostMove(G, game);
     return G;
   };
 };

src/plugins/main.test.js

@@ -29,12 +29,16 @@ describe('plugins', () => {
             G = fn(G, ctx);
             return { ...G, fnWrap: true };
           },
-          setupG: G => ({ ...G, initG: true }),
-          setupCtx: ctx => ({ ...ctx, initCtx: true }),
-          addToCtx: ctx => ({ ...ctx, addToCtx: true }),
-          removeFromCtx: ctx => ({ ...ctx, removeFromCtx: true }),
-          addToG: G => ({ ...G, addToG: true }),
-          removeFromG: G => ({ ...G, removeFromG: true }),
+          G: {
+            setup: G => ({ ...G, initG: true }),
+            preMove: G => ({ ...G, addToG: true }),
+            postMove: G => ({ ...G, removeFromG: true }),
+          },
+          ctx: {
+            setup: ctx => ({ ...ctx, initCtx: true }),
+            preMove: ctx => ({ ...ctx, addToCtx: true }),
+            postMove: ctx => ({ ...ctx, removeFromCtx: true }),
+          },
         },
       ],
     });

src/plugins/plugin-player.js

@@ -48,15 +48,17 @@ export default initPlayerState => ({
     };
   },
 
-  setupG: (G, ctx) => {
-    let players = {};
-    for (let i = 0; i < ctx.numPlayers; i++) {
-      const playerState = {};
-      if (initPlayerState !== undefined) {
-        initPlayerState(i + '');
+  G: {
+    setup: (G, ctx) => {
+      let players = {};
+      for (let i = 0; i < ctx.numPlayers; i++) {
+        const playerState = {};
+        if (initPlayerState !== undefined) {
+          initPlayerState(i + '');
+        }
+        players[i + ''] = playerState;
       }
-      players[i + ''] = playerState;
-    }
-    return { ...G, players };
+      return { ...G, players };
+    },
   },
 });

src/plugins/plugin-player.test.js

@@ -13,7 +13,7 @@ import { makeMove, gameEvent } from '../core/action-creators';
 
 describe('default values', () => {
   test('playerState is not passed', () => {
-    const value = PluginPlayer().setupG({}, { numPlayers: 2 });
+    const value = PluginPlayer().G.setup({}, { numPlayers: 2 });
     expect(value).toEqual({ players: { '0': {}, '1': {} } });
   });
 });