-
-
Notifications
You must be signed in to change notification settings - Fork 714
Effectful Event Handlers
This page describes features in the v0.8.0 release of re-frame. Comment and discussion on this feature is happening here. Please feel free to correct any typos and mistakes. Thanks.
This tutorial shows you how to implement pure event handlers that side-effect. Yes, a surprising claim.
In the process, via the explanations provided,
you'll also get insight into how you might use an alternative to app-db
, like
perhaps a DataScript database.
Not all event handlers are pure. The great majority are but there'll always be some handlers which need to side-effect.
First, the good...
Here we register a pure event handler:
(reg-event
:my-event
(fn [db [_ a]] ;; <--- lovely and pure
(assoc db :flag true)))
That fn
handler is passed values, returns a value. No side-effects.
Now, to the more troublesome...
This handler is not pure:
(reg-event
:my-event
(fn [db [_ a]]
(dispatch [:do-something-else 3]) ;; oops, side-effect
(assoc db :flag true)))
That handler fn
is passed values, returns a value, but ... it
has a side-effect. That dispatch
queues up another event to be processed. It changes the world.
And, this is not pure either:
(reg-event
:my-event
(fn [db [_ a]]
(GET "http://json.my-endpoint.com/blah" ;; dirty great big side-effect
{:handler #(dispatch [:process-response %1])
:error-handler #(dispatch [:bad-response %1])})
(assoc db :flag true)))
Sure, this approach works. But that dirty great big side-effect doesn't come for free.
Both of those impure event handlers will work. So what's the problem?
A re-frame application proceeds step by step, like a reduce. From the README:
at any one time, the value in app-db is the result of performing a reduce over the entire collection of events dispatched in the app up until that time. The combining function for this reduce is the set of registered event handlers.
Such a collection of events is replay-able which is a dream for debugging and testing. But only
when all the handlers are pure. Handlers with side-effects (like that HTTP GET, or the dispatch
) pollute the
replay process, inserting extra events, etc, which ruins the process.
And, it is hard to test these impure handlers. Did the handler GET the right URL? Did it dispatch the right event? Now we have to start mocking things out. Everything gets harder.
So, impure handlers cause a small collection of irritating paper cuts. It isn't a disaster, but we'd like to do better.
Side-effecting event handlers are inevitable.
Event handlers implement the control logic of your re-frame app, and that means dealing with the mutative world of servers, databases, windows.location, cookies, etc.
There's just no getting around that. So it sounds like we're stuck. No solution?
Well, luckily a small twist in the tale makes a profound difference. Instead of creating event handlers which do side-effects, we'll instead get them to cause side-effects.
Above, I claimed that this fn
event handler was pure:
(reg-event
:my-event
(fn [db _]
(assoc db :flag true)))
Takes a db
value, returns a db
value. No side-effects. Pure!
All true, but ... this purity is only possible because re-frame is doing the necessary side-effecting.
Wait on. What "necessary side-effecting"?
Well, app-db
is a ratom, right? It contains the application state and, after each event handler runs, it must be reset!
to the newly returned value. re-frame's steps for each event are:
- extract the value (a map) from
app-db
(a ratom) - call the registered event handler with this
db
value as the first argument -
reset!
the returned value back intoapp-db
So, we get to live in our ascetic functional world because re-frame is looking after the "necessary side-effects" on app-db
.
Turns out it's the same pattern with Reagent/React.
We get to write a nice pure component:
(defn say-hi
[name]
[:div "Hello " name])
and Reagent/React mutates the DOM for us. The framework is looking after the "necessary side-effects".
Pause and look back at say-hi
. I'd like you to view it through the following lens: it is a pure
function which returns a description of the side-effects required. It says: add a div element
to the DOM.
Notice that the description is declarative. We don't tell React how to do it.
Notice also that it is data. Hiccup is just vectors and maps.
This is a big, important concept. While we can't get away from certain side-effects, we can program using pure functions which describe side-effects, declaratively, in data and let the backing framework look after the "doing" of them. Efficiently. Discreetly.
Let's use this pattern to solve the side-effecting handler problem.
From here, two steps:
- Work out how event handlers can declaratively describe side-effects, in data.
- Work out how re-frame can do the "necessary side-effecting". Efficiently and discreetly.
So, how would it look if event handlers returned side-effects, declaratively, in data?
Here is an impure handler:
(reg-event
:my-event
(fn [db [_ a]]
(dispatch [:do-something-else 3]) ;; Eeek, side-effect
(assoc db :flag true)))
Here it is re-written so as to be pure:
(reg-event
:my-event
(fn [db [_ a]]
{:db (assoc db :flag true) ;; side-effect we want on db
:dispatch [:do-something-else 3]})) ;; side-effect from dispatching
The handler is returning a data structure which describes two side-effects:
- update app-db (application state) with this new
db
value - dispatch an event
Above, the impure handler did a dispatch
side-effect, while the pure handler described
a dispatch
side-effect.
The impure way:
(reg-event
:my-event
(fn [db [_ a]]
(GET "http://json.my-endpoint.com/blah" ;; dirty great big side-effect
{:handler #(dispatch [:process-response %1])
:error-handler #(dispatch [:bad-response %1])})
(assoc db :flag true)))
the pure, descriptive way:
(reg-event
:my-event
(fn [db [_ a]]
{:http {:method :get
:url "http://json.my-endpoint.com/blah"
:on-success [:process-blah-response]
:on-fail [:failed-blah]}
:db (assoc db :flag true)}))
Again, the old way did a side-effect (Booo!) and the new way describes, declaratively, in data, the side-effects required (Yaaa!).
Time for the next step.
So far we've been experimenting with side-effects
but that's only one half of the picture. There
are actually two concepts at play here:
- Effects - what your event handler does to the world (aka side-effects)
- Coeffects - what your event handler requires from the world (aka side-causes)
So now we'll talk about the 2nd part: coeffects
Above, I proposed this event handler:
(reg-event
:my-event
(fn [db [_ a]]
{:db (assoc db :flag true) ;; side-effect we want on db
:dispatch [:do-something-else 3]})) ;; side-effect from dispatching
I'd now like to change the name of the first handler argument from db
to world
,
and pass in this structure {:db db}
. Ie. the argument is now a map, and the
key :db
has the value in app-db
.
So, we rewrite our handler like this:
(reg-event
:my-event
(fn [world [_ a]] ;; world, not db as parameter
{:db (assoc (:db world) :flag true)
:dispatch [:do-something-else 3]}))
or perhaps like this (shrug):
(reg-event
:my-event
(fn [world [_ a]] ;; world, not db as parameter
(-> world ;; world is {:db db}
(assoc-in [:db :flag] true)
(assoc-in [:dispatch] [:do-something-else 3]))))
So the 1st parameter to the event handler, world
, is the "state of the world" or the
"computational context" in which the handler is to run. It is the coeffect.
This rewrite means that world
can now be more than db
. It can include whatever other "computational context"
the handler needs to perform its computation. Most of the time,
that's just what's in app-db, but "other aspects of the computation context" are possible.
For example, what if a handler needed to know the current datetime? Or, it needed a random number? Or, what if some state was stored in a DataScript database?
All possible, but you must know how "new worlds" are created ...
A "new world" is created each and every time an event handler is run. A brand spanking new world. And it is the event handler's middleware stack which makes that happen.
This can be a surprise to even experienced re-frame users. After all, look at this event handler registration ... there's no apparent middleware:
(reg-event
:my-event ;; no apparent middleware !!!!!
(fn [db _]
(assoc db :flag true)))
But, don't be fooled. re-frame.core/reg-event
exists for only one
reason: to install the pure
middleware on all your handlers in the
right place within the stack. Here's proof
It is pure
middleware which does the important work. First, it takes the value out of
app-db
, makes it "the world" by providing
it to the event handler as the first argument and then, after the handler returns, it is again
pure
which uses reset!
to mutate app-db
.
So,
pure
is that bit of re-frame which does BOTH effects and coeffects. It obtains and providesdb
to an event handler and, afterwards, it does the "necessary side-effecting" to put data back intoapp-db
.
While pure
is central, re-frame's other middleware can also contribute to
effects and coeffects. For example, undoable
, snapshots the value in app-db
. And after
is used in the todomvc
example to write out to LocalStore.
So, within re-frame, effects and coeffects are done with middleware. We're now going to up the ante a bit.
So, how are we going?
Earlier, I presented a two step plan:
- Work out how event handlers can declaratively describe side-effects, in data.
- Work out how re-frame can action these side-effecting descriptions, efficiently and discreetly
We have a solution for 1.
And, regarding point 2, we now know that middleware is the answer, somehow.
Let's give this new middleware a name: fx
- (effects, geddit?)
Below I provide a specific solution for fx
but before we get there:
- remember, you can write your own middleware. It isn't hard.
-
fx
is definitely not the only way to do this.
fx
will be an alternative for pure
.
You will continue to use pure
for regular
handlers whose effects and coeffects are limited to app-db
. No change there.
But you will use fx
for event handlers which need additional effects and coeffects.
pure
is largely invisible because it gets "installed" by re-frame.core/reg-event
. So too it will be for fx
.
A new registration function, re-frame.core/reg-event-fx
(notice that -fx
on the end), will invisibly add fx
to the middleware stack of the registered handler.
Aside: remember that each event handler has its own middleware stack. So, some can have a pure
stack, and some fx
stacks.
Use will look like this:
(reg-event-fx ;; <-- use alternative registration (-fx on the end)
:my-event
(fn [world [_ a]] ;; world, instead of db
{:db (assoc (:db world) :flag a)
:dispatch [:do-something-else 3]})) ;; return effects
Aside: Instead of fx
I almost named it io
, which is a nod towards Haskell.
The language. Not James Haskell, the current
English Rugby openside breakaway, who I often claim is functional but lazy. My Rugby
friends have no idea what I'm talking about - "Mike, you're being too harsh.
He's in career-best form". Honestly, its pearls before swine.
fx
will need to:
- provide a
world
of{:db db}
. This is what the rest of the middleware stack will see, including the handler being registered - action the side effects described in the data returned by the handler
Here is an initial sketch of fx
in code:
(defn fx
[handler]
(fn io-handler
[app-db event-vec]
(let [world {:db @app-db}
result (handler world event-vec)] ;; call the event handler with world
; HERE IS WHERE WE ACTION THE EFFECTS in result
(if-let [db (:db result)]
(reset! app-db db))))
If writing middleware is a mystery to you, do not be alarmed. Just know that we must now
solve a problem: how should fx
action the side effects returned by an event handler.
fx
may get a handler return
value like:
{:db X
:http Y
:dispatch Z}
Actioning the :db
part would be straightforward. But
what about :http
and :dispatch
? And what to do if result
contains the key :abc
? The set of possible effects is open ended.
re-frame provides a plugable way of registering handlers for effects: reg-fx
. You nominate a handler which will action the side effects described by a key in an effects map.
Example use:
(re-frame.core/reg-fx
:http ;; if the key :http is found in an effect map, then ...
(fn [val] ;; ... action it via this handler function. "val" is the value of the key.
....))
So, to process an effects map, fx
finds all the keys in the map (:http :dispatch :db ?), looks up the associated handler for each, and calls these handlers, passing in the value of that key as the one argument.
Just to be clear, if the returned effects looked like:
{:db {}
:dispatch [:they-said-yes]
:http {:method :get
:url "http://google.com/secret-dark-web/naughty-bits"}}
Then fx
would handle :http
by calling the registered handler with one argument:
{:method :get
:url "http://google.com/secret-dark-web/naughty-bits"}
There isn't an ordering.
At this point, fx
does not allow you to control the order in which side effects occur. It is arbitrary. If you feel you need ordering - really need it - then please open an issue and explain the usecase. Ordering isn't in fx
currently, because we don't have a usecase.
If it were to be needed, it might be handled by:
- allowing metadata to be added to
:effects
map indicating ordering. - by perhaps allowing event handlers to return an
array-map
to provide an ordering of effects?
Perhaps allow for reg-fx
to optionally supply two functions:
- a pre-process fn <--- new
- the handler as already discussed.
The pre-process fn would take a context
argument and return a context
. In this way, the pre-process
fn could do any necessary rework of :effects
, including adding metadata about sorting. A lot of possibilities. But not needed yet. And it can be added later as usecases appear.
You don't always want effects to be actioned. Sometimes, if you are testing or debugging, you want effects to become noops.
Here's what a noop effects handler would look like:
(defn fx-noop [val])
Here's how :http
would be turned into a noop
(re-frame.core/reg-fx :http noop) ;; handler now does nothing
XXX make reg-fx return the previous handler, so it can be reinstated?
XXX or should this be done in a with-redefs
kinda way?
XXX list of standard effects.
Ramblings follow. Don't read.
Some candidate effects:
- dispatch
- flush-dom (force dom writes)
- undo
- localstore writes
- database queries (rethinkdb) ?
- http get or post
- cookies
- event sniffing
XXX how would you do multiple GET ? Multiple dispatches? Give a vector I guess
XXX should they be given the entire returned value, or just their part of the try?
Deprecated Tutorials:
Reagent: