Support custom dispatchers

[gaearon]

Goals of this PR:

• Add a single powerful extension point
• Allow both Middleware all the things #55 and Implement middleware #6 to be implemented in userland

This PR does not try to solve middleware API or the middleware composition. Instead, it allows to implement #55 and #6 in the userland by separating “Redux instance” (the state holder) and the Dispatcher. By providing a custom Dispatcher, you can experiment with different composable middleware APIs without changing the core.

New definitions

The Dispatcher is a function responsible for turning actions into state changes. Its signature is (initialState, setState) => (action) => (). You won't use it directly, and will instead hand it off to the Redux instance.

The Redux instance is ignorant of how actions turn into state. It has no knowledge of dispatching, or stores. It is a facade for Redux, providing you getState and dispatch, and letting you specify an initial state for hydration.

The Redux library provides a default dispatcher that implements the current behavior with createDispatcher:

import { createRedux, createDispatcher, composeStores } from 'redux';
import * as stores from '../stores/index';

// Compose all your Stores into a single Store function with `composeStores`:
const store = composeStores(stores);

// Create a Dispatcher function for your composite Store:
const dispatcher = createDispatcher(store);

// Create a Redux instance using the dispatcher function:
const redux = createRedux(dispatcher);

The built-in Dispatcher

The default dispatcher looks like this:

export default function createDispatcher(store) {
  return function dispatcher(initialState, setState) {
    let state = store(initialState, {});
    setState(state);

    function dispatchSync(action) {
      state = store(state, action);
      setState(state);
      return action;
    }

    function dispatch(action) {
      return typeof action === 'function' ?
        action(dispatch, state) :
        dispatchSync(action);
    }

    return dispatch;
  };
}

As you can see, perform is no more. Now dispatch behaves exactly like perform used to behave because that's what the Dispatcher does.

Custom Dispatchers

To provide a custom dispatcher, just don't use createDispatcher and pass your own function instead with the same (initialState, setState) => (action) => () signature.

It doesn't even have to understand the concept of Stores. It may do something completely different—the only important part is that it has to translate the actions into the state updates.

Convenience API

Finally, this PR brings back a simpler convenience API for most people who don't need to customize the Dispatcher or the Store composition:

import { createRedux } from 'redux';
import * as stores from '../stores/index';

const redux = createRedux(stores);

[threepointone]

lovely!

(also, and not sure this makes sense... one can now compose dispatchers?)

[vslinko]

👍

[emmenko]

👍

[rpominov]

Solves all problems. 👍

[vslinko]

Hmm. Why dispatcher stores a copy of state? May be redux should pass getState into dispatcher?

export default function createDispatcher(store) {
  return function dispatcher(getState, setState) {
    setState(store(getState(), {}));

    function dispatchSync(action) {
      state = store(getState(), action);
      setState(state);
      return action;
    }

    function dispatch(action) {
      return typeof action === 'function' ?
        action(dispatch, state) :
        dispatchSync(action);
    }

    return dispatch;
  };
}

[tsingson]

great job.

[gaearon]

May be redux should pass getState into dispatcher?

I wanted “only the dispatcher may set the state” to be a hard constraint. If it's not true, it's much more difficult to implement transactions, as we saw in #55.

Having the dispatcher maintain the reference to state reinforces this idea—since it's the only thing that can change it, providing getState is unnecessary in my opinion.

[gaearon]

This change has a funny consequence!

Now I can write createReplayingDispatcher and change createDispatcher to createReplayingDispatcher while the code is running, and the dispatcher will be hot reloaded. Which means I don't even need transactions because I can just write an über dispatcher that switches between those folks with options like this:

const dispatcher = createUberDispatcher({ replay: true, log: true }); // can tweak options with hot reloading

[acdlite]

Sorry I'm just now looking at this, but yay! Looks great.

[gaearon]

@vslinko

I think you were right now about getState. Passing it instead of initialState makes the custom dispatchers composable. 👍

I'll change it to be (getState, setState) => (action) => () instead.