Split README into separate docs

Author: acdlite

docs/design-goals.md

@@ -0,0 +1,17 @@
+### Philosophy & Design Goals
+
+* You shouldn't need a book on functional programming to use Redux.
+* Everything (Stores, Action Creators, configuration) is hot reloadable.
+* Preserves the benefits of Flux, but adds other nice properties thanks to its functional nature.
+* Prevents some of the anti-patterns common in Flux code.
+* Works great in [universal (aka “isomorphic”)](https://medium.com/@mjackson/universal-javascript-4761051b7ae9) apps because it doesn't use singletons and the data can be rehydrated.
+* Doesn't care how you store your data: you may use JS objects, arrays, ImmutableJS, etc.
+* Under the hood, it keeps all your data in a tree, but you don't need to think about it.
+* Lets you efficiently subscribe to finer-grained updates than individual Stores.
+* Provides hooks for powerful devtools (e.g. time travel, record/replay) to be implementable without user buy-in.
+* Provides extension points so it's easy to [support promises](https://github.com/gaearon/redux/issues/99#issuecomment-112212639) or [generate constants](https://gist.github.com/skevy/8a4ffc3cfdaf5fd68739) outside the core.
+* No wrapper calls in your stores and actions. Your stuff is your stuff.
+* It's super easy to test things in isolation without mocks.
+* You can use “flat” Stores, or [compose and reuse Stores](https://gist.github.com/gaearon/d77ca812015c0356654f) just like you compose Components.
+* The API surface area is minimal.
+* Have I mentioned hot reloading yet?

docs/examples.md

@@ -0,0 +1,39 @@
+## Examples
+
+### Simple Examples
+
+Redux is distributed with a Counter and a TodoMVC example in its source code.
+
+First, clone the repo:
+
+```
+git clone https://github.com/gaearon/redux.git
+cd redux
+```
+
+Run the Counter example:
+
+```
+cd redux/examples/counter
+npm install
+npm start
+```
+
+Run the TodoMVC example:
+
+```
+cd ../todomvc
+npm install
+npm start
+```
+
+### Async and Universal Examples with Routing
+
+These async and [universal (aka “isomorphic”)](https://medium.com/@mjackson/universal-javascript-4761051b7ae9) examples using React Router should help you get started:
+
+* [redux-react-router-async-example](https://github.com/emmenko/redux-react-router-async-example): Work in progress. Semi-official. Only the client side. Uses React Router.
+* [react-redux-universal-hot-example](https://github.com/erikras/react-redux-universal-hot-example): Universal. Uses React Router.
+* [redux-example](https://github.com/quangbuule/redux-example): Universal. Uses Immutable, React Router.
+* [isomorphic-counter-example](https://github.com/khtdr/redux-react-koa-isomorphic-counter-example): Universal. A bare-bone implentation of the [counter example app](https://github.com/gaearon/redux/tree/master/examples/counter). Uses promises-middleware to interact with API via Koa on the server.
+
+Don’t be shy, add your own!

docs/getting-started.md

@@ -0,0 +1,71 @@
+### Actions
+
+```js
+// Still using constants...
+import { INCREMENT_COUNTER, DECREMENT_COUNTER } from '../constants/ActionTypes';
+
+// But action creators are pure functions returning actions
+export function increment() {
+  return {
+    type: INCREMENT_COUNTER
+  };
+}
+
+export function decrement() {
+  return {
+    type: DECREMENT_COUNTER
+  };
+}
+
+// Can also be async if you return a function
+export function incrementAsync() {
+  return dispatch => {
+    setTimeout(() => {
+      // Yay! Can invoke sync or async actions with `dispatch`
+      dispatch(increment());
+    }, 1000);
+  };
+}
+
+
+// Could also read state of a store in the callback form
+export function incrementIfOdd() {
+  return (dispatch, getState) => {
+    const { counter } = getState();
+
+    if (counter % 2 === 0) {
+      return;
+    }
+
+    dispatch(increment());
+  };
+}
+```
+
+### Stores
+```js
+// ... too, use constants
+import { INCREMENT_COUNTER, DECREMENT_COUNTER } from '../constants/ActionTypes';
+
+// what's important is that Store is a pure function,
+// and you can write it anyhow you like.
+
+// the Store signature is (state, action) => state,
+// and the state shape is up to you: you can use primitives,
+// objects, arrays, or even ImmutableJS objects.
+
+export default function counter(state = 0, action) {
+  // this function returns the new state when an action comes
+  switch (action.type) {
+  case INCREMENT_COUNTER:
+    return state + 1;
+  case DECREMENT_COUNTER:
+    return state - 1;
+  default:
+    return state;
+  }
+
+  // BUT THAT'S A SWITCH STATEMENT!
+  // Right. If you hate 'em, see the FAQ below.
+}
+```

docs/higher-order-stores.md

@@ -7,9 +7,9 @@ A higher-order store is a function that turns a store creating function into a n
 createStore => createStore'
 ```
 
-Look familiar? It's just like the signature for [middleware](middleware.md), only we're wrapping `createStore()` instead of `dispatch()`.
+Look familiar? It's just like the signature for [middleware](middleware.md), only we're wrapping `createStore()` instead of `dispatch()`. Like middleware, the key feature of higher-order stores is that they are composable.
 
-Higher-order stores are a pattern for creating composable Redux extensions. They're much the same as higher-order components in React. They can be as simple as `applyMiddleware()`, or as powerful as the Redux Devtools](https://github.com/gaearon/redux-devtools). There's no limit to the kinds of things you can create.
+Higher-order stores are much the same as higher-order components in React. They can be as simple as `applyMiddleware()`, or as powerful as the Redux Devtools](https://github.com/gaearon/redux-devtools). There's no limit to the kinds of extensions you can create.
 
 ## How it works
 

docs/middleware.md

@@ -1,4 +1,56 @@
-# Middleware
+Middleware
+==========
+
+A middleware in Redux is a function that turns a dispatching function into a new dispatching function:
+
+```
+dispatch => dispatch'
+```
+
+The key feature of middleware is that it is composable. Multiple middleware can be combined together, where each middleware requires no knowledge of the what comes before or after it in the chain.
+
+Usage
+=====
+
+To enable middleware in your Redux app, use `applyMiddleware()`.
+
+### `applyMiddleware(...middlewares)`
+
+This function returns a [higher-order store](higher-order store). You don't need to worry about that if you're not interested — here's how you use it:
+
+```js
+const store = applyMiddleware(thunk, promise, observable)(createStore)(reducer);
+```
+
+Yes, you read that correctly. If this looks strange to you, it may help to break the process down into multiple steps:
+
+```js
+const newCreateStore = applyMiddleware(thunk, promise, observable)(createStore);
+const store = newCreateStore(reducer);
+```
+
+If you 
+
+How it works
+============
+
+```js
+const newDispatch = thunk(promise(observable(dispatch)));
+// Or
+const newDispatch = compose(thunk, promise, observable, dispatch);
+```
+
+`compose` performs function composition. It is the same as `compose()` in underscore or lodash.
+
+You can also use `composeMiddleware()`, which is similar to `compose()` except instead of creating a dispatching function, it creates a middleware function:
+
+```js
+const middleware = composeMiddleware(thunk, promise, observable);
+const newDispatch = compose(middleware, dispatch);
+// Or simply
+const newDispatch = compose(dispatch);
+```
+
 
 A middleware is a function that wraps the `dispatch()` method, or another middleware. For example:
 

docs/react.md

@@ -0,0 +1,99 @@
+### Components
+
+#### Dumb Components
+
+```js
+// The dumb component receives everything using props:
+import React, { PropTypes } from 'react';
+
+export default class Counter {
+  static propTypes = {
+    increment: PropTypes.func.isRequired,
+    decrement: PropTypes.func.isRequired,
+    counter: PropTypes.number.isRequired
+  };
+
+  render() {
+    const { increment, decrement, counter } = this.props;
+    return (
+      <p>
+        Clicked: {counter} times
+        {' '}
+        <button onClick={increment}>+</button>
+        {' '}
+        <button onClick={decrement}>-</button>
+      </p>
+    );
+  }
+}
+```
+
+#### Smart Components
+
+```js
+// The smart component may observe stores using `<Connector />`,
+// and bind actions to the dispatcher with `bindActionCreators`.
+
+import React from 'react';
+import { bindActionCreators } from 'redux';
+import { Connector } from 'redux/react';
+import Counter from '../components/Counter';
+import * as CounterActions from '../actions/CounterActions';
+
+// You can optionally specify `select` for finer-grained subscriptions
+// and retrieval. Only when the return value is shallowly different,
+// will the child component be updated.
+function select(state) {
+  return { counter: state.counter };
+}
+
+export default class CounterApp {
+  render() {
+    return (
+      <Connector select={select}>
+        {({ counter, dispatch }) =>
+          /* Yes this is child as a function. */
+          <Counter counter={counter}
+                   {...bindActionCreators(CounterActions, dispatch)} />
+        }
+      </Connector>
+    );
+  }
+}
+```
+
+#### Decorators
+
+The `@connect` decorator lets you create smart components less verbosely:
+
+```js
+import React from 'react';
+import { bindActionCreators } from 'redux';
+import { connect } from 'redux/react';
+import Counter from '../components/Counter';
+import * as CounterActions from '../actions/CounterActions';
+
+@connect(state => ({
+  counter: state.counter
+}))
+export default class CounterApp {
+  render() {
+    const { counter, dispatch } = this.props;
+    // Instead of `bindActionCreators`, you may also pass `dispatch` as a prop
+    // to your component and call `dispatch(CounterActions.increment())`
+    return (
+      <Counter counter={counter}
+               {...bindActionCreators(CounterActions, dispatch)} />
+    );
+  }
+}
+```
+
+### React Native
+
+To use Redux with React Native, just replace imports from `redux/react` with `redux/react-native`:
+
+```js
+import { bindActionCreators } from 'redux';
+import { Provider, Connector } from 'redux/react-native';
+```

docs/store.md

@@ -0,0 +1,27 @@
+### Initializing Redux
+
+The simplest way to initialize a Redux instance is to give it an object whose values are your Store functions, and whose keys are their names. You may `import *` from the file with all your Store definitions to obtain such an object:
+
+```js
+import { createRedux } from 'redux';
+import { Provider } from 'redux/react';
+import * as stores from '../stores/index';
+
+const redux = createRedux(stores);
+```
+
+Then pass `redux` as a prop to `<Provider>` component in the root component of your app, and you're all set:
+
+```js
+export default class App {
+  render() {
+    return (
+      <Provider redux={redux}>
+        {() =>
+          <CounterApp />
+        }
+      </Provider>
+    );
+  }
+}
+```

docs/universal-rendering.md

@@ -0,0 +1,16 @@
+### Running the same code on client and server
+
+The `redux` instance returned by `createRedux` also has the `dispatch(action)`, `subscribe()` and `getState()` methods that you may call outside the React components.
+
+You may optionally specify the initial state as the second argument to `createRedux`. This is useful for hydrating the state you received from running Redux on the server:
+
+```js
+// server
+const redux = createRedux(stores);
+redux.dispatch(MyActionCreators.doSomething()); // fire action creators to fill the state
+const state = redux.getState(); // somehow pass this state to the client
+
+// client
+const initialState = window.STATE_FROM_SERVER;
+const redux = createRedux(stores, initialState);
+```