Meiosis-Tracer Documentation

Contents

Introduction

Meiosis-Tracer is a development and debugging tool that traces, rewinds, and replays snapshots of Flyd or Mithril streams. It can also work with other stream libraries such as RxJS, most.js, and so on.

You can also directly enter your own snapshots and send the values onto the streams. This works particularly well in Meiosis applications.

You can install Meiosis-Tracer with npm:

npm i -D meiosis-tracer

You can also download the JavaScript file from unpkg and add it to your page with a plain <script> tag. In that case it will be available as the meiosisTracer global variable.

Then use it either by adding it to your page, or with the Chrome DevTools Extension.

Adding the Tracer To Your Page

First, add an HTML element to your page where you want the tracer to be rendered, and give it a way to identify it via a selector. For example:

<div id="tracer" style="position: fixed; top: 0px; right: 0px;"></div>

Second, import the tracer and call it as a function, passing a selector that matches your HTML element and an array of streams that you want to trace. For example:

import meiosisTracer from "meiosis-tracer";

const models = ...; // a stream
const states = model.map(...); // another stream

meiosisTracer({ selector: "#tracer", streams: [ models, states ] });

This will render the tracer into the HTML element that has the tracer id.

See Using the Tracer for more details and examples.

Using the Chrome DevTools Extension

Meiosis-Tracer is now also available as a Chrome DevTools Extension, so that you can use it without needing to add it to your page.

You can get it from the Chrome Web Store.

Alternatively, you can run it directly from the source code. To do so, clone the repository:

git clone https://github.com/foxdonut/meiosis-tracer

Once installed:

To trace streams in your application, call meiosisTracer but DO NOT specify a selector:

import meiosisTracer from "meiosis-tracer";

const models = ...; // a stream
const states = model.map(...); // another stream

meiosisTracer({ streams: [ models, states ] });

The Meiosis-Tracer UI works in the same way either added to the page, or in DevTools.

See Using the Tracer for more details and examples.

Credits

The following repositories were very helpful in developing the Chrome extension for Meiosis-Tracer. My thanks and appreciation go to their authors!

Using the Tracer

At it simplest, the Tracer works with Flyd or Mithril streams without any configuration. Simply call meiosisTracer and indicate the streams that you want to trace. That's all you need if you are using the Chrome Extension. If you want to add the Tracer to your page instead, also indicate the selector.

Here is a Flyd example:

And here is the same example with Mithril-Stream:

The controls that you see at the top of the Tracer are as follows:

Each stream also has these controls:

By default, streams are labeled Stream 0, Stream 1, etc. To specify different labels, use objects in the streams array. Each object must have a stream property for the stream. Then, use label to indicate the label:

You can also specify options to the tracer itself, which apply to all streams. In the example below, we indicated the number of rows for the textarea, and how to stringify values:

The Tracer can also work with other stream libraries such as RxJS, most.js, and so on. In those cases, specify the listen and emit properties to indicate how to listen to a stream and how to emit a value onto a stream. Here is an example with RxJS:

For more examples using Meiosis-Tracer, see the Meiosis Examples.

Full List of Options

Options for meiosisTracer({ ... })

These are general options for the tracer. Stream-related options apply to all streams.

option purpose values default
selector CSS selector targetting the HTML element for the tracer string
stream array of streams to be traced array
direction layout direction for multiple streams row, column, auto column
rows number of rows in textareas number 15
cols number of columns in textareas number 50
autoSend whether or not to automatically send values boolean true
stringify how to convert a stream value to a string function JSON.stringify(val, null, 4)
parse how to parse a string to a stream value function JSON.parse(str)
listen how to listen to a stream function (stream, fn) => stream.map(fn)
emit how to send a value to a stream function (stream, value) => stream(value)

Stream Options

These are stream-specific options. Indicate these options within properties of the objects that you pass to the streams array.

option purpose values default
stream the stream to be traced stream
label the label for the stream string Stream N
hist whether or not to accumulate history boolean true
hide whether or not to initially hide the stream boolean false

Meiosis-Tracer is developed by @foxdonut00 / foxdonut and is released under the MIT license.