Docs: Added clarity re return value of store.dispatch

[tomatau]

Added some more information about the return value of store.dispatch.

It should be the dispatched action but could also be the return value of the middleware chain, such as a promise of the dispatched action

[ellbee]

The reason that it is specified solely as a plain object is explained in the Notes section below. Is there anything there you would suggest to change to make it clearer?

[tomatau]

True! Perhaps adding a "see notes"?

API references should be easy to lookup quickly - notes are easy to overlook.

[gaearon]

"Promise of dispatch action object" sounds very specific as if we enforce something like that. I'd just say "a Promise" there.

[tomatau]

I feel like the focus here should be on the end value being the action object. It gives middleware creators more direction and can improve consistency within the ecosystem.

[gaearon]

I don't think this is necessarily true at all. Async action creators often dispatch multiple actions. I don't think it makes sense to suggest it's the action that the Promise should resolve to.

[tomatau]

When middleware can return anything, it makes the return from store.dispatch more complicated and less type safe. Whereas the general pattern of return next(action) is very easy to interpret.

When multiple actions are dispatched, the middleware should be able to comfortably provide either:

• an action object
• an array/set of actions objects
• a promise of an action object
• stream/observable/iterable of action objects.

I don't see the down side to encouraging this?

[pburtchaell]

I agree that a standard return value of store.dispatch would be preferable. I would argue it ensures that middleware across the Redux ecosystem as a whole will work similarly in that aspect.

I don't think a standard return value should be required, but I think encouraging a standard would be beneficial. I say this because I also think that if it makes sense for a middleware to return a value other than the standard, e.g., a promise object, then that is acceptable. Maybe the update to the docs should express this?

[pburtchaell]

It may also be worth noting that this is coming from discussions at pburtchaell/redux-promise-middleware#39 and este/este#633.

[ellbee]

I think adding see notes is a improvement, so I'm going to merge this. Maybe for the standard return value it would be worth creating a standard like FSA which we could link to from the ecosystem page in docs?

[ellbee]

Oh, where are my manners? Thanks Tomatau!

[tomatau]

@ellbee Hah thanks, was a very trivial PR :)

I very like the idea of a standard with link in the docs -- just a github readme page should be enough. I don't see how any libraries could really help here, perhaps a middleware to check against the dispatch return from following middleware.