Lambda Island

A complete look at re-frame subscriptions, including coverage of Reagent’s atoms and reactions. You learn how to write subscriptions, how they work, and how to plug them together into a signal graph.

Transcript

In re-frame, views receive data from the database through subscriptions. Suppose we have a database that looks like this, here we’re building a todo list app, and individual todo items are represented as hash-maps, bundled together in a vector under the :todos key.

(def default-db
  {:todos [{:id (random-uuid)
            :title "Donate to charity"
            :completed false}]})

We want to use this information to render a list of all todos that haven’t been completed yet. So we need a subscription, let’s call it :visible-todos.

Registering a subscription is done with re-frame.core/reg-sub. You first pass it the name of the subscription as a keyword, followed by the function that gets the right data from the database.

This function receives the current state of the application database, and pulls out the list todos that haven’t been completed yet. You can think of it as a database query.

This subscription function also receives a second argument, the query vector. This is useful for subscriptions that take arguments, we’ll see examples of those later on.

(re-frame.core/reg-sub :visible-todos
         (fn [db query-v]
           (remove :completed (:todos db))))

Now create a view that will display this data. Use a form-2 component, let’s call it todo-list, and add a let block around the render function to subscribe to any data sources you need. Here we subscribe to the :visible-todos subscription we created earlier. subscribe takes a vector which is known as the “query vector”, where the first argument in the vector is the name of the subscription.

The inner render function returns Hiccup that will become the next virtual DOM. We’ll return a div containing the individual todos.

Notice that I’m dereferencing the subscription here to get its current value, and that it’s happening inside the render function . This is important, as we’ll see later.

As always don’t forget to give siblings elements a unique key to keep React happy.

(defn todo-list []
  (let [todos (subscribe [:visible-todos])]
    (fn []
      [:div#todo-list
       (for [todo @todos]
         ^{:key (:id todo)} [todo-item todo])])))

re-frame’s subscription system is built using Reagent’s atoms and reactions. When you look at the result of calling subscribe, you can see it’s a ‘Reaction`’, a special type of object provided by Reagent. To fully understand what reactions are, we first need to talk about Reagent’s atoms.

(subscribe [:visible-todos])
;;=> #<Reaction 11: ({:id #uuid "4760db48-c52a-494a-a62c-00cb64504238", :title "Donate to charity"})>

A Reagent atom, also called an “ratom”, behaves a lot like a regular Clojurescript atom. It allows you to store a value that might change over time. It’s basically just a box holding a value. To get to the value inside the atom you “deref” it, which can be abbreviated to simply “@”.

Changing an atom is done with swap!. You pass swap! a function that takes the atom’s current value, and returns the new one. You can also set the atom to a fixed value with reset!.

(require '[reagent.core :as r])
(def counter (r/atom 0))              ;;=> #'cljs.user/counter

counter                               ;;=> #<Atom: 0>
(deref counter)                       ;;=> 0
@counter                              ;;=> 0

(swap! counter (fn [i] (+ 1 i)))      ;;=> 1
@counter                              ;;=> 1

(reset! counter 7)                    ;;=> 7
@counter                              ;;=> 7

It is possible to “watch” an atom, so your code gets notified when its value changes. When you’re using Reagent atoms then Reagent does this watching for you behind the scenes. First it will detect whenever an ratom is dereferenced inside a render function. This way it can track which components should be updated whenever a certain atom changes. When the atom does change, Reagent tells React to re-draw only these particular components use it, leaving the rest alone.

This is why Reagent atoms work so well for storing application state. With a regular atom you would have to manually re-render the whole virtual DOM whenever the app state changes. With ratoms components are automatically kept up-to-date, and in a way that cuts out a lot of unnecessary work.

(def app-state (r/atom {:todos []}))

(def todo-list []
  [:div
   (for [todo (:todos @app-state)]
     ^{:key (:id todo)} [todo-item todo])])

Besides storing global application state, ratoms are also used to store component local state. This for example is a common pattern for storing the current value of a text input field. You create the atom in the outer let of a form-2 component, so that the render function closes over it. Now the change events from the text field keep the atom up-to-date, which in turn causes the new value to be displayed in the text field. When the user presses enter or clicks a button, you can read out the current value and use it.

(def input-box []
  (let [value (r/atom "")]
    (fn []
      [:input {:type "text"
               :value @value
               :on-change #(reset! value (.. % -target -value))
               :on-key-down #(when (= 13 (.. % -which))
                               (handle-enter @value))}])))

So that’s a Reagent atom, if you used plain Reagent before you probably already used these. In a re-frame app however you typically don’t use atoms directly. Instead there’s one atom that’s managed behind the scenes by re-frame, called the application database.

Using a single atom to store all application states is a typical Clojure thing to do. It’s very elegant and makes code easy to reason about. In the case of Reagent though there’s one gotcha you have to be aware of.

Remember that whenever the atom changes, Reagent will re-render all components that reference it. This mean that if you only have one atom that’s used all over the place, then any state change will cause all components to re-render. This isn’t necessarily a huge deal. Even though you’re rebuilding the virtual DOM more often than necessary, React’s DOM diffing algorithm will still minimize the amount of operations to the real DOM, but still there’s work being done that we might just as well avoid.

To solve this, Reagent introduced Reactions. They let you specify a value based on the value of one or more ratoms. Think of them as formulas in a spreadsheet. When you update a spreadsheet cell, then any formulas that reference that cell will update. Similarly, when an ratom changes, any reactions that reference it get updated.

You create a Reaction by wrapping some code in the reaction macro. By dereffing the reaction you get to its computed value. For example we can have a reaction that returns just the list of todos.

Now in the component instead of dereffing the whole app-state atom, use the todos-reaction instead. When the app-state changes React will recompute the list of todos, and only when it is different from the previous value will it re-render the component.

(require '[reagent.core :as r])
(require-macros '[reagent.ratom :refer [reaction]])

(def app-state (r/atom {:user {}
                        :sidebar-open false
                        :todos []}))

(def todos-reaction
  (reaction
   (:todos @app-state)))

todos-reaction       ;;=> #<Reaction 27: []>
@todos-reaction      ;;=> []

(def todo-list []
  [:div
   (for [todo @todos-reaction]
     ^{:key (:id todo)}) [todo-item todo]])

Before continuing let’s see what we’re actually building. I’m making a re-frame version of the popular TodoMVC app. Our app state will hold two things: the list of todos, and the type of todos that are currently visible. I’m only going to show a few select parts of the code, but I encourage you to check out the whole source on Github. It also demonstrates how to use Secretary for page routing.

Here’s the default database state, this will be used for the initial value of re-frame’s internal database atom. This time I’m using a map to store the todos, rather than a vector, so it’s easy to look them up based on their id.

We’ll also track the, :display-type. This determines which todos are currently visible. This way we can either show all todos, only the ones that are completed, or those that haven’t been completed yet.

(def default-db
  {:todos {}
   :display-type :all})

By now you might already have realized that re-frames subscriptions behave a lot like reactions. That’s because subscriptions are really just reactions under the hood.

So let’s create a subscription for the todos. I don’t need the query vector so I’m just using _ as a placeholder argument. Given the current database state this function pulls out the :todos hash-map, and then returns all values in the map, so you get a seq of todos you can iterate over. Notice that the subscription is just a pure function. Even though the application database is an atom, you don’t have to worry about dereferencing it. re-frame will pass in the latest version whenever :todos needs to be recomputed.

We also need to expose :display-type to the views, so create a subscription which passes it on directly.

(reg-sub :todos
         (fn [db _]
           (vals (:todos db))))

(reg-sub :display-type
         (fn [db _]
           (:display-type db)))

As we saw before, calling subscribe now returns a reaction. You might think that the reaction is created when calling reg-sub, but it’s really only instantiated in the call to subscribe.

(subscribe [:todos])

The reason for this is that subscriptions can take arguments, and only when you call subscribe does re-frame know what those arguments are. For example this is a subscription to get a specific todo item based on its id.

Now we do need the query vector, with some destructuring it’s easy to get to the individual arguments. The first item in the vector will be the name of the subscription, :todo-by-id, we can ignore that one. The id we’re looking for comes second.

Now when you call subscribe include the todo’s :id as second argument in the query vector, and it will create a reaction that always looks up the todo with this particular id.

(reg-sub :todo-by-id
         (fn [db [_ uuid]]
           (get (:todos db) uuid)))

(subscribe [:todo-by-id #uuid "0eda7b22-cff7-4abc-b10c-fd892bd7132b"])

Subscriptions are named such because they allow a component to “subscribe” to specific pieces of data. It’s like there’s a cable connected to the component that always feeds it the current value of whatever data it’s interested in.

Looked at this way, the database is like a signal that always sends out the current state of the database. Subscriptions are like signal transformers, they receive one or more input signals, and send out a new signal based on what they’re receiving.

Finally components tune in to these signals so they stay up to date.

(defn todos-list []
  (let [todos (subscribe [:todos])]
    (fn []
      [:ul#todo-list
       (for [todo @todos]
         ^{:key (:id todo)} [todo-item todo])])))

A collection of things that send, receive, or transform signals is known as a signal graph. This signal graph is still pretty simple, there’s only one subscription between the app db and the components. It’s possible however to use subscriptions as inputs for other subscriptions, creating a chain of computed values.

Any state change will trickle down through the chain of subscriptions, but if the output of a subscription didn’t change, then the flow of data stops. Subscriptions further down the line will not be recomputed, and components that use them will not be re-rendered.

It should be clear now that good use of subscriptions can go a long way towards making your app perform well.

There are two ways to link subscriptions together. I’ll first show you how to plug them together using a special “arrow” syntax, then afterwards show the more general way.

Create a new subscription called :todos/completed. I’m using a namespaced keyword this time. As your app grows it’s a good idea to use these both for subscriptions and for events, to logically group things together. This way it’s also easy later on to split things into multiple files based on the keyword prefix.

Now after the subscription name, add this arrow keyword, and then the query vector.

You can think of this arrow as saying “use the output of [:todos] as input for this subscription”. Now the subscription function no longer receives the whole database, but instead just receives the list of todos as output by the :todos subscription.

(reg-sub :todos/completed :<- [:todos]
         (fn [todos _]
           (filter :completed todos)))

Let me also quickly add a subscription for the “active” todos, in other words the ones that haven’t been completed.

(reg-sub :todos/active :<- [:todos]
         (fn [todos _]
           (remove :completed todos)))

Now you can implement a subscription for the currently visible todos, which depending on the value of :display-type will be either all of them, just the completed ones, or only the active ones. We already have subscriptions for all of those, so now you can use them as inputs.

When a subscription has more than one input, as is the case here, then their values will be passed to the subscription function in a vector, so you need an extra pair of square brackets here to destructure the vector. This wasn’t the case earlier, when there was only one input.

With all of that there it’s just a matter of switching on the display type and returning the right response.

(reg-sub :todos/visible
         :<- [:display-type]
         :<- [:todos]
         :<- [:todos/completed]
         :<- [:todos/active]
         (fn [[type all completed active] query-v]
           (case type
             :all all
             :completed completed
             :active active)))

Now let’s go back to this :todo-by-id subscription. Suppose you want to add a similar, derived subscription, that tells you if a todo with a certain id is completed or not.

Here’s a first attempt, using :todo-by-id as an input. But :todo-by-id requires an uuid as an argument, and we only have access to that uuid from the query vector inside the subscription function, not outside of it when setting up the inputs.

For cases like these where you need access to the query vector to set up the inputs, there’s a different approach.

(reg-sub :todo-by-id
         (fn [db [_ uuid]]
           (get (:todos db) uuid)))

(reg-sub :todo-completed? :<- [:todo-by-id uuid]
         (fn [todo [_ uuid]]
           (:completed todo)))

Instead of using the magical arrow syntax, you can use a function that provides the inputs for the subscription. The return value has to be either a single ratom or reaction, or a vector of them. re-frame will take care of derefercing them and passing them to the subscription as inputs.

(reg-sub :todo-completed?
         (fn [query-v]
           (subscribe [:todo-by-id (second query-v)]))
         (fn [todo [_ uuid]]
           (:completed todo)))

We can refactor :todos/visible to use this syntax as well, to demonstrate how it looks when there’s more than one input. Notice that the inputs-function now returns a vector of reactions, which corresponds with the vector of inputs that is passed to the subscription-function.

(reg-sub :todos/visible
         (fn [_]
           [(subscribe [:display-type])
            (subscribe [:todos])
            (subscribe [:todos/completed])
            (subscribe [:todos/active])])

         (fn [[type all completed active] query-v]
           (case type
             :all all
             :completed completed
             :active active)))

So far I’ve used subscriptions as inputs, but subscribe just returns a reaction, and in fact any reaction or ratom will work as an input just fine. This can be very useful when migrating a legacy Reagent app to re-frame. You can continue to use the ratoms you used before to store application state, but already use subscriptions to populate your views. Once that is done it should be easier to migrate the state held in those atoms into the re-frame database.

Show Notes

browse source code

Starting point is the ep20-start branch, the episode goes up to the ep20-end. [Full diff]

Errata

The video is missing the definition of the :display-type subscription. The transcript has been updated to include it.

(reg-sub :display-type
         (fn [db _]
           (:display-type db)))

Prerequisites

This episode is part of a series on building React apps using Reagent and re-frame.

If you’re not familiar with re-frame yet, then start here:

19. re-frame

re-frame builds on top of Reagent, which you can learn about in these episodes. Especially the first and third are relevant to this episode

Reagent is a ClojureScript wrapper for React. If you’re new to React development and not yet familiar with its concepts like components and the virtual DOM, then start here:

6. Building a React app with ClojureScript

Code

(ns redolist.subs
    (:require-macros [reagent.ratom :refer [reaction]])
    (:require [re-frame.core :as re-frame :refer [reg-sub]]))

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Regular subscriptions

(reg-sub :display-type
         (fn [db]
           (:display-type db)))

(reg-sub :todos
         (fn [db]
           (vals (:todos db))))

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Subscriptions with othe subscriptions as inputs

(reg-sub :todos/visible
         :<- [:display-type]
         :<- [:todos]
         :<- [:todos/completed]
         :<- [:todos/active]
         (fn [[type all completed active]]
           (case type
             :all all
             :completed completed
             :active active)))

(reg-sub :todos/completed :<- [:todos]
         (fn [todos]
           (filter :completed todos)))

(reg-sub :todos/active :<- [:todos]
         (fn [todos]
           (filter (complement :completed) todos)))

(reg-sub :todos/empty? :<- [:todos]
         (fn [todos]
           (empty? todos)))

(reg-sub :todos/all-complete? :<- [:todos/active]
         (fn [active]
           (empty? active)))

(reg-sub :todos/active-count :<- [:todos/active]
         (fn [active]
           (count active)))

re-frame, part 2: Subscriptions