re-frame/docs/Effects.md

358 lines
11 KiB
Markdown
Raw Normal View History

2016-08-19 05:32:51 +00:00
## Effects
2016-08-12 13:47:20 +00:00
About 10% of the time, event handlers need to cause side effects.
This tutorial explains how side effects are actioned,
how you can create your own side effects, and how you can
2016-08-15 01:56:03 +00:00
make side effects a noop in event replays.
> imperative programming is a big pile of do <br>
> &nbsp; &nbsp; -- @stuarthalloway
2016-08-12 13:47:20 +00:00
2016-08-13 06:11:11 +00:00
## Table Of Contexts
* [Where Effects Come From](#where-effects-come-from)
* [The Effects Map](#the-effects-map)
* [Infinite Effects](#infinite-effects)
* [Extensible Side Effects](#extensible-side-effects)
* [Writing An Effect Handler](#writing-an-effect-handler)
* [:db Not Always Needed](#-db-not-always-needed)
* [What Makes This Work?](#what-makes-this-work-)
* [Order Of Effects?](#order-of-effects-)
2016-08-15 08:11:28 +00:00
* [Effects With No Data](#effects-with-no-data)
2016-08-19 05:32:51 +00:00
* [Testing And Noops](#testing-and-noops)
* [Builtin Effect Handlers](#builtin-effect-handlers)
2016-08-13 06:11:11 +00:00
+ [:dispatch-later](#-dispatch-later)
+ [:dispatch](#-dispatch)
+ [:dispatch-n](#-dispatch-n)
+ [:deregister-event-handler](#-deregister-event-handler)
+ [:db](#-db)
2016-08-12 13:47:20 +00:00
### Where Effects Come From
2016-08-19 05:32:51 +00:00
When an event handler is registered via `reg-event-fx`, it must return effects.
2016-08-12 13:47:20 +00:00
Like this:
```clj
2016-08-15 01:56:03 +00:00
(reg-event-fx ;; -fx registration, not -db registration
2016-08-12 13:47:20 +00:00
:my-event
2016-08-19 05:32:51 +00:00
(fn [cofx [_ a]] ;; 1st argument is coeffects, instead of db
{:db (assoc (:db cofx) :flag a)
2016-08-12 13:47:20 +00:00
:dispatch [:do-something-else 3]})) ;; return effects
```
`-fx` handlers return a description of the side-effects required, and that description is a map.
### The Effects Map
An effects map contains instructions.
2016-08-15 08:11:28 +00:00
Each key/value pair in the map is one instruction - the `key` uniquely identifies
the particular side effect required, and the `value` for that `key` provides
2016-08-19 05:32:51 +00:00
further data. The structure of `value` is different for each side-effect.
2016-08-12 13:47:20 +00:00
2016-08-14 04:42:32 +00:00
Here's the two instructions from the example above:
2016-08-12 13:47:20 +00:00
```cljs
2016-08-16 14:08:30 +00:00
{:db (assoc db :flag a) ;; side effect on app-db
:dispatch [:do-something-else 3]} ;; dispatch this event
2016-08-12 13:47:20 +00:00
```
2016-08-19 05:32:51 +00:00
The `:db` `key` instructs that "app-db" should be `reset!` to the
`value` supplied.
2016-08-19 05:32:51 +00:00
And the `:dispatch` `key` instructs that an event should be
2016-08-15 08:11:28 +00:00
dispatched. The `value` is the vector to dispatch.
2016-08-12 13:47:20 +00:00
2016-08-14 04:42:32 +00:00
There's many other possible
effects, like for example `:dispatch-later` or `:set-local-store`.
2016-08-12 13:47:20 +00:00
And so on. And so on. Which brings us to a problem.
2016-08-13 06:11:11 +00:00
### Infinite Effects
2016-08-12 13:47:20 +00:00
While re-frame supplies a number of builtin effects, the set of
2016-08-12 13:47:20 +00:00
possible effects is open ended.
2016-08-19 05:32:51 +00:00
What if you use PostgreSQL and want an effect which issues mutating
2016-08-15 01:56:03 +00:00
queries? Or what if you want to send logs to Logentries or metrics to DataDog.
2016-08-14 04:42:32 +00:00
Or write values to windows.location. And what happens if your database is
X, Y or Z?
2016-08-16 14:08:30 +00:00
The list of effects is long and varied, with everyone needing to use a
different combination.
2016-08-12 13:47:20 +00:00
So effect handling has to be extensible. You need to a way to define
2016-08-14 04:42:32 +00:00
your own side effects.
2016-08-12 13:47:20 +00:00
### Extensible Side Effects
2016-08-15 01:56:03 +00:00
re-frame provides a function `reg-fx` through which you can register
your own `Effect Handlers`.
2016-08-12 13:47:20 +00:00
Use it like this:
```clj
(reg-fx ;; <-- registration function
:butterfly ;; <1>
2016-08-12 13:47:20 +00:00
(fn [value] ;; <2>
...
))
```
2016-08-16 14:08:30 +00:00
__<1>__ the key for the effect. When later an effects map contains
the key `:butterfly`, the function we are registering will be used to action it. <br>
2016-08-12 13:47:20 +00:00
2016-08-16 14:08:30 +00:00
__<2>__ the function which actions the side effect. Later, it will be called
with one argument - the value in the effects map, for this key.
2016-08-12 13:47:20 +00:00
2016-08-19 05:32:51 +00:00
So, if an event handler returned these two effects:
2016-08-12 13:47:20 +00:00
```clj
{:dispatch [:save-maiden 42]
2016-08-19 05:32:51 +00:00
:butterfly "Flapping"} ;; butterfly effect, but no chaos !!
2016-08-12 13:47:20 +00:00
```
2016-08-15 08:11:28 +00:00
Then the function we registered for `:butterfly` would be called to handle
that effect. And it would be called with the parameter "Flapping".
2016-08-12 13:47:20 +00:00
So, terminology:
2016-08-14 04:42:32 +00:00
- `:butterfly` is an "effect key"
2016-08-19 05:32:51 +00:00
- and the function registered is an "effect handler".
So re-frame has `event handlers` and `effect handlers` and they are
different, despite both starting with `e` and ending in `t`!!
2016-08-12 13:47:20 +00:00
### Writing An Effect Handler
2016-08-14 04:42:32 +00:00
A word of advice - make them as simple as possible, and then
2016-08-19 05:32:51 +00:00
simplify them further. You don't want them containing any fancy logic.
2016-08-14 04:42:32 +00:00
Why? Well, because they are all side-effecty they will be a pain
to test rigorously. And the combination of fancy logic and limited
2016-08-15 08:11:28 +00:00
testing always ends in tears. If not now, later.
2016-08-12 13:47:20 +00:00
A second word of advice - when you create an effect handler,
you also have to design (and document!) the structure of the
`value` expected.
2016-08-12 13:47:20 +00:00
2016-08-15 08:11:28 +00:00
When you do, realise that you are designing a nano DSL for `value` and try to
make that design simple too. If you resist being terse and smart, and instead, favor slightly
verbose and obvious, your future self will thank you. Create as little
cognitive overhead as possible for the eventual readers of your effectful code.
2016-08-12 13:47:20 +00:00
2016-08-15 08:11:28 +00:00
This advice coming from the guy who named effects `fx` ... Oh, the hypocrisy.
2016-08-12 13:47:20 +00:00
2016-08-15 08:11:28 +00:00
In my defence, here's the builtin effect handler for `:db`:
2016-08-12 13:47:20 +00:00
```clj
(reg-fx
:db
(fn [value]
(reset! re-frame.db/app-db value)))
```
2016-08-19 05:32:51 +00:00
So, yeah, simple ... and, because of it, I an almost guarantee there's no bug in ... bang, crash, smoke, flames.
2016-08-12 13:47:20 +00:00
> Note: the return value of an effect handler is ignored.
### :db Not Always Needed
2016-08-19 05:32:51 +00:00
An effects map does not need to include the `effect key` `:db`.
2016-08-19 05:32:51 +00:00
It is perfectly valid for an event handler
to not change `app-db`.
2016-08-19 05:32:51 +00:00
In fact, it is perfectly valid for an event handler to return
2016-08-15 08:11:28 +00:00
an effects map of `{}`. Slightly puzzling, but not a problem.
2016-08-14 04:42:32 +00:00
### What Makes This Work?
A silently inserted interceptor.
2016-08-14 04:42:32 +00:00
Whenever you register an event handler via __either__ `reg-event-db`
or `reg-event-fx`, an interceptor, cunningly named `do-fx`,
2016-08-14 04:42:32 +00:00
is inserted at the beginning of the chain.
2016-08-14 04:42:32 +00:00
Example: if your event handler registration looked like this:
```clj
(reg-event-fx
:some-id
[debug (path :right)] ;; <-- two interceptors, apparently
2016-08-16 14:08:30 +00:00
(fn [cofx _]
2016-08-14 04:42:32 +00:00
{}) ;; <-- imagine returned effects here
```
2016-08-14 04:42:32 +00:00
While it might look like you have registered with 2 interceptors,
`reg-event-fx` will make it 3:
```clj
[do-fx debug (path :right)]
```
2016-08-19 05:32:51 +00:00
It silently inserts `do-fx` at the front, and this is a good thing.
The placement of `do-fx` at the beginning of the interceptor chain means
2016-08-14 04:42:32 +00:00
it's `:after` function would be the final act when the chain is executed
(forwards and then backwards, as described in the Interceptor Tutorial).
In this final act, the `:after` function extracts `:effects` from `context`
and simply iterates across the key/value pairs it contains, calling the
2016-08-19 05:32:51 +00:00
registered "effect handlers" for each.
> For the record, the FISA Court requires that we deny all claims
> that `do-fx` is secretly injected NSA surveillance-ware. <br>
> We also note that you've been particularly sloppy with your personal
> grooming today, including that you forgot to clean your teeth. Again.
If ever you want to take control of the way effect handling is done,
create your own alternative to `reg-event-fx` and, in it, inject
your own version of the `do-fx` interceptor at the front
of the interceptor chain. It is only a few lines of code.
### Order Of Effects?
2016-08-12 13:47:20 +00:00
There isn't one.
`do-fx` does not currently provide you with control over the order in
2016-08-12 13:47:20 +00:00
which side effects occur. The `:db` side effect
2016-08-15 08:11:28 +00:00
might happen before `:dispatch`, or not. You can't rely on it.
2016-08-12 13:47:20 +00:00
2016-08-14 04:42:32 +00:00
*Note:* if you feel you need ordering, then please
open an issue and explain the usecase. The current absence of
2016-08-15 08:11:28 +00:00
good usecases is the reason ordering isn't implemented. So give
us a usercase and we'll revisit, maybe.
2016-08-12 13:47:20 +00:00
2016-08-15 08:11:28 +00:00
*Further Note:* if later ordering was needed, it might be handled via
metadata on `:effects`. Also, perhaps by allowing `reg-fx` to optionally
2016-08-14 04:42:32 +00:00
take two functions:
2016-08-15 08:11:28 +00:00
- an effects pre-process fn <-- new. Takes `:effects` returns `:effects`
- the effects handler (as already described above).
2016-08-12 13:47:20 +00:00
Anyway, these are all just possibilities. But not needed or implemented yet.
2016-08-12 13:47:20 +00:00
2016-08-15 08:11:28 +00:00
### Effects With No Data
Some effects have no associated data:
```clj
(reg-event-fx
:some-id
(fn [coeffect _]
{:exit-fullscreen nil})) ;; <--- no data, use a nil
```
2016-08-16 14:08:30 +00:00
In these cases, although it looks odd, just supply `nil` as the value for this key.
2016-08-15 08:11:28 +00:00
The associated effect handler would look like:
```clj
(reg-fx
:exit-fullscreen
(fn [_] ;; we don't bother with that nil value
(.exitFullscreen js/document)))
```
2016-08-19 05:32:51 +00:00
### Testing And Noops
2016-08-12 13:47:20 +00:00
When you are running tests or replaying events, it is sometimes
2016-08-19 05:32:51 +00:00
useful to stub out effects.
2016-08-12 13:47:20 +00:00
This is easily done - you simply register a noop effect handler.
2016-08-12 13:47:20 +00:00
Want to stub out the `:dispatch` effect? Do this:
2016-08-12 13:47:20 +00:00
```clj
(reg-fx
:dispatch
(fn [_] )) ;; a noop
2016-08-12 13:47:20 +00:00
```
2016-08-19 05:32:51 +00:00
If your test does alter registered effect handlers, and you are using `cljs.test`,
then you can use a `fixture` to restore all effect handlers at the end of your test:
```clj
(defn fixture-re-frame
[]
(let [restore-re-frame (atom nil)]
{:before #(reset! restore-re-frame (re-frame.core/make-restore-fn))
:after #(@restore-re-frame)}))
(use-fixtures :each (fixture-re-frame))
2016-08-19 05:32:51 +00:00
```
`re-frame.core/make-restore-fn` creates a checkpoint for re-frame state (including
registered handlers) to which you can return.
2016-08-24 14:29:57 +00:00
### Summary
XXX
---
Previous: [Interceptors](Interceptors.md)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Up: [Index](Readme.md)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Next: [Coeffects](Coeffects.md)
---
2016-08-19 05:32:51 +00:00
### Builtin Effect Handlers
#### :dispatch-later
`dispatch` one or more events after given delays. Expects a collection
of maps with two keys: `:ms` and `:dispatch`
usage:
```clj
{:dispatch-later [{:ms 200 :dispatch [:event-id "param"]}
{:ms 100 :dispatch [:also :this :in :100ms]}]}
```
Which means: in 200ms do this: `(dispatch [:event-id "param"])` and in 100ms ...
#### :dispatch
`dispatch` one event. Excepts a single vector.
usage:
```clj
{:dispatch [:event-id "param"] }
```
#### :dispatch-n
`dispatch` more than one event. Expects a collection events.
usage:
```clj
{:dispatch-n (list [:do :all] [:three :of] [:these])}
```
#### :deregister-event-handler
removes a previously registered event handler. Expects either a single id (
typically a keyword), or a seq of ids.
usage:
```clj
{:deregister-event-handler :my-id)}
```
or:
```clj
{:deregister-event-handler [:one-id :another-id]}
```
#### :db
reset! app-db with a new value. Expects a map.
usage:
```clj
{:db {:key1 value1 key2 value2}}
```
2016-08-13 06:11:11 +00:00
2016-08-19 05:32:51 +00:00
### External Effects
2016-08-13 06:11:11 +00:00
- https://github.com/Day8/re-frame-http-fx (GETs and POSTs)
- https://github.com/Day8/re-frame-forward-events-fx (slightly exotic)
- https://github.com/Day8/re-frame-async-flow-fx (more complicated)
Create a PR to include yours in this list.
2016-08-15 08:11:28 +00:00
XXX maybe put this list into the Wiki, so editable by all.