Prefer a static reducer (#4)

A `static` reducer will not only improve the code because it leaves less
room for side effects, it will also make individual actions easier to
test.

Side effects still should have access to the instance (e.g. to access
refs). To enable this, all side effects will now be called with a
reference to the component as the first argument.

Previous, class property reducers will still work until the 1.0.0
release to avoid making a breaking change in a minor version.

Author: philipp-spiess

README.md

@@ -36,7 +36,7 @@ A reducer component is used like a regular, stateful, React component with the d
 
 - [Installation](#installation)
 - [Getting Started](#getting-started)
-- [Advantages Over `setState`](#advantages-over-setstate)
+- [FAQ](#faq)
 - [Advanced Usage](#advanced-usage)
   - [Side Effects](#side-effects)
   - [Handling Events](#handling-events)
@@ -67,7 +67,7 @@ class Counter extends ReComponent {
     this.state = { count: 0 };
   }
 
-  reducer(action, state) {
+  static reducer(action, state) {
     switch (action.type) {
       case "CLICK":
         return Update({ count: state.count + 1 });
@@ -99,7 +99,9 @@ ReComponent comes with four different types of [effects](https://github.com/phil
 
 By intelligently using any of the four types above, it is possible to transition between states in one place and without the need to use `setState()` manually. This drastically simplifies our mental model since changes must always go through the reducer first.
 
-## Advantages Over `setState`
+## FAQ
+
+### Advantages Over `setState`
 
 The advantages are similar to those of [Redux](https://github.com/reduxjs/redux) or really any state management tool:
 
@@ -109,6 +111,14 @@ The advantages are similar to those of [Redux](https://github.com/reduxjs/redux)
 
 3.  Get rid of side effects with **Pure State Transformation**. By keeping your state changes side effect free, you’re forced into writing code that is easier to test (given an action and a state, it must _always_ return the same new state). Plus you can build extended event sourcing features on top of that since you can easily store all actions that where send to your reducers and replay them later (to go back in time and see exactly how an invalid state occurred).
 
+### Why is the reducer `static`?
+
+To fully leverage all of the advantages outlined above, the reducer function must not have any side effects. Making the reducer `static` will enforce this behavior since you won’t have access to `this` inside the function. We identified three situations that could need `this` inside the reducer:
+
+1.  You’re about to read class properties. In this case, make sure those properties are properly encapsulated in the state object.
+2.  You’re about to write class properties. This is a side effect and should be handled using the `SideEffects(fn)` effect.
+3.  You’re accessing a function that is pure by itself. In this case, the function does not need to be a class property but can be a regular module function instead.
+
 ## Advanced Usage
 
 Now that we‘ve learned how to use reducer components with React, it‘s time to look into more advanced use cases to effectively handle state transitions across bigger portions of your app.
@@ -141,7 +151,7 @@ class Counter extends ReComponent {
     this.state = { count: 0 };
   }
 
-  reducer(action, state) {
+  static reducer(action, state) {
     switch (action.type) {
       case "NO_UPDATE":
         return NoUpdate();
@@ -202,7 +212,7 @@ class Counter extends ReComponent {
     });
   }
 
-  reducer(action, state) {
+  static reducer(action, state) {
     switch (action.type) {
       case "CLICK":
         return Update({
@@ -270,7 +280,7 @@ class Container extends ReComponent {
     this.state = { count: 0 };
   }
 
-  reducer(action, state) {
+  static reducer(action, state) {
     switch (action.type) {
       case "CLICK":
         return Update({ count: state.count + 1 });
@@ -308,7 +318,7 @@ class UntypedActionTypes extends ReComponent<Props, State> {
   handleClick = this.createSender("CLICK");
   state = { count: 0 };
 
-  reducer(action, state) {
+  static reducer(action, state) {
     switch (action.type) {
       case "CLICK":
         return Update({ count: state.count + 1 });
@@ -341,7 +351,7 @@ class TypedActionTypes extends ReComponent<Props, State, ActionTypes> {
   handleClick = this.createSender("CLICK");
   state = { count: 0 };
 
-  reducer(action, state) {
+  static reducer(action, state) {
     switch (action.type) {
       case "CLICK":
         return Update({ count: state.count + 1 });
@@ -373,7 +383,7 @@ Check out the [type definition tests](https://github.com/philipp-spiess/react-re
 
 - `ReComponent`
 
-  - `reducer(action, state): effect`
+  - `static reducer(action, state): effect`
 
     Translates an action into an effect. This is the main place to update your component‘s state.
 
@@ -402,13 +412,13 @@ Check out the [type definition tests](https://github.com/philipp-spiess/react-re
 
   Returning this effect will update the state. Internally, this will use `setState()` with an updater function.
 
-- `SideEffects(fn)`
+- `SideEffects(this => mixed)`
 
-  Enqueues side effects to be run but will not update the component‘s state.
+  Enqueues side effects to be run but will not update the component‘s state. The side effect will be called with a reference to the react component (`this`) as the first argument.
 
-- `UpdateWithSideEffects(state, fn)`
+- `UpdateWithSideEffects(state, this => mixed)`
 
-  Updates the component‘s state and _then_ calls the side effect function.
+  Updates the component‘s state and _then_ calls the side effect function.The side effect will be called with a reference to the react component (`this`) as the first argument.
 
 ## License
 

__tests__/Context-test.js

@@ -48,7 +48,7 @@ describe("ReComponent", () => {
       this.state = { count: 0 };
     }
 
-    reducer(action, state) {
+    static reducer(action, state) {
       switch (action.type) {
         case "CLICK":
           return Update({ count: state.count + 1 });

__tests__/ReComponent-test.js

@@ -26,7 +26,7 @@ describe("ReComponent", () => {
       this.state = { count: 0 };
     }
 
-    reducer(action, state) {
+    static reducer(action, state) {
       switch (action.type) {
         case "CLICK":
           return Update({ count: state.count + 1 });
@@ -74,7 +74,7 @@ describe("ReComponent", () => {
         super();
         setState = () => this.setState({ some: "state" });
       }
-      reducer() {}
+      static reducer() {}
       render() {
         return null;
       }
@@ -98,7 +98,7 @@ describe("ReComponent", () => {
           click = this.createSender("CLICK");
         }
 
-        reducer(action, state) {
+        static reducer(action, state) {
           return {};
         }
 
@@ -113,4 +113,36 @@ describe("ReComponent", () => {
       process.env.NODE_ENV = originalNodeEnv;
     }
   });
+
+  it("warns when the reducer is not static", () => {
+    let originalWarn = console.warn;
+    try {
+      console.warn = jest.fn();
+
+      let click;
+      class ClassPropertyReducer extends ReComponent {
+        constructor() {
+          super();
+          click = this.createSender("CLICK");
+        }
+
+        reducer(action, state) {
+          return NoUpdate();
+        }
+
+        render() {
+          return null;
+        }
+      }
+
+      ReactDOM.render(<ClassPropertyReducer />, container);
+      expect(() => click()).not.toThrowError();
+
+      expect(console.warn).toHaveBeenCalledWith(
+        "ClassPropertyReducer(...): Class property `reducer` methods are deprecated. Please upgrade to `static` reducers instead: https://github.com/philipp-spiess/react-recomponent#why-is-the-reducer-static"
+      );
+    } finally {
+      console.warn = originalWarn;
+    }
+  });
 });

__tests__/ReComponentImmutable-test.js

@@ -30,7 +30,7 @@ describe("ReComponentImmutable", () => {
       return State();
     }
 
-    reducer(action, state) {
+    static reducer(action, state) {
       switch (action.type) {
         case "CLICK":
           return Update(state.update("count", count => count + 1));

__tests__/RePureComponent-test.js

@@ -25,7 +25,7 @@ describe("RePureComponent", () => {
       this.state = { count: 0 };
     }
 
-    reducer(action, state) {
+    static reducer(action, state) {
       switch (action.type) {
         case "CLICK":
           return Update({ count: state.count + 1 });

__tests__/UpdateTypes-test.js

@@ -40,17 +40,18 @@ describe("UpdateTypes", () => {
       this.state = { count: 0 };
     }
 
-    reducer(action, state) {
+    static reducer(action, state) {
       switch (action.type) {
         case "NO_UPDATE":
           return NoUpdate();
         case "UPDATE":
           return Update({ count: state.count + 1 });
         case "SIDE_EFFECTS":
-          return SideEffects(() => sideEffectSpy());
+          return SideEffects(sideEffectSpy);
         case "UPDATE_WITH_SIDE_EFFECTS":
-          return UpdateWithSideEffects({ count: state.count + 1 }, () =>
-            sideEffectSpy()
+          return UpdateWithSideEffects(
+            { count: state.count + 1 },
+            sideEffectSpy
           );
         case "INVALID":
           return {};
@@ -106,7 +107,7 @@ describe("UpdateTypes", () => {
       const instance = ReactDOM.render(<ReducerReturns />, container);
       sideEffects();
       expect(container.textContent).toEqual("You’ve clicked 0 times(s)");
-      expect(sideEffectSpy).toHaveBeenCalled();
+      expect(sideEffectSpy).toHaveBeenCalledWith(instance);
     });
 
     it("does not re-render", () => {
@@ -121,7 +122,7 @@ describe("UpdateTypes", () => {
       const instance = ReactDOM.render(<ReducerReturns />, container);
       updateWithSideEffects();
       expect(container.textContent).toEqual("You’ve clicked 1 times(s)");
-      expect(sideEffectSpy).toHaveBeenCalled();
+      expect(sideEffectSpy).toHaveBeenCalledWith(instance);
     });
 
     it("re-renders", () => {

src/re.js

@@ -11,8 +11,22 @@ export function Re(Component) {
       super(props);
 
       if (process.env.NODE_ENV !== "production") {
-        if (typeof this.reducer !== "function") {
-          const name = this.displayName || this.constructor.name;
+        const name = this.displayName || this.constructor.name;
+
+        const isStaticReducer = typeof this.constructor.reducer === "function";
+        const isPropertyReducer = typeof this.reducer === "function";
+
+        // @TODO: Remove property reducer support with v1.0.0
+        if (isPropertyReducer) {
+          console.warn(
+            name +
+              "(...): Class property `reducer` methods are deprecated. Please " +
+              "upgrade to `static` reducers instead: " +
+              "https://github.com/philipp-spiess/react-recomponent#why-is-the-reducer-static"
+          );
+        }
+
+        if (!(isStaticReducer || isPropertyReducer)) {
           throw new Error(
             name +
               "(...): No `reducer` method found on the returned component " +
@@ -82,7 +96,12 @@ export function Re(Component) {
         let sideEffects;
 
         const updater = state => {
-          const reduced = this.reducer(action, state);
+          let reduced;
+          if (typeof this.reducer === "function") {
+            reduced = this.reducer(action, state);
+          } else {
+            reduced = this.constructor.reducer(action, state);
+          }
 
           if (process.env.NODE_ENV !== "production") {
             if (typeof reduced === "undefined") {
@@ -129,7 +148,7 @@ export function Re(Component) {
           return state;
         };
 
-        setState.call(this, updater, () => sideEffects && sideEffects());
+        setState.call(this, updater, () => sideEffects && sideEffects(this));
       };
 
       // Convenience method to create sender functions: Functions that send an

type-definitions/ReComponent.js.flow

@@ -7,19 +7,18 @@
 import * as React from "react";
 
 declare opaque type UpdateType;
-declare type fn = () => mixed;
 
 export type Sender<AT, A = mixed> = (a: A) => { action: AT, payload: A };
 
 declare export function NoUpdate(): {| type: UpdateType |};
 declare export function Update<S>(state: S): {| type: UpdateType, state: S |};
-declare export function SideEffects(
-  sideEffects: fn
-): {| type: UpdateType, sideEffects: fn |};
-declare export function UpdateWithSideEffects<S>(
+declare export function SideEffects<T>(
+  sideEffects: (T) => mixed
+): {| type: UpdateType, sideEffects: T => mixed |};
+declare export function UpdateWithSideEffects<S, T>(
   state: S,
-  sideEffects: fn
-): {| type: UpdateType, state: S, sideEffects: fn |};
+  sideEffects: (T) => mixed
+): {| type: UpdateType, state: S, sideEffects: T => mixed |};
 
 declare export class ReComponent<
   Props,
@@ -28,14 +27,14 @@ declare export class ReComponent<
 > extends React.Component<Props, State> {
   initialState(props: Props): State;
 
-  reducer(
+  static reducer(
     action: { type: ActionType },
     state: State
   ):
     | {| type: UpdateType |}
     | {| type: UpdateType, state: $Shape<State> |}
-    | {| type: UpdateType, sideEffects: fn |}
-    | {| type: UpdateType, state: $Shape<State>, sideEffects: fn |};
+    | {| type: UpdateType, sideEffects: ($Subtype<ReComponent<Props, State, ActionType>>) => mixed |}
+    | {| type: UpdateType, state: $Shape<State>, sideEffects: ($Subtype<ReComponent<Props, State, ActionType>>) => mixed |};
 
   send(action: { type: ActionType, payload?: mixed }): void;