Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

This document is a discussion on the best path for adding reactive programming functionality to ClojureScript. Although this is primarily focused around UI updates/bindings, it should be generic enough to support something like the following:


Textbox -> On Key Press -> Throttle to 1 per sec -> Make Server request for data -> Format response into DOM elements -> Update UI


Async binding chains are required to allow for throttling, server calls, and for maintaining general UI responsiveness.



Related Work:



For the most part, async dom manipulation functions in JavaScript are both ugly and imperative. The same is currently true in ClojureScript. As an example let's imagine a requirement for a auto-complete box that must make an async call back to the server. However, to avoid creating a network storm we want to limit queries to once a second. In ClojureScript, we may write it thusly:


No Format
(def current-text (atom nil))

(defn on-changed [txt]
    (reset! current-text txt))

(defn make-server-request [txt]
    (ajax/get (make-url txt) 
              (fn [response error]
                  (when-not error
                            (dom/replace "#suggestions"
(defn timeout []
    (when-let [txt @current-text]
         (reset! current-text nil)
         (make-server-request txt)))

(js/setInterval timeout 1000)

(set! (.onchange dom-element) on-changed)


This code is ugly and every function impure. For a language that espouses immutability and pure functions, there has to be a better way.

Current Solutions

Related work in the JavaScript world:

Flapjax -

A fairly normal interpretation of FRP in JavaScript. Requires the user to manually convert event handlers to event streams. From there, streams can be composed and bound to the DOM.


Rx -

This is a well known and very powerful technology developed by MS.


  • Very simple interface (could be done with a single protocol)
  • Observables/Observers can be easily coupled-decoupled


  • The code isn't really side-effect free. Chains basically end with a dorun block


TPL Dataflow:

A slightly different library also developed by MS:

Reactive extensions take the Observable pattern and extend it to support functional event stream transforms. Many examples can be seen here (

Unlike Rx, TPL Dataflow is expressed as blocks with input queues and output queues. If messages are not removed from these queues the messages will build up. This is by design as TPL Dataflow is more about processing data via Dataflow graphs and less about event based UI programming.


  • Also a fairly simple to implement (just a few interfaces needed)
  • The "code blocks" could be very functional. Each block could accept a list of queues and return a map of data to queue into the outputs
  • Fairly may uses cases
  • Could possibly work well with web workers? (



  • If we were building a dataflow off of mouse events, the queue could get full very quickly.
    • Perhaps a throttle block would be all that's needed here?



A very large library built by Zach Tellman  (


  • Can we get Zach to comment here?



This is the well known Racket implementation (


  • Very functional
  • Will re-interpret lisp functions into event based functions


  • Quite a lot of code is required for this
  • Doesn't seem to support async functions.



Suggested Implementation:


To start with, I suggest we reduce the Reactive Extensions interfaces down to the following


(defprotocol IObservable

    (subscribe [this onnext onerror oncomplete]))


To subscribe, a user would need to supply functions that will be called when a new event arrives, when an error has occurred, and when the stream has completed. In return the subscribe method will return a single function that the user can call to detach from the IObservable.

This interface could be further simplified by combining the input functions into a single function that would accept either a event or one of ::error or ::complete messages. However, in my attempts with this, I've discovered that this simply makes the subscriber code more complex as a single function must now handle three use cases.


Several functions could then be created that operate on this interface. For instance, rmap (reactive map) would apply a function to each event sent through onnext.




Potential Solution

I suggest we stick pretty close to the Rx solution. Due to the fact that ClojureScript is single threaded and will remain so for the foreseeable future (web workers communicate purely via message passing), it is possible to construct a much simplified version of Rx in ClojureScript.


I suggest the following interfaces:

No Format
(defprotocol IObserver
    (onnext [this evt] "Called when a new event arrives")
    (onerror [this err] "Called when an error occurs")
    (onend [this end] "Called when the stream ends"))

(defprotocol IObservable
    (subscribe [this ^IObserver observer] 
       "Registers the observer with the observable. Returns a function
        that when called, unregisters the Observer))

(defprotocol IObservableLookup
    (to-observable [this key] "Returns a IObservable based on the key"))


Based on these interfaces, it is fairly easy to start composing blocks of code that call the methods on IObserver differently, and that actually emulate several of the functions found in clojure.core. I suggest the following stream functions:

map - applies a function to every event in a stream. If more than one stream is specified, the events of each stream are queued until a new value for each stream is available. Then all streams are processed one element at a time

reduce - reduces a stream by applying a function to each item and the accum value until onend is called. At this point the accum is pushed to the observers.

merge - simply interleaves the contents of each stream in the order that they are received

interleave - same as merge, but events are interleaved in a round-robin order.

throttle - same as map, but extra events are thrown way, not queued. Only the most recent of each event stream is processed

foreach - executes a function against every element in the stream. Assumes that side-effects take place.


Using the above, it's fairly simple to see how one could write our auto-complete in the following way:


No Format
(-> (to-observable dom-element :changed)
    (throttle (to-observable timer [1 :sec]))
    (rmap make-url)
    (foreach #(dom/replace "#suggestions" %)))


Not only is this code concise, but it also presents the logic in a fairly functional manner.


After the above interfaces have been proven to work. The implementation of a DSL will be investigated (as a separate proposal). In this DSL we would expose to-observable as symbols where a observable/key pair are written as observable:key.


For example:

No Format
(bind dom:#suggestions
    (-> (throttle dom-element:changed timer:1sec)



Topics for Discussion

Should a naming convention be adopted for event stream functions? Map is a good name for the map function, but I'd rather not confuse users.


  • $map
  • rmap
  • mapr
  • |map


Can we simplify this any more? Three interfaces aren't much, but those interfaces hide a lot of mutability. This mutability may be less of an issue in the single-threaded world of JS, but can we see any issues?


Some work by Stuart Sierra on Rx in Clojure:

Event programming in Clojure:

TPL Dataflow, like Rx, but uses queues and processor blocks: