anchor.diff:  = beicon - reactive streams for clojurescript
   Andrey Antukh, <niwi@niwi.nz>
  -v0.8.1
  +v0.1.0
   :toc: left
   :!numbered:
   :idseparator: -
  
positive.code: _beicon_ is a small and concise library that provides reactive streams to
  clojurescript built on top of link:https://github.com/Reactive-Extensions/RxJS[rxjs].
  
  
  === Project Maturity
  
  
negative.code: ----
  
  
  === From Value
  
  It creates a observable sequence of one unique value:
  
  [source, clojure]
  ----
  (def stream (s/once 10)
  
  (s/on-value stream #(println "v:" %))
  ;; ==> v: 10
  ----
  
  
  === Terminated
  
  Some times you also want just a terminated stream:
  
  [source, clojure]
  ----
  (def stream (s/never))
  ----
  
  This stream not yelds any value and just terminates.
  
  
  === With timeout
  
  This allow create an observable seequence of one unique value that will be emited
  after specified amount of time:
  
  [source, clojure]
  ----
  (def stream (s/timeout 1000 10))
  
  (s/on-value stream #(println "v:" %))
  ;; After 1 sec...
  ;; ==> v: 10
  ----
  
  
  === From factory
  
  This is the most advanced and flexible way to create a observable sequence. It
  allows to have control about termination and errors and intended to be used
  for build other kind of constructors.
  
  [source, clojure]
  ----
  (def stream 
    (s/create (fn [sick]
                (sick 1)
                (sick 2)
                (sick nil) ;; ends
                )))
  
  (s/on-value stream #(println "v:" %))
  ;; ==> v: 1
  ;; ==> v: 2
  ----
  
  This is implemented using protocols for make it flexible and easy extensible
  by the user. By default any object except `nil` or instance of `js/Error` are
  considered valid values; `nil` is considered as end of stream and `js/Error` or
  any instance of it is considered error termination.
  
  == Consuming streams
  
  === The stream states
  
  The observable sequence can be in 3 different kind of states: alive, errored or
  ended. I an error is emited the stream can be considered ended with an error.
  So error or end states can be considered termination states.
  
  And is convenient you can subscribe to any of that states of an observable
  seequence.
  
  === General purpose
  
  A general purpose subscription is one that allows you create one subscription
  that watches all the different possible states of an observable seequence:
  
  [source, clojure]
  ----
  (def sub (s/subscribe stream
                        #(println "on-value:" %)
                        #(println "on-error:" %)
                        #(println "on-end:")))
  ----
  
  The return value of `subscribe` function is a funcition that can be called for
  dispose the subscription.
  
  === Consume values
  
  But in most circumstances you only want consume values regardless of any error
  or termination. For this purposes is there the `on-value` function:
  
  [source, clojure]
  ----
  (def sub (s/on-value sub #(println "val:" %)))
  ----
  
  Like with `subscribe` function, `on-value` function also return a callable that
  when is called will dispose the created subscription.
  
  NOTE: take care that calling any one of that helper functions creates a separated
  subscription and it can behave unexpectly if you do not aware if you are using
  <<hot or cold observables, hot-vs-cold-observales>>.
  
  
  === Consume successful termination
  
  With `on-end` function you can watch the successful termination of an observable
  sequence:
  
  [source, clojure]
  ----
  (def sub (s/on-end sub #(println "end!")))
  ----
  
  === Consume error termination
  
  With `on-error` function you can watch the error termination of an observable
  seequence:
  
  [source, clojure]
  ----
  (def sub (s/on-end sub #(println "error:" %)))
  ----
  
  
  == Transformations
  
  === Filter
  
  The main advantage of using reactive streams is that you may treat them like
  normal seequence, and in this case filter them with a predicate:
  
  [source, clojure]
  ----
  (def stream (->> (s/from-coll [1 2 3 4 5])
                   (s/filter #(> % 3))))
  
  (s/subscribe stream
               #(println "on-value:" %)
               #(println "on-error:" %)
               #(println "on-end"))
  
  ;; ==> on-value: 4
  ;; ==> on-value: 5
  ;; ==> on-end
  ----
  
  === Map
  
  Also, you can apply a function over each value in the stream:
  
  [source, clojure]
  ----
  (def stream (->> (s/from-coll [1 2])
                   (s/map inc)))
  
  (s/subscribe stream
               #(println "on-value:" %)
               #(println "on-error:" %)
               #(println "on-end"))
  
  ;; ==> on-value: 2
  ;; ==> on-value: 3
  ;; ==> on-end
  ----
  
  
  === Flat Map
  
  Convets a observable seequence that can contain other observable seequences in
  an other observable seequences that emits just plain values.
  
  The result is similar to concatenate all the underlying seequences.
  
  [source, clojure]
  ----
  (def stream (->> (s/from-coll [1 2])
                   (s/map #(sfrom-coll (range % (+ % 2))))
                   (s/flat-map))
  
  (s/subscribe stream
               #(println "on-value:" %)
               #(println "on-error:" %)
               #(println "on-end"))
  
  ;; ==> on-value: 1
  ;; ==> on-value: 2
  ;; ==> on-value: 2
  ;; ==> on-value: 3
  ;; ==> on-end
  ----
  
  
  === Skip
  
  Also, sometimes you just want to skip values from stream under different criteria.
  
  You can skip the first N values:
  
  [source, clojure]
  ----
  (def stream (->> (s/from-coll [1 2 3 4 5 6])
                   (s/skip 4)))
  
  (s/subscribe stream
               #(println "on-value:" %)
               #(println "on-error:" %)
               #(println "on-end"))
  
  ;; ==> on-value: 5
  ;; ==> on-value: 6
  ;; ==> on-end
  ----
  
  Skip while some condition evalutates to true:
  
  [source, clojure]
  ----
  (def stream (->> (s/from-coll [1 1 1 1 2 3])
                   (s/skip-while odd?)))
  
  (s/subscribe stream
               #(println "on-value:" %)
               #(println "on-error:" %)
               #(println "on-end"))
  
  ;; ==> on-value: 2
  ;; ==> on-value: 3
  ;; ==> on-end
  ----
  
  Or skip until an other observable yelds a value using `skip-until` (no example at
  this moment).
  
  
  === Take
  
  You also can limit the observale sequence to an specified number of elements:
  
  [source, clojure]
  ----
  (def stream (->> (s/from-coll [1 1 1 1 2 3])
                   (s/take 2)))
  
  (s/subscribe stream
               #(println "on-value:" %)
               #(println "on-error:" %)
               #(println "on-end"))
  
  ;; ==> on-value: 1
  ;; ==> on-value: 1
  ;; ==> on-end
  ----
  
  Or an condition expression evaluates to true:
  
  [source, clojure]
  ----
  (def stream (->> (s/from-coll [1 1 1 1 2 3])
                   (s/take-while odd?)))
  
  (s/subscribe stream
               #(println "on-value:" %)
               #(println "on-error:" %)
               #(println "on-end"))
  
  ;; ==> on-value: 1
  ;; ==> on-value: 1
  ;; ==> on-value: 1
  ;; ==> on-value: 1
  ;; ==> on-end
  ----
  
  
  === Slice
  
  This is a some kind of combination of `skip` and `take`, and returns a observable
  seequence that represents a portion delimited by start and end of the source
  observable seequence.
  
  [source, clojure]
  ----
  (def stream (->> (s/from-coll [1 2 3 4])
                   (s/slice 1 3)))
  
  (s/subscribe stream
               #(println "on-value:" %)
               #(println "on-error:" %)
               #(println "on-end"))
  
  ;; ==> on-value: 2
  ;; ==> on-value: 3
  ;; ==> on-end
  ----
  
  
  === Reduce
  
  Allows combine all results of an observable seequence using a combining function
  also called (reducing function):
  
  [source, clojure]
  ----
  (def stream (->> (s/from-coll [1 2 3 4])
                   (s/reduce + 0)))
  
  (s/subscribe stream
               #(println "on-value:" %)
               #(println "on-error:" %)
               #(println "on-end"))
  
  ;; ==> on-value: 10
  ;; ==> on-end
  ----
  
  
  === Buffer
  
  This transformer functions allow accomulate N specified values in a buffer and then
  emits them as one value.
  
  [source, clojure]
  ----
  (def stream (->> (s/from-coll [1 2 3 4])
                   (s/buffer 2)))
  
  (s/subscribe stream
               #(println "on-value:" %)
               #(println "on-error:" %)
               #(println "on-end"))
  
  ;; ==> on-value: [1 2]
  ;; ==> on-value: [3 4]
  ;; ==> on-end
  ----
  
  
  == Combinators
  
  === Choice
  
  Perform an arbitrary choice between two or more observable sequences and return the
  first value available from any provided observables.
  
  This kind if combinator works very well with operations that can timeout:
  
  [source, clojure]
  ----
  (def stream (s/choice
                (s/timeout 1000 :timeout)
                (s/timeout 900 :value)))
  
  (s/subscribe stream
               #(println "on-value:" %)
               #(println "on-error:" %)
               #(println "on-end"))
  
  ;; ==> on-value: :value
  ;; ==> on-end
  ----
  
  === Zip
  
  This combinator combines two observable seequences in one.
  
  [source, clojure]
  ----
  (def stream (s/zip
                (s/from-coll [1 2 3])
                (s/from-coll [2 3 4])))
  
  (s/subscribe stream
               #(println "on-value:" %)
               #(println "on-error:" %)
               #(println "on-end"))
  
  ;; ==> on-value: [1 2]
  ;; ==> on-value: [2 3]
  ;; ==> on-value: [3 4]
  ;; ==> on-end
  ----
  
  
  === Concat
  
  This cobinator concatenates two or more observable seequences.
  
  [source, clojure]
  ----
  (def stream (s/concat
                (s/from-coll [1 2])
                (s/from-coll [3 4])))
  
  (s/subscribe stream
               #(println "on-value:" %)
               #(println "on-error:" %)
               #(println "on-end"))
  
  ;; ==> on-value: 1
  ;; ==> on-value: 2
  ;; ==> on-value: 3
  ;; ==> on-value: 4
  ;; ==> on-end
  ----
  
  === Merge
  
  This combinator merges two or more observable seequences.
  
  [source, clojure]
  ----
  (def stream (s/concat
                (s/from-coll [1 2])
                (s/from-coll [3 4])))
  
  (s/subscribe stream
               #(println "on-value:" %)
               #(println "on-error:" %)
               #(println "on-end"))
  
  ;; ==> on-value: 1
  ;; ==> on-value: 3
  ;; ==> on-value: 2
  ;; ==> on-value: 4
  ;; ==> on-end
  ----
  
  NOTE: the order is not required to be the same always.
  
  
  == Bus
  
  This is an abstraction that combines observable seequence with the observer. So
  you can push values into it and transform and subscribe to it like any other
  seequence.
  
  === Creating a bus.
  
  You can create a bus instance using `bus` constructor function. There is an
  example of using bus for the both operations: push values and subscribe to it.
  
  [source, clojure]
  ----
  (def bus (s/bus))
  (def stream (-> bus
                  (s/skip 1)
                  (s/map inc)
                  (s/take 2)))
  
  (s/subscribe stream
               #(println "on-value:" %)
               #(println "on-error:" %)
               #(println "on-end"))
  
  (s/push! bus 1)
  (s/push! bus 2)
  (s/push! bus 1)
  (s/push! bus 2)
  
  ;; ==> on-value: 3
  ;; ==> on-value: 2
  ;; ==> on-end
  ----
  
  
  === Ending a bus
  
  You can end bus in any moment just executing `end!` function:
  
  [source, clojure]
  ----
  (def bus (s/bus))
  
  (s/subscribe bus
               #(println "on-value:" %)
               #(println "on-error:" %)
               #(println "on-end"))
  
  (s/end! bus)
  ;; ==> on-end
  ----
  
  
  == FAQ
  
  === That is the difference between hot and cold observables.?
  
  TBD
  
  