You're reading from Hands-On Reactive Programming with Clojure Create asynchronous, event-based, and concurrent applications

Product type Paperback

Published in Jan 2019

Publisher Packt

ISBN-13 9781789346138

Length 298 pages

Edition 2nd Edition

Languages

Clojure

Tools

ClojureScript

Concepts

Reactive Programming

Authors (2):

Leonardo Borges

Konrad Szydlo

View More author details

A taste of Reactive Programming

Before covering some history and background behind Reactive Programming and CES, I would like to open with a working, and hopefully compelling, example: an animation in which we draw a sine wave onto a web page.

The sine wave is simply a graphical representation of the sine function. It is a smooth, repetitive oscillation, and at the end of our animation, it will look like what's shown in the following screenshot:

This example will highlight how CES does the following:

Urges us to think about what we would like to do as opposed to how
Encourages small, specific abstractions that can be composed together
Produces terse and maintainable code that is easy to change

The core of this program boils down to four lines of ClojureScript:

(-> app-time
    (.pipe (rx-take 700))
    (.subscribe (fn [{:keys [x y]}] 
                  (fill-rect x y) "orange"))))

Simply by looking at this code, it is impossible to determine precisely what it does. However, do take the time to read and imagine what it could do.

First, we have a variable called app-time, which represents a sequence of time. The next line gives us the intuition that app-time is some sort of collection-like abstraction: we use rx-take to retrieve 700 numbers from it.

Finally, we have to .subscribe to this collection by passing it a callback. This callback will be called for each item in the sine wave, finally drawing out the given sine coordinates using the fill-rect function.

This is quite a bit to take in for now, as we haven't seen any other code yet, but that was the point of this little exercise: even though we know nothing about the specifics of this example, we are able to develop an intuition of how it might work.

Let's see what else is necessary to make this snippet animate a sine wave on our screen.

This example is built in ClojureScript and uses HTML5 canvas for rendering and RxJS (see https://github.com/reactivex/rxjs), a framework for Reactive Programming in JavaScript.

Before we start, keep in mind that we will not go into the details of these frameworks yet; that will happen in the next chapter. This means I'll be asking you to take quite a few things at face value, so don't worry if you don't immediately grasp how things work. The purpose of this example is to simply get us started in the world of Reactive Programming.

For this project, we will be using figwheel (see https://github.com/bhauman/lein-figwheel), a Leiningen template for ClojureScript that gives us a sample working application that we can use as a skeleton.

To create our new project, head over to the command line and invoke Leiningen as follows:

lein new figwheel sin-wave
cd sin-wave

Next, we need to modify a couple of things in the generated project. Open up sin-wave/resources/index.html and update it to look like the following:

<!DOCTYPE html> 
<html> 
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1"> 
    <link href="css/style.css" rel="stylesheet" type="text/css">        
    <script src="js/rxjs.umd.js" type="text/javascript"></script></head> 
<body>
  <div id="app"></div>
  <script src="js/compiled/sin_wave.js" type="text/javascript"></script>
  <canvas id="myCanvas" width="650" height="200" style="border:1px solid #d3d3d3;"></canvas>
 </body>
</html>

This simply ensures that we import both our application code and RxJS. We haven't downloaded RxJS yet, so let's do that now. Browse to https://unpkg.com/rxjs/bundles/rxjs.umd.js and save this file to sin-wave/resources/public/js. The previous snippets also add an HTML5 canvas element, onto which we will be drawing.

Now, open /src/cljs/sin_wave/core.cljs. This is where our application code will live. You can ignore what is currently there. Make sure you have a clean slate like the following one:

(ns sin-wave.core) 
 
(defn on-js-reload[])

Finally, go back to the command line under the sin-wave folder and start up the following application:

lein figwheel
Figwheel: Cutting some fruit, just a sec ...                            
Figwheel: Validating the configuration found in project.clj             
Figwheel: Configuration Valid ;)    
Figwheel: Starting server at http://0.0.0.0:3449                        
Figwheel: Watching build - dev      
Figwheel: Cleaning build - dev      
Compiling build :dev to "resources/public/js/compiled/sine_wave.js" from ["src"]...                                                              
Successfully compiled build :dev to "resources/public/js/compiled/sine_wave.js" in 16.12 seconds.                                                
Figwheel: Starting CSS Watcher for paths  ["resources/public/css"]      
Launching ClojureScript REPL for build: dev                             
Figwheel Controls:                  
          (stop-autobuild)                ;; stops Figwheel autobuilder 
          (start-autobuild id ...)        ;; starts autobuilder focused on optional ids                                                          
          (switch-to-build id ...)        ;; switches autobuilder to different build                                                             
          (reset-autobuild)               ;; stops, cleans, and starts autobuilder                                                               
          (reload-config)                 ;; reloads build config and resets autobuild                                                           
          (build-once id ...)             ;; builds source one time     
          (clean-builds id ..)            ;; deletes compiled cljs target files                                                                  
          (print-config id ...)           ;; prints out build configurations                                                                     
          (fig-status)                    ;; displays current state of system                                                                    
          (figwheel.client/set-autoload false)    ;; will turn autoloading off                                                                   
          (figwheel.client/set-repl-pprint false) ;; will turn pretty printing off                                                               
  Switch REPL build focus:          
          :cljs/quit                      ;; allows you to switch REPL to another build                                                          
    Docs: (doc function-name-here)  
    Exit: :cljs/quit                
 Results: Stored in vars *1, *2, *3, *e holds last exception object     
Prompt will show when Figwheel connects to your application             
[Rebel readline] Type :repl/help for online help info                   
ClojureScript 1.10.238              
dev:cljs.user!{:conn 2}=>

Once the previous command finishes, the application will be available at http://localhost:3449/index.html, where you will find a blank, rectangular canvas. We are now ready to begin.

The main reason we are using the figwheel template for this example is that it performs hot-reloading of our application code via WebSockets. This means that we can have the browser and the editor side by side, and as we update our code, we will see the results immediately in the browser without having to reload the page.

To validate that this is working, open your web browser's console so that you can see the output of the scripts on the page. Then, add this to /src/cljs/sin_wave/core.cljs as follows:

(.log js/console "hello clojurescript")

You should have seen the hello clojurescript message being printed to your browser's console. Make sure you have a working environment up to this point, as we will be relying on this workflow to interactively build our application.

It is also a good idea to make sure we clear the canvas every time figwheel reloads our file. This is simple enough to do by adding the following snippet to our core namespace:

(defn canvas []
  (.getElementById js/document "myCanvas"))

(defn ctx []
  (.getContext (canvas) "2d"))

The concept of time in RxJS

Now that we have a working environment, we can progress with our animation. It is probably a good idea to specify how often we would like to have a new animation frame.

This effectively means adding the concept of time to our application. You're free to play with different values, but let's start with a new frame every 10 milliseconds:

(def rx-interval js/rxjs.interval)
(def rx-take js/rxjs.operators.take)
(def rx-map js/rxjs.operators.map)
(def app-time (rx-interval 10))

As RxJS is a JavaScript library, we need to use ClojureScript's interoperability to call its functions. For convenience, we will bind the interval function of RxJS to a local var. We will use this approach throughout this book when appropriate.

Next, we will create an infinite stream of numbers, starting at 0, that will have a new element every 10 milliseconds. Let's make sure this is working as expected:

(-> app-time
    (.pipe (rx-take 5)) 
    (.subscribe (fn [n] 
                  (.log js/console n)))) 
 
;; 0 
;; 1 
;; 2 
;; 3 
;; 4

I use the term stream very loosely here. It will be defined more precisely later in the book.

Remember that time is infinite, so we will use the take Rx operator in order to avoid indefinitely printing out numbers to the console.

Our next step is to calculate the 2D coordinate representing a segment of the sine wave we can draw. This will be given by the following functions:

(defn deg-to-rad [n] 
  (* (/ Math/PI 180) n)) 
 
(defn sine-coord [x] 
  (let [sin (Math/sin (deg-to-rad x)) 
        y   (- 100 (* sin 90))] 
    {:x   x 
     :y   y 
     :sin sin}))

(def sine-wave
  (.pipe app-time (rx-map sine-coord)))

The sine-coord function takes an x point of our 2D canvas and calculates the y point based on the sine of x. The constants 100 and 90 simply control how tall and sharp the slope should be. As an example, try calculating the sine coordinate when x is 50:

(.log js/console (str (sine-coord 50))) 
;;{:x 50, :y 31.05600011929198, :sin 0.766044443118978}

We will be using app-time as the source for the values of x. Creating the sine wave is now only a matter of combining both app-time and sine-coord:

(-> app-time 
    (.pipe (rx-take 5) )
    (.subscribe (fn [num] 
                  (.log js/console (sine-coord num))))) 
 
 ;; {:x 0, :y 100, :sin 0}  
 ;; {:x 1, :y 98.42928342064448, :sin 0.01745240643728351}  
 ;; {:x 2, :y 96.85904529677491, :sin 0.03489949670250097}  
 ;; {:x 3, :y 95.28976393813505, :sin 0.052335956242943835}  
 ;; {:x 4, :y 93.72191736302872, :sin 0.0697564737441253}

This brings us to the original code snippet that piqued our interest, alongside a function to perform the actual drawing:

(defn fill-rect [x y colour]
  (set! (.-fillStyle (ctx)) colour)
  (.fillRect (ctx) x y 2 2))
 
(-> app-time 
    (.pipe (rx-take 700)) 
    (.subscribe (fn [num] 
                  (fill-rect x y "orange"))))

As this point, we can save the file again and watch as the sine wave we have just created gracefully appears on the screen.

More colors

One of the points this example sets out to illustrate is how thinking in terms of very simple abstractions and then building more complex ones on top of them make for code that is simpler to maintain and easier to modify.

As such, we will now update our animation to draw the sine wave in different colors. In this case, we would like to draw the wave in red if the sine of x is negative, and blue otherwise.

We already have the sine value coming through the sine-wave stream, so all we need to do is transform this stream into one that will give us the colors according to the preceding criteria:

(def colour (.pipe sine-wave 
                   (rx-map
                     (fn [{:keys [sin]}] 
                       (if (< sin 0) 
                         "red" 
                         "blue")))))

The next step is to add the new stream into the main drawing loop—remember to comment the previous one so that we don't end up with multiple waves being drawn at the same time:

(-> (js/rxjs.zip sine-wave colour) 
    (.pipe (rx-take 700)) 
    (.subscribe (fn [[{:keys [x y]} colour]] 
                  (fill-rect x y colour))))

Once we save the file, we should see a new sine wave alternating between red and blue as the sine of x oscillates from -1 to 1.

Making it reactive

As fun as this has been so far, the animation we have created isn't really reactive. Sure, it does react to time itself, but that is the very nature of animation. As we will see later, Reactive Programming is called as such because programs react to external inputs such as a mouse or network events.

We will, therefore, update the animation so that the user is in control of when the color switch occurs: the wave will start off red and switch to blue when the user clicks anywhere within the canvas area. Further clicks will simply alternate between red and blue.

We start by creating infinite—as per the definition of app-time—streams for our color primitives as follows:

(def red  (.pipe app-time (rx-map (fn [_] "red")))) 
(def blue (.pipe app-time (rx-map (fn [_] "blue"))))

On their own, red and blue aren't that interesting, as their values don't change. We can think of them as constant streams. They become a lot more interesting when combined with another infinite stream that cycles between them based on user input:

(def rx-concat     js/rxjs.concat) 
(def rx-defer      js/rxjs.defer) 
(def rx-from-event js/rxjs.fromEvent)
(def rx-takeUntil  js/rxjs.operators.takeUntil)
 
 
(def mouse-click (rx-from-event canvas "click")) 
 
(def cycle-colour 
  (rx-concat (.pipe red (rx-takeUntil mouse-click)) 
          (rx-defer #(rx-concat (.pipe blue (rx-takeUntil mouse-click)) 
                          cycle-colour))))

This is our most complex update so far. If you look closely, you will also notice that cycle-colour is a recursive stream; that is, it is defined in terms of itself.

When we first saw the code of this nature, we took a leap of faith in trying to understand what it does. After a quick read, however, we realized that cycle-colour closely follows how we might have talked about the problem: we will use red until a mouse click occurs, after which, we will use blue until another mouse click occurs. Then, we start the recursion.

The change to our animation loop is minimal:

(-> (js/rxjs.zip sine-wave cycle-colour) 
    (.pipe (rx-take 700))
    (.subscribe (fn [[{:keys [x y]} colour]] 
                  (fill-rect x y colour))))

The purpose of this book is to help you develop the instinct required to model problems in the way that's demonstrated here. After each chapter, more and more of this example will make sense. Additionally, a number of frameworks will be used both in ClojureScript and Clojure to give you a wide range of tools to choose from.

Before we move on to that, we must take a little detour and understand how we got here.

Exercise 1.1

Modify the previous example in such a way that the sine wave is drawn using all the colors of the rainbow. The drawing loop should look like the following:

(-> (js/rx.zip sine-wave rainbow-colours) 
    (pipe (rx-take 700))
    (.subscribe (fn [[{:keys [x y]} colour]] 
                  (fill-rect x y colour))))

Your task is to implement the rainbow-colours stream. As everything up until now has been very light on explanations, you might choose to come back to this exercise later, once we have covered more about CES.

The repeat, scan, and flatMap functions may be useful in solving this exercise. Be sure to consult RxJs' API at https://rxjs-dev.firebaseapp.com/guide/overview for more information.