RxJS Marble Diagrams

RxJS Marble Diagrams are made to visualize the values emitted from the RxJS Observable over timeline.</p>

Hi in this article I will explain why we need marble diagrams and what are the benefits of Marble Diagrams.

Inventor of Rx Marbles

In 2009 Erik Meijer first discovered Marbles concept for Rx project please checkout Erik Meijer 15 Minutes Talk Here  It was called Rx Marbles because, it was first created for C# language in Microsoft team.

Why RxJS Marbles

RxJS Marbles are helpful to visualize the values coming from observable. In JavaScript we call it RxJS Marbles. Similarly in Java it is called RxJava Marble Diagrams and so on. Marble Diagrams helps us to understand the RxJS Operators and their behavior. Realizing the concept of RxJS Operators is difficult unless you see them how they are effecting the behavior of underneath streams. Therefore, I believe Marble Diagrams are great tool to visualize the patterns of stream events and derive its behavior over time.

suppose I told you that RxJS interval method takes an argument of 10 and hence emits only 10 values. This behavior is understandable, since it is a simple example. However, if we have complex operator or collection of operators applied over source/s observables then It is very difficult to understand how values will be emitted in result observable. Therefore, visualizing result values and source values over timeline gives much clarity.

André Staltz has created nice website called as rxmarbles.com that can be used to visualize the marbles and play it out live for major RxJS operators. I am using some pics from same website to show you visual marbles.

Explaining RxJS method: interval(10)

[caption id="attachment_784" align="aligncenter" width="1412"] 10 values marble diagrams interval[/caption]

In above diagram one can easily say that okay, I can see 10 circles / marbles with their values. Which is the explanation of method interval(10). So without explaining the behavior of observable you can understand what is its behavior by just viewing its diagram. That is the power of Marble diagrams.

How to Draw Marble Diagrams

Marbles are normally drawn by circles which indicates the values. Marbles are drawn over Timeline. Timeline is horizontal line which moves from left to right, it indicates the time passage. In order to indicate the stream is completed we use pipe symbol |and in order for indicating error over timeline we use X symbol.

Below are the symbols used in order to draw marble diagram.

• X error (notification)
• | completion (notification)
• O values (emitted by observable)
• -----> Time line

Examples of Marble Diagrams

Emitting 10 Values and complete

In above marble diagrams each circle represents marbles and inside the circle you can see the values.  The Pipe symbol at the end indicates on 10th value the stream gets completed. Therefore, here we knew that this is an observable which emitted 10 serial numbers and then complete. That is interval(10) .

Emitting Value and Error out

[caption id="attachment_785" align="alignnone" width="1303"] 3 values marble diagrams with error[/caption]

In above marble diagrams X symbol represents Error notification and hence this behavior says that this observable emitted 3 values and then error out.

Marble Diagrams used in Unit Testing

In order to write RxJS testing now a days marble diagrams are used as domain specific language (DSL).  And it is used to write unit test in order to assert observable and operators behavior. There are many node libraries which supports marble testing. Out of that jasmine-marbles is one the famous one. I am creating one pluralsight course where I will be explaining Marble Testing  and please stay tuned to know more about the marble diagrams.

Marble Diagrams to visualize Operator Behavior

The first marble diagram line represents source observable the middle line where flip is written represents the operator. The last line represents the result observable. In the above example we have applied flip operator on source observable and we got result operator.

Some More Examples of Marble Diagrams

[caption id="attachment_786" align="alignnone" width="1231"] merge operator marble diagram[/caption]

In this above marble diagram we are trying to understand merge operator.

• The  first source observable emitted 5 values and completed.
• The 2nd source observable emitted 2 values and completed.
• In the result observable you can see whenever which ever value comes first has been put early. So value 1 from 2nd observable arrives earlier than value 80 from first observable.

Benefits of Marble Diagrams

There are many benefits however below are the major ones:

• Makes easy to understand the behavior of observable and operators
• Marbles are used in unit testing to make our test more readable, visual and synchronous.
• Marble diagrams are used in unit testing also to find out race conditions.

Playground for Marble Diagrams

I always search for playground where I can try my own things. In order to see Marbles drawn automatically from your RxJS Code please go to the Animated playground for RxJS Observable it is nice website where you can see the marbles diagrams drawn live based on the RxJS code.

[caption id="attachment_788" align="alignnone" width="1629"] live marble diagrams drawn[/caption]

Please feel free to ask questions , give suggestions and share your thoughts here !