Using effects in re-frame

In re-frame, we'd like to use pure event handlers because they provide some important advantages, (mentioned in a previous post about coeffects in re-frame): local reasoning, easier testing, and events replay-ability.

However, as we said, to build a program that does anything useful, it's inevitable to have some side-effects and/or side-causes. So, there will be many cases in which event handlers won't be pure functions.

We also saw how using coeffects in re-frame allows to have pure event handlers in the presence of side-causes.

In this post, we'll focus on side-effects:

If a function modifies some state or has an observable interaction with calling functions or the outside world, it no longer behaves as a mathematical (pure) function, and then it is said that it does side-effects.

Let's see some examples of event handlers that do side-effects (from a code animating the evolution of a cellular automaton):

	(ns cellular-animation.handlers
	(:require
	[cellular-animation.evolution :as evolution]
	[re-frame.core :as re-frame]))
	(defn evolve [db _]
	(if (:evolving db)
	(let [db (update
	db :automaton-states
	(partial
	evolution/evolve (:rule db)))]
	(js/setTimeout
	(fn [] (re-frame/dispatch [:evolve]))
	100) ; <- side-effect!
	db)
	db))
	(defn start-stop-evolution [db _]
	(let [db (update db :evolving not)]
	(re-frame/dispatch [:evolve]) ; <- side-effect!
	db))

view raw impure_untestable_handlers.cljs hosted with ❤ by GitHub

	(ns cellular-animation.register-handlers
	(:require
	[re-frame.core :as re-frame]
	[cellular-animation.db :as db]
	[cellular-animation.handlers :as handlers]))
	(re-frame/reg-event-db
	:initialize-db
	(fn [_ _]
	db/default-db))
	(re-frame/reg-event-db
	:evolution-started-or-stopped
	handlers/start-stop-evolution)
	(re-frame/reg-event-db
	:evolve
	handlers/evolve)

view raw register_impure_untestable_handlers.cljs hosted with ❤ by GitHub

These event handlers, registered using reg-event-db, are impure because they're doing a side-effect when they dispatch the :evolve event. With this dispatch, they are performing an action at a distance, which is in a way a hidden output of the function.

These impure event handlers are hard to test. In order to test them, we'll have to somehow spy the calls to the function that is doing the side-effect (the dispatch). Like in the case of side-causes from our previous post, there are many ways to do this in ClojureScript, (see Isolating external dependencies in Clojure), only that, in this case, the code required to test the impure handler will be a bit more complex, because we need to keep track of every call made to the side-effecting function.

In this example, we chose to make explicit the dependency that the event handler has on the side-effecting function, and inject it into the event handler which becomes a higher order function. Actually, we injected a wrapper of the side-effecting function in order to create an easier interface.

Notice how the event handlers, evolve and start-stop-evolution, now receive as its first parameter the function that does the side-effect, which are dispatch-later-fn and dispatch, respectively.

	(ns cellular-animation.handlers
	(:require
	[cellular-animation.evolution :as evolution]))
	(defn evolve [dispatch-later-fn db _]
	(if (:evolving db)
	(let [db (update
	db :automaton-states
	(partial evolution/evolve (:rule db)))]
	(dispatch-later-fn :evolve 100)
	db)
	db))
	(defn start-stop-evolution [dispatch-fn db _]
	(let [db (update db :evolving not)]
	(dispatch-fn :evolve)
	db))

view raw testable-impure-handlers.cljs hosted with ❤ by GitHub

When the event handlers are registered with the events they handle, we partially apply them, in order to pass them their corresponding side-effecting functions, dispatch-later for evolve and dispatch for start-stop-evolution:

	(ns cellular-animation.register-handlers
	(:require
	[re-frame.core :as re-frame]
	[cellular-animation.db :as db]
	[cellular-animation.handlers :as handlers]
	[cellular-animation.dispatchers :as dispatchers]))
	(re-frame/reg-event-db
	:initialize-db
	(fn [_ _]
	db/default-db))
	(re-frame/reg-event-db
	:evolution-started-or-stopped
	(partial
	handlers/start-stop-evolution
	dispatchers/dispatch))
	(re-frame/reg-event-db
	:evolve
	(partial
	handlers/evolve
	dispatchers/dispatch-later))

view raw register-testable-impure-handlers.cljs hosted with ❤ by GitHub

These are the wrapping functions:

	(ns cellular-animation.dispatchers
	(:require
	[re-frame.core :as re-frame]))
	(defn dispatch [event]
	(re-frame/dispatch [event]))
	(defn dispatch-later [event ms]
	(js/setTimeout
	(fn [] (dispatch event))
	ms))

view raw dispatchers.cljs hosted with ❤ by GitHub

Now when we need to test the event handlers, we use partial application again to inject the function that does the side-effect, except that, in this case, the injected functions are test doubles, concretely spies which record the parameters used each time they are called:

	(ns cellular-animation.handlers-test
	(:require
	[cljs.test :refer-macros [deftest testing is]]
	[cellular-animation.handlers :as handlers]
	[cellular-animation.rules :as rules]))
	(defn- make-spy [args]
	(fn [& parameters] (swap! args conj parameters)))
	(deftest evolve-handler-test
	(testing
	"when the automaton is evolving it calls itself after changing its state"
	(let [initial-states [[1]]
	expected-states [[0 1 0] [1 0 1]]
	db {:automaton-states initial-states
	:rule rules/rule-90
	:evolving true}
	args (atom [])
	dispatch-later-fn (make-spy args)
	evolve (partial
	handlers/evolve dispatch-later-fn)
	resulting-db (evolve db :not-used-event)]
	(is (= resulting-db
	(merge db {:automaton-states expected-states})))
	(let [first-call-args (nth @args 0)]
	(is (= (count first-call-args) 2))
	(is (= (first first-call-args) :evolve))
	(is (= (second first-call-args) 100))))))
	(testing
	"when the automaton is not evolving it does not change its state"
	(let [db :some-db
	args (atom [])
	dispatch-later-fn (make-spy args)
	evolve (partial
	handlers/evolve dispatch-later-fn)
	resulting-db (evolve db :not-used-event)]
	(is (= resulting-db db))
	(is (zero? (count @args)))))
	(deftest start-stop-evolution-handler-test
	(testing
	"when the automaton is evolving it stops the evolution"
	(let [db {:evolving true}
	args (atom [])
	dispatch (make-spy args)
	start-stop-evolution (partial
	handlers/start-stop-evolution dispatch)
	resulting-db (start-stop-evolution db :not-used-event)]
	(is (= resulting-db (assoc db :evolving false)))
	(let [first-call-args (nth @args 0)]
	(is (= (count first-call-args) 1))
	(is (= (first first-call-args) :evolve)))))
	(testing
	"when the automaton is not evolving it starts the evolution"
	(let [db {:evolving false}
	args (atom [])
	dispatch (make-spy args)
	start-stop-evolution (partial
	handlers/start-stop-evolution dispatch)
	resulting-db (start-stop-evolution db :not-used-event)]
	(is (= resulting-db (assoc db :evolving true)))
	(let [first-call-args (nth @args 0)]
	(is (= (count first-call-args) 1))
	(is (= (first first-call-args) :evolve))))))

view raw testable-impure-handlers-test.cljs hosted with ❤ by GitHub

This is very similar to what we had to do to test event handlers with side-causes in re-frame before having effectful event handlers (see previous post). However, the code for spies is a bit more complex than the one for stubs.

Using test doubles makes the event handler testable again, but it's still impure, so we have not only introduced more complexity to test it, but also, we have lost the two other advantages cited before: local reasoning and events replay-ability.

Since re-frame's 0.8.0 (2016.08.19) release, this problem has been solved by introducing the concept of effects and coeffects.

Whereas, in our previous post, we saw how coeffects can be used to track what your program requires from the world (side-causes), in this post, we'll focus on how effects can represent what your program does to the world (side-effects). Using effects, we'll be able to write effectful event handlers that keep being pure functions.

Let's see how the previous event handlers look when we use effects:

	(ns cellular-animation.handlers
	(:require
	[cellular-animation.evolution :as evolution]))
	(defn evolve [{:keys [db]} _]
	(if (:evolving db)
	{:db (update db :automaton-states
	(partial evolution/evolve (:rule db)))
	:dispatch-later [{:ms 100 :dispatch [:evolve]}]}
	{:db db}))
	(defn start-stop-evolution [{:keys [db]} _]
	{:db (update db :evolving not)
	:dispatch [:evolve]})

view raw pure-effectful-handlers.cljs hosted with ❤ by GitHub

Notice how the event handlers are not side-effecting anymore. Instead, each of the event handlers returns a map of effects which contains several key-value pairs. Each of these key-value pairs declaratively describes an effect using data. re-frame will use that description to actually do the described effects. The resulting event handlers are pure functions which return descriptions of the side-effects required.

In this particular case, when the automaton is evolving, the evolve event handler is returning a map of effects which contains two effects represented as key/value pairs. The one with the :db key describes the effect of resetting the application state to a new value. The other one, with the :dispatch-later key describes the effect of dispatching the :evolve event after waiting 100 microseconds. On the other hand, when the automaton is not evolving, the returned effect describes that the application state will be reset to its current value.

Something similar happens with the start-stop-evolution event handler. It returns a map of effects also containing two effects. The one with the :db key describes the effect of resetting the application state to a new value, whereas the one with the :dispatch key describes the effect of immediately dispatching the :evolve event.

The effectful event handlers are pure functions that accept two arguments, being the first one a map of coeffects, and return, after doing some computation, an effects map which is a description of all the side-effects that need to be done by re-frame.

As we saw in the previous post about coeffectts, re-frame's effectful event handlers are registered using the reg-event-fx function:

	(ns cellular-animation.register-handlers
	(:require
	[re-frame.core :as re-frame]
	[cellular-animation.db :as db]
	[cellular-animation.handlers :as handlers]))
	(re-frame/reg-event-db
	:initialize-db
	(fn [_ _]
	db/default-db))
	(re-frame/reg-event-fx
	:evolution-started-or-stopped
	handlers/start-stop-evolution)
	(re-frame/reg-event-fx
	:evolve
	handlers/evolve)

view raw register-pure-effectfull-handlers.cljs hosted with ❤ by GitHub

These are their tests:

	(ns cellular-animation.handlers-test
	(:require
	[cljs.test :refer-macros [deftest testing is]]
	[cellular-animation.handlers :as handlers]
	[cellular-animation.rules :as rules]))
	(deftest evolve-handler-test
	(testing
	"when the automaton is evolving it calls itself after changing its state"
	(let [initial-states [[1]]
	expected-states [[0 1 0] [1 0 1]]
	db {:automaton-states initial-states
	:rule rules/rule-90
	:evolving true}]
	(is (= (handlers/evolve {:db db} [])
	{:db (merge db {:automaton-states expected-states})
	:dispatch-later [{:ms 100 :dispatch [:evolve]}]}))))
	(testing
	"when the automaton is not evolving it does not change its state"
	(let [db {:automaton-states :not-used-initial-states
	:rule :not-used-rule
	:evolving false}]
	(is (= (handlers/evolve {:db db} []) {:db db})))))
	(deftest start-stop-evolution-test
	(testing
	"when the automaton is evolving it stops the evolution"
	(let [db {:evolving true}]
	(is (= (handlers/start-stop-evolution {:db db} [])
	{:db (assoc db :evolving false)
	:dispatch [:evolve]}))))
	(testing
	"when the automaton is not evolving it starts the evolution"
	(let [db {:evolving false}]
	(is (= (handlers/start-stop-evolution {:db db} [])
	{:db (assoc db :evolving true)
	:dispatch [:evolve]})))))

view raw testing-pure-effectfull-handlers.cljs hosted with ❤ by GitHub

Notice how by using effects we don't need to use tests doubles anymore in order to test the event handlers. These event handlers are pure functions, so, besides easier testing, we get back the advantages of local reasoning and events replay-ability.

:dispatch and :dispatch-later are builtin re-frame effect handlers already defined. It's possible to create your own effect handlers. We'll explain how and show an example in a future post.