Pass previous state to event definitions (#117)

Author: ttmarek

docs/api/event-definition.md

@@ -1,16 +1,25 @@
 ### `EventDefinition`
 
 A `function` used by Redux Beacon to generate an event or series of events for a
-given Redux action. An event definition receives the associated action object,
-and the state of the application (before the action).
+given Redux action. An event definition receives the associated action object
+and the state of the application (before and after the action).
+
+```typescript
+export type EventDefinition = (
+  action: Action,
+  prevState: any,
+  nextState: any
+) => any | Array<any>;
+```
 
 #### A Basic Event Definition
 ```js
-function (action, prevState) {
+function (action, prevState, nextState) {
   return {
     hitType: 'pageview',
     route: action.payload.location.pathname,
     referrer: prevState.currentRoute,
+    numUserActions: nextState.numUserActions,
   };
 }
 ```

docs/notes-on-unit-testing.md

@@ -5,15 +5,16 @@ transformations it's not a bad idea to test them. Or better yet to
 start out with a test or two, and build out your event definitions to
 make the tests pass.
 
-To help with testing, Redux-Beacon exposes a function `createEvents`
+To help with testing, Redux Beacon exposes a function `createEvents`
 which it uses internally to create events from event
 definitions. `createEvents` has the following signature:
 
 ```js
-function createEvents(
-  eventDefinition: EventDefinition | Array<EventDefinition>,
+export function createEvents(
+  eventDefinition: EventDefinition,
   prevState: any,
   action: any,
+  nextState: any
 ): Array<any>;
 ```
 

index.d.ts

@@ -6,13 +6,16 @@ interface Action {
 }
 
 /**
- * Used by Redux-Beacon to generate an event or series of events for a
- * given Redux action. An event definition is a function that will
- * receive the state of the application (before the action), and the
- * associated action object. The function should return an event, or
- * an array of events.
+ * Used by Redux Beacon to generate an event or series of
+ * events for a given Redux action. An event definition receives the
+ * associated action object and the state of the application (before
+ * and after the action).
  */
-export type EventDefinition = (action: Action, prevState: any) => any | Array<any>;
+export type EventDefinition = (
+  action: Action,
+  prevState: any,
+  nextState: any
+) => any | Array<any>;
 
 /**
  * A map between your actions and your analytics events.  Each key
@@ -49,7 +52,8 @@ export function createMetaReducer(
  * Use this function for testing your event definitions.
  */
 export function createEvents(
-  eventDefinition: EventDefinition | Array<EventDefinition>,
+  eventDefinition: EventDefinition,
   prevState: any,
-  action: any
+  action: any,
+  nextState: any
 ): Array<any>;

src/main/__tests__/create-events.test.js

@@ -80,11 +80,24 @@ describe('createEvents(eventDef, prevState, action)', () => {
         { hitType: 'timing' },
       ],
     },
+    {
+      title: 'event definition uses previous state',
+      eventDef: (action, prevState, nextState) => ({
+        hitType: 'event',
+        numActions: nextState.numActions,
+      }),
+      nextState: { numActions: 3 },
+      expected: [{
+        hitType: 'event',
+        numActions: 3,
+      }],
+    },
   ].forEach((scenario, index) => {
     const {
       title,
       eventDef,
       prevState,
+      nextState,
       action,
       expected,
     } = scenario;
@@ -93,7 +106,13 @@ describe('createEvents(eventDef, prevState, action)', () => {
       if (title === undefined || eventDef === undefined || expected === undefined) {
         throw new Error('tests require title, eventDef, and expected keys');
       }
-      expect(createEvents(eventDef, prevState || {}, action || {})).toEqual(expected);
+      const events = createEvents(
+        eventDef,
+        prevState || {},
+        action || {},
+        nextState || {}
+      );
+      expect(events).toEqual(expected);
     });
   });
 });

src/main/__tests__/integration.test.js

@@ -6,22 +6,39 @@ function runIntegrationTests(title, prepareStore) {
     describe('When an action with an associated event definition is dispatched', () => {
       it('creates the event and pushes it to the target', () => {
         const eventsMap = {
-          ROUTE_CHANGED: (action, prevState) => ({
+          ROUTE_CHANGED: (action, prevState, nextState) => ({
             hitType: 'pageview',
             page: action.payload,
             referrer: prevState.route,
+            numActions: nextState.numActions,
           }),
         };
         const target = jest.fn();
 
-        const reducer = (state = { route: '/home' }) => state;
+        const initialState = {
+          route: '/home',
+          numActions: 0,
+        };
+        const reducer = (state = initialState, action) => {
+          if (action.type === 'ROUTE_CHANGED') {
+            return Object.assign({}, state, {
+              route: action.payload,
+              numActions: state.numActions + 1,
+            });
+          }
+          return state;
+        };
+
         const store = prepareStore(reducer, eventsMap, target);
 
         store.dispatch({ type: 'ROUTE_CHANGED', payload: '/my-account' });
 
-        expect(target).toHaveBeenCalledWith([
-          { hitType: 'pageview', page: '/my-account', referrer: '/home' },
-        ]);
+        expect(target).toHaveBeenCalledWith([{
+          hitType: 'pageview',
+          page: '/my-account',
+          referrer: '/home',
+          numActions: 1,
+        }]);
       });
     });
 

src/main/__tests__/main.ts

@@ -19,6 +19,5 @@ const target = () => {};
 createMiddleware(eventsMap, target, { logger, offlineStorage: offlineWeb });
 createMetaReducer(eventsMap, target, { logger, offlineStorage: offlineWeb });
 
-let events: Array<any>
-events = createEvents(eventDefinition, {}, {});
-events = createEvents([eventDefinition, eventDefinition], {}, {});
+let events: Array<any>;
+events = createEvents(eventDefinition, {}, {}, {});

src/main/create-events.js

@@ -1,4 +1,4 @@
-const createEvents = (eventDefinition, prevState, action) =>
-  [].concat(eventDefinition(action, prevState)).filter(ifTruethy => ifTruethy);
+const createEvents = (eventDefinition, prevState, action, nextState) =>
+  [].concat(eventDefinition(action, prevState, nextState)).filter(ifTruethy => ifTruethy);
 
 module.exports = createEvents;

src/main/create-meta-reducer.js

@@ -2,17 +2,25 @@ const createEvents = require('./create-events');
 const registerEvents = require('./register-events');
 
 function createMetaReducer(eventDefinitionsMap, target, extensions = {}) {
+  /* Why not arrow functions? AOT... */
   /* eslint-disable func-names */
   return function (reducer) {
     return function (prevState, action) {
       if (!eventDefinitionsMap[action.type]) {
         return reducer(prevState, action);
       }
 
-      const events = createEvents(eventDefinitionsMap[action.type], prevState, action);
+      const nextState = reducer(prevState, action);
+      const events = createEvents(
+        eventDefinitionsMap[action.type],
+        prevState,
+        action,
+        nextState
+      );
+
       registerEvents(events, target, extensions, prevState, action);
 
-      return reducer(prevState, action);
+      return nextState;
     };
   };
 }

src/main/create-middleware.js

@@ -8,12 +8,19 @@ function createMiddleware(eventDefinitionsMap, target, extensions = {}) {
     }
 
     const prevState = store.getState();
+    const result = next(action);
+    const nextState = store.getState();
 
-    const events = createEvents(eventDefinitionsMap[action.type], prevState, action);
+    const events = createEvents(
+      eventDefinitionsMap[action.type],
+      prevState,
+      action,
+      nextState
+    );
 
     registerEvents(events, target, extensions, prevState, action);
 
-    return next(action);
+    return result;
   };
 }