redux-free-flow
What it does
It let's you write pure, composable and versatile redux store interactions (both sync and async) like this:
;;; { return ;}// laterstore;
Yes, dispatch({ type: "ERROR_INSUFFICIENT_FUNDS" })
is pure - it does not dispatch actions, instead it's an expression evaluates to some data structure to be interpreted later (when dispatched by redux
store). This small snippet of code does the following once dispatched:
- Use
getState
(byreadBalance
) to get account balance offromAccount
- Check if the account has enough funds to transfer
- If so, dispatches two actions,
withdraw
anddeposit
atomically - makes an api call to tell the server this transfer transaction has happened
- conclude everything if api response indicates a server-side success
- otherwise, rollback the entire transaction
- If so, dispatches two actions,
- If not enough funds, dispatches an error action
{ type: "ERROR_INSUFFICIENT_FUNDS" }
Example
How it Works
The inspirations of this enhancer are:
- Free Monad, DSL / Interpreter pattern
- Event Sourcing Systems
redux-saga
co
async-await
etc.- transactional semantics
dispatch
, effect
, rollback
etc are all functions that return data structures which encodes the shape and control flow of effectful computations (redux
store api calls). In fact, the underlying data structure here is a Free Monad. If you don't know what it is don't worry, for the purpose of using these library, they are just immutable objects with then
method. For example:
const callDispatch = ;const twiceDispatch = callDispatch;
You'd write these store interactions just like how you would write promise chains - and the final interaction when dispatched will do almost exactly what you think it does.
Furthermore, a handy generator oriented helper Do
is provided to make code more readable. Haskell
has do
notation, Scala
has for
comprehension, and javaScript has co
and async-wait
syntax for flattening out nested promise chains. Do
lets you use generator
s to rewrite the code above to:
const twiceDispatch = ;
- Note:
Do(function* { .. })
is no-longer pure asgenerators
are stateful, making the resulting interactions interpretable only once. It is better to wrapDo
calls inside a function, and every time you dispatch the same interaction, call the function again for a new iterator.
Comparisons with Other Libraries
- Isn't this like
redux-thunk
?
Kinda. redux-thunks
gives you the freedom to consult getState
and do multiple and possibly async dispatch
calls. But thunks
are effectful and not composable. You cannot easily take the return value of a thunk
and use it as inputs of other thunks
easily, nor can you rollback thunk
actions without big changes to reducer. This library gives you all the raw power of redux-thunk
but non of the effectful nastiness...
redux-saga
Think an DSL / interaction / free monad (I haven't come up a name yet...) as a one-time saga. It doesn't have access to actions from other dispatch calls, but the general idea is similar: declarative and composable async control flows.
redux-loop
DSL / Interactions / free monads are move expressive than redux-loop
Effects / Cmds
. They incorporate both read, sync dispatch and async effects in one unified framework. Oh, and rollbacks...
API
Installation and Integration:
yarn add redux-free-flow
; const store = ;// orconst store = createStorereducer preloadedState
** Note: This library assumes all actions are plain objects, it will not work with other middlewares and enhancers that gives you the ability to use non-plain-object actions (such as redux-thunk
, redux-promise
) . In other words, an action
must be something you reducer
can understand.
Core apis:
read
dispatch
effect
end
rollback
Don't worry too much about the type signature.
read
: Free DSL A
Given a select
function, read
produces a command to read value from store, "returned" value is select(store.getState())
, the value can be accessed like:
read(select)
.then(currentValue => { .. })
dispatch
: Free DSL Unit
dispatch
takes an plain object (action), and returns a command that dispatches the action when executed.
For example:
store.dispatch(
read(state => state.counter)
.then(counter => {
if (counter > 0) {
return dispatch({ type: DECREMENT });
}
return end;
})
)
This will dispatch an DECREMENT
action only if store's counter
value is positive. redux
takes dispatch
out of action creators from flux
, now I am putting it back in...
effect
effect(promiseFactory: () -> Promise A) : Free DSL A
effect
takes a function that returns a promise and stores it. When interpreted, the function gets called, and when the promise it returns resolves, the value becomes available to the next then
function in the DSL chain.
end
end :: Free DSL Unit
The termination of a transaction, end
is automatically assumed for any chain of commands, it the last one is not end
.
rollback
rollback :: Free DSL Unit
The most magical of them all. When encountered by the internal interpreter, all dispatched action from the given transaction so far will be taken out history as if they never happened! Other concurrent actions (and transactions) remain intact.
Performance
Dispatching a free monad switches redux store to a "event sourcing" mode. What it means is all actions dispatched (including vanilla ones) gets added to a queue (this is why rollback
is possible). If you have a long running or perpetual thing going on like this:
const forever =
You'd either running into a infinite loop (if everything is sync) or a async loop (if effect
is used like above) with memory leak from the action queue.
Is it production ready?
No.
It's a complex piece of machinery, there for sure are bugs. Also lots of edge case handling code is missing.