Merge branch 'breaking-changes-1.0' into rewrite-docs

Author: gaearon

.eslintrc

@@ -6,6 +6,8 @@
     "node": true
   },
   "rules": {
+    "valid-jsdoc": 2,
+
     "react/jsx-uses-react": 2,
     "react/jsx-uses-vars": 2,
     "react/react-in-jsx-scope": 2,

src/createStore.js

@@ -1,22 +1,35 @@
-/* @flow */
-/*eslint-disable */
-import type { State, Reducer, Action, IntermediateAction, Store } from './index';
-/*eslint-enable */
-
 import invariant from 'invariant';
 import isPlainObject from './utils/isPlainObject';
 
-// Don't ever try to handle these action types in your code. They are private.
-// For any unknown actions, you must return the current state.
-// If the current state is undefined, you must return the initial state.
+/**
+ * These are private action types reserved by Redux.
+ * For any unknown actions, you must return the current state.
+ * If the current state is undefined, you must return the initial state.
+ * Do not reference these action types directly in your code.
+ */
 export var ActionTypes = {
   INIT: '@@redux/INIT'
 };
 
-export default function createStore(
-  reducer: Reducer,
-  initialState: State
-): Store {
+/**
+ * Creates a Redux store that holds the state tree.
+ * The only way to change the data in the store is to call `dispatch()` on it.
+ *
+ * There should only be a single store in your app. To specify how different
+ * parts of the state tree respond to actions, you may combine several reducers
+ * into a single reducer function by using `combineReducers`.
+ *
+ * @param {Function} reducer A function that returns the next state tree, given
+ * the current state tree and the action to handle.
+ *
+ * @param {any} initialState The initial state. You may optionally specify it
+ * to hydrate the state from the server in universal apps, or to restore a
+ * previously serialized user session.
+ *
+ * @returns {Store} A Redux store that lets you read the state, dispatch actions
+ * and subscribe to changes.
+ */
+export default function createStore(reducer, initialState) {
   invariant(
     typeof reducer === 'function',
     'Expected the reducer to be a function.'
@@ -26,11 +39,24 @@ export default function createStore(
   var currentState = initialState;
   var listeners = [];
 
+  /**
+   * Reads the state tree managed by the store.
+   *
+   * @returns {any} The current state tree of your application.
+   */
   function getState() {
     return currentState;
   }
 
-  function subscribe(listener: Function) {
+  /**
+   * Adds a change listener. It will be called any time an action is dispatched,
+   * and some part of the state tree may potentially have changed. You may then
+   * call `getState()` to read the current state tree inside the callback.
+   *
+   * @param {Function} listener A callback to be invoked on every dispatch.
+   * @returns {Function} A function to remove this change listener.
+   */
+  function subscribe(listener) {
     listeners.push(listener);
 
     return function unsubscribe() {
@@ -39,7 +65,29 @@ export default function createStore(
     };
   }
 
-  function dispatch(action: Action) {
+  /**
+   * Dispatches an action. It is the only way to trigger a state change.
+   *
+   * The `reducer` function the store was created with will be called with the
+   * current state tree and the and the given `action`. Its return value will
+   * be considered the next state of the tree, and the change listeners will be
+   * notified.
+   *
+   * The base implementation only supports plain object actions. If you want to
+   * dispatch a promise, an observable, a thunk, or something else, you need to
+   * wrap your store creating function into the corresponding middleware. For
+   * example, see the documentation for the `redux-thunk` package. Even the
+   * middleware will eventually dispatch plain object actions using this method.
+   *
+   * @param {Object} action A plain object representing “what changed”. It is
+   * a good idea to keep actions serializable so you can record and replay user
+   * sessions, or use the time travelling Redux developer tools.
+   *
+   * @returns {Object} For convenience, the same action object you dispatched.
+   * Note that, if you use a custom middleware, it may wrap `dispatch()` to
+   * return something else (for example, a Promise you can await).
+   */
+  function dispatch(action) {
     invariant(
       isPlainObject(action),
       'Actions must be plain objects. Use custom middleware for async actions.'
@@ -50,11 +98,29 @@ export default function createStore(
     return action;
   }
 
+  /**
+   * Returns the reducer currently used by the store to calculate the state.
+   *
+   * It is likely that you will only need this function if you implement a hot
+   * reloading mechanism for Redux.
+   *
+   * @returns {Function} The reducer used by the current store.
+   */
   function getReducer() {
     return currentReducer;
   }
 
-  function replaceReducer(nextReducer: Reducer) {
+  /**
+   * Replaces the reducer currently used by the store to calculate the state.
+   *
+   * You might need this if your app implements code splitting and you want to
+   * load some of the reducers dynamically. You might also need this if you
+   * implement a hot reloading mechanism for Redux.
+   *
+   * @param {Function} nextReducer The reducer for the store to use instead.
+   * @returns {void}
+   */
+  function replaceReducer(nextReducer) {
     currentReducer = nextReducer;
     dispatch({ type: ActionTypes.INIT });
   }

src/index.js

@@ -1,50 +1,13 @@
-/* @flow */
-
-export type State = any;
-export type Action = Object;
-export type IntermediateAction = any;
-export type Dispatch = (a: Action | IntermediateAction) => any;
-export type Reducer<S, A> = (state: S, action: A) => S;
-export type ActionCreator = (...args: any) => Action | IntermediateAction;
-
-export type MiddlewareArgs = {
-  dispatch: Dispatch;
-  getState: () => State;
-};
-
-export type Middleware = (args: MiddlewareArgs) =>
-  (next: Dispatch) =>
-  Dispatch;
-
-export type Store = {
-  dispatch: Dispatch;
-  getState: () => State;
-  getReducer: () => Reducer;
-  replaceReducer: (nextReducer: Reducer) => void;
-  subscribe: (listener: () => void) => () => void;
-};
-
-export type CreateStore = (
-  reducer: Reducer,
-  initialState: State
-) => Store;
-
-export type HigherOrderStore = (
-  next: CreateStore
-) => CreateStore;
-
 import createStore from './createStore';
-import compose from './utils/compose';
 import combineReducers from './utils/combineReducers';
 import bindActionCreators from './utils/bindActionCreators';
 import applyMiddleware from './utils/applyMiddleware';
-import composeMiddleware from './utils/composeMiddleware';
+import compose from './utils/compose';
 
 export {
   createStore,
-  compose,
   combineReducers,
   bindActionCreators,
   applyMiddleware,
-  composeMiddleware
+  compose
 };

src/utils/applyMiddleware.js

@@ -1,42 +1,30 @@
-/* @flow */
-/*eslint-disable */
-import type {
-  Dispatch, Middleware, Reducer, State,
-  Store, CreateStore, HigherOrderStore
-} from '../index';
-/*eslint-enable */
-
 import compose from './compose';
-import composeMiddleware from './composeMiddleware';
 
 /**
- * Creates a higher-order store that applies middleware to a store's dispatch.
+ * Creates a higher-order store that applies middleware to the dispatch method
+ * of the Redux store. This is handy for a variety of tasks, such as expressing
+ * asynchronous actions in a concise manner, or logging every action payload.
+ *
+ * See `redux-thunk` package as an example of the Redux middleware.
+ *
  * Because middleware is potentially asynchronous, this should be the first
  * higher-order store in the composition chain.
- * @param {...Function} ...middlewares
- * @return {Function} A higher-order store
+ *
+ * @param {...Function} middlewares The middleware chain to be applied.
+ * @returns {Function} A higher-order store.
  */
-export default function applyMiddleware(
-  ...middlewares: Array<Middleware>
-): HigherOrderStore {
-  return (next: CreateStore) => (reducer: Reducer, initialState: State) => {
+export default function applyMiddleware(...middlewares) {
+  return (next) => (reducer, initialState) => {
     var store = next(reducer, initialState);
-    var middleware = composeMiddleware(...middlewares);
-    var composedDispatch = () => {};
-
-    function dispatch(action) {
-      return composedDispatch(action);
-    }
+    var dispatch = store.dispatch;
+    var chain = [];
 
     var middlewareAPI = {
       getState: store.getState,
-      dispatch
+      dispatch: (action) => dispatch(action)
     };
-
-    composedDispatch = compose(
-      middleware(middlewareAPI),
-      store.dispatch
-    );
+    chain = middlewares.map(middleware => middleware(middlewareAPI));
+    dispatch = compose(...chain, store.dispatch);
 
     return {
       ...store,

src/utils/bindActionCreators.js

@@ -1,14 +1,21 @@
-/* @flow */
-/*eslint-disable */
-import type { Dispatch } from '../index';
-/*eslint-enable */
-
 import mapValues from '../utils/mapValues';
 
-export default function bindActionCreators(
-  actionCreators: Object,
-  dispatch: Dispatch
-): Object {
+/**
+ * Turns an object whose values are action creators, into an object with the
+ * same keys, but with every function wrapped into a `dispatch` call so they
+ * may be invoked directly. This is just a convenience method, as you can call
+ * `store.dispatch(MyActionCreators.doSomething())` yourself just fine.
+ *
+ * @param {Object} actionCreators An object whose values are action creator
+ * functions. One handy way to obtain it is to use ES6 `import * as` syntax.
+ *
+ * @param {Function} dispatch The `dispatch` function available on your Redux
+ * store.
+ *
+ * @returns {Object} The object mimicking the original object, but with every
+ * action creator wrapped into the `dispatch` call.
+ */
+export default function bindActionCreators(actionCreators, dispatch) {
   return mapValues(actionCreators, actionCreator =>
     (...args) => dispatch(actionCreator(...args))
   );

src/utils/combineReducers.js

@@ -1,24 +1,35 @@
-/* @flow */
-/*eslint-disable */
-import type { Action, State, Reducer } from '../index';
-/*eslint-enable */
-
 import mapValues from '../utils/mapValues';
 import pick from '../utils/pick';
 import invariant from 'invariant';
 import { ActionTypes } from '../createStore';
 
-function getErrorMessage(key: String, action: Action): string {
+function getErrorMessage(key, action) {
   var actionType = action && action.type;
-  var actionName = actionType && `"${actionType}"` || 'an action';
+  var actionName = actionType && `"${actionType.toString()}"` || 'an action';
 
   return (
     `Reducer "${key}" returned undefined handling ${actionName}. ` +
     `To ignore an action, you must explicitly return the previous state.`
   );
 }
 
-export default function combineReducers(reducers: Object): Reducer {
+/**
+ * Turns an object whose values are different reducer functions, into a single
+ * reducer function. It will call every child reducer, and gather their results
+ * into a single state object, whose keys correspond to the keys of the passed
+ * reducer functions.
+ *
+ * @param {Object} reducers An object whose values correspond to different
+ * reducer functions that need to be combined into one. One handy way to obtain
+ * it is to use ES6 `import * as reducers` syntax. The reducers may never return
+ * undefined for any action. Instead, they should return their initial state
+ * if the state passed to them was undefined, and the current state for any
+ * unrecognized action.
+ *
+ * @returns {Function} A reducer function that invokes every reducer inside the
+ * passed object, and builds a state object with the same shape.
+ */
+export default function combineReducers(reducers) {
   var finalReducers = pick(reducers, (val) => typeof val === 'function');
 
   Object.keys(finalReducers).forEach(key => {
@@ -43,7 +54,7 @@ export default function combineReducers(reducers: Object): Reducer {
     );
   });
 
-  return function composition(state: State = {}, action: Action): State {
+  return function combination(state = {}, action) {
     return mapValues(finalReducers, (reducer, key) => {
       var newState = reducer(state[key], action);
       invariant(

src/utils/compose.js

@@ -1,10 +1,11 @@
-/* @flow */
-
 /**
- * Composes functions from left to right
- * @param  {...Function} funcs - Functions to compose
- * @return {Function}
+ * Composes functions from left to right.
+ *
+ * @param {...Function} funcs - The functions to compose.
+ * @returns {Function} A function that passes its only argument to the first of
+ * the `funcs`, then pipes its return value to the second one, and so on, until
+ * the last of the `funcs` is called, and its result is returned.
  */
-export default function compose(...funcs: Array<Function>): Function {
+export default function compose(...funcs) {
   return funcs.reduceRight((composed, f) => f(composed));
 }

src/utils/composeMiddleware.js

@@ -1,6 +1,8 @@
-/* @flow */
-
-export default function isPlainObject(obj: Object): boolean {
+/**
+ * @param {any} obj The object to inspect.
+ * @returns {boolean} True if the argument appears to be a plain object.
+ */
+export default function isPlainObject(obj) {
   if (!obj) {
     return false;
   }