Meiosis-Tracer Documentation

Contents

Introduction

Meiosis-Tracer is a development and debugging tool that traces, rewinds, and replays snapshots of streams such as flyd, Mithril Stream, and Meiosis's own Simple Stream.

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

Installation

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
cd meiosis-tracer
npm ci
npm start

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 its simplest, the Tracer works with Simple Stream, 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 an example that uses Meiosis:

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've indicated the number of rows for the textarea, and how to stringify values. This example uses Meiosis-Setup.

These examples are also available here so that you can run them in your browser with the Chrome Devtools version of Meiosis-Tracer.

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
streams array of streams to be traced array
direction layout direction for multiple streams row, column, auto column
theme add a theme-<name> class any string light
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.