Fix compose() to have a less surprising API

docs/api/compose.md

@@ -1,17 +1,17 @@
 # `compose(...functions)`
 
-Composes functions from left to right.
+Composes functions from right to left.
 
 This is a functional programming utility, and is included in Redux as a convenience.  
 You might want to use it to apply several [store enhancers](../Glossary.md#store-enhancer) in a row.
 
 #### Arguments
 
-1. (*arguments*): The functions to compose. Each function is expected to accept a function as an argument and to return a function.
+1. (*arguments*): The functions to compose. Each function is expected to accept a single parameter. Its return value will be provided as an argument to the function standing to the left, and so on.
 
 #### Returns
 
-(*Function*): The final function obtained by composing the given functions from left to right.
+(*Function*): The final function obtained by composing the given functions from right to left.
 
 #### Example
 
@@ -39,20 +39,16 @@ if (process.env.NODE_ENV === 'production') {
     require('redux-devtools').devTools(),
     require('redux-devtools').persistState(
       window.location.href.match(/[?&]debug_session=([^&]+)\b/)
-    ),
-    createStore
-  );
+    )
+  )(createStore);
 
-  // Same code without the compose helper:
+  // Same code without the `compose` helper:
   //
-  // finalCreateStore =
-  //   applyMiddleware(middleware)(
-  //     devTools()(
-  //       persistState(window.location.href.match(/[?&]debug_session=([^&]+)\b/))(
-  //         createStore
-  //       )
-  //     )
-  //   );
+  // finalCreateStore = applyMiddleware(middleware)(
+  //   require('redux-devtools').devTools()(
+  //     require('redux-devtools').persistState(window.location.href.match(/[?&]debug_session=([^&]+)\b/))()
+  //   )
+  // )(createStore);
 }
 
 let store = finalCreateStore(reducer);

src/utils/applyMiddleware.js

@@ -27,7 +27,7 @@ export default function applyMiddleware(...middlewares) {
       dispatch: (action) => dispatch(action)
     };
     chain = middlewares.map(middleware => middleware(middlewareAPI));
-    dispatch = compose(...chain, store.dispatch);
+    dispatch = compose(...chain)(store.dispatch);
 
     return {
       ...store,

src/utils/compose.js

@@ -1,11 +1,10 @@
 /**
- * Composes functions from left to right.
+ * Composes single-argument functions from right to left.
  *
- * @param {...Function} funcs - The functions to compose. Each is expected to
- * accept a function as an argument and to return a function.
- * @returns {Function} A function obtained by composing functions from left to
- * right.
+ * @param {...Function} funcs The functions to compose.
+ * @returns {Function} A function obtained by composing functions from right to
+ * left. For example, compose(f, g, h) is identical to x => h(g(f(x))).
  */
 export default function compose(...funcs) {
-  return funcs.reduceRight((composed, f) => f(composed));
+  return arg => funcs.reduceRight((composed, f) => f(composed), arg);
 }

test/utils/compose.spec.js

@@ -3,15 +3,23 @@ import { compose } from '../../src';
 
 describe('Utils', () => {
   describe('compose', () => {
-    it('composes functions from left to right', () => {
+    it('composes from right to left', () => {
+      const double = x => x * 2;
+      const square = x => x * x;
+      expect(compose(square)(5)).toBe(25);
+      expect(compose(square, double)(5)).toBe(100);
+      expect(compose(double, square, double)(5)).toBe(200);
+    });
+
+    it('composes functions from right to left', () => {
       const a = next => x => next(x + 'a');
       const b = next => x => next(x + 'b');
       const c = next => x => next(x + 'c');
       const final = x => x;
 
-      expect(compose(a, b, c, final)('')).toBe('abc');
-      expect(compose(b, c, a, final)('')).toBe('bca');
-      expect(compose(c, a, b, final)('')).toBe('cab');
+      expect(compose(a, b, c)(final)('')).toBe('abc');
+      expect(compose(b, c, a)(final)('')).toBe('bca');
+      expect(compose(c, a, b)(final)('')).toBe('cab');
     });
   });
 });