status-im
/
re-frame-10x
mirror of https://github.com/status-im/re-frame-10x.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update README.md

This commit is contained in:
Mike Thompson 2018-02-03 12:12:15 +11:00 committed by GitHub
parent c6835aab06
commit 80d11688e3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 12 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
README.md
View File

@ -1,17 +1,13 @@
# re-frame-trace # re-frame-trace
`re-frame-trace` let's you look at the inner workings of a running `re-frame` application. It presents as a programmer's dashboard, delivering curated insight and illumination. So, you'll use it to better understand your application and to debug it. `re-frame-trace` let's you look at the inner workings of a running `re-frame` application. It presents as a programmer's dashboard, delivering curated insight and illumination. Your capacity to debug will increase because you know more.
**Status:** Beta. [![Clojars Project](https://img.shields.io/clojars/v/day8.re-frame/trace.svg)](https://clojars.org/day8.re-frame/trace) [![CircleCI](https://circleci.com/gh/Day8/re-frame-trace.svg?style=svg)](https://circleci.com/gh/Day8/re-frame-trace)
**Note** also use the latest version of re-frame itself - currently `v0.10.4` (but please check yourself - out of date docs and all that)
### It Is Epoch Oriented ### It Is Epoch Oriented
`re-frame` applications are computationally regular. First an event happens, `re-frame` applications are computationally regular. First an event happens,
and then boom, boom, boom go a series of known computational steps (dominoes), and then boom, boom, boom go a series of known computational steps (aka dominoes),
in a known order. When this chain reaction completes, in a known order. When this chain reaction completes,
a `re-frame` app lapses into a quiescent state waiting for another a `re-frame` app enters a quiescent state waiting for another
event to kick off the next iteration of the same process. event to kick off the next iteration of the same process.
Each `re-frame` event and its consequent computation forms a bounded "epoch" Each `re-frame` event and its consequent computation forms a bounded "epoch"
@ -27,7 +23,7 @@ aspect of what `re-frame-trace` delivers.
As it runs, `re-frame` logs "trace" as data (not strings). As it runs, `re-frame` logs "trace" as data (not strings).
This data trace provides an x-ray of your app's functioning. This data trace provides an x-ray of your app's functioning.
`re-frame-trace` is essentially a consumer, processor and displayer of this xray trace data. `re-frame-trace` is essentially a consumer, processor and displayer of this x-ray trace data.
### More Data ### More Data
@ -35,7 +31,7 @@ While re-frame is a functional framework, it is
strongly defined by its "data oriented" design. `re-frame` strongly defined by its "data oriented" design. `re-frame`
"flows" data, in a loop, through the functions you provide. "flows" data, in a loop, through the functions you provide.
To understand what is happening in a `re-frame` app, you must understand To understand what is happening in a `re-frame` app, you must understand
what data is happening. what data is "happening".
So, data is at the core of `re-frame-trace` in both of the ways just described, So, data is at the core of `re-frame-trace` in both of the ways just described,
and data is a powerful and leverageable substrate. and data is a powerful and leverageable substrate.
@ -44,14 +40,11 @@ and data is a powerful and leverageable substrate.
Except, there's often too much data - you can drown in the detail. Except, there's often too much data - you can drown in the detail.
So, `re-frame-trace` tries to be a "dashboard" which curates the So, `re-frame-trace` tries to be a "dashboard" which curates this
"raw data" into "information" through various kinds of analysis "raw data" into "information" through various kinds of analysis
and "roll ups". It should deliver insight "at a glance", while still allowing and "roll ups". It should deliver insight "at a glance", while still allowing
you to drill down into the detail. you to drill down into the detail.
Okay. So, we now know enough to do a summary: this tool is an epoch-oriented,
interactive data dashboard which delivers insights and assists debugging.
### Which Is Helpful How? ### Which Is Helpful How?
Four ways: Four ways:
@ -59,20 +52,25 @@ Four ways:
1. It helps you to learn `re-frame`. Simply looking at 1. It helps you to learn `re-frame`. Simply looking at
the "raw traces" provides insight into how it operates. Even experienced the "raw traces" provides insight into how it operates. Even experienced
re-framians, er, like me, have learned a lot. re-framians, er, like me, have learned a lot.
2. It helps you to explore and learn an unfamiliar `re-frame` codebase. 2. It helps you to explore and learn an unfamiliar `re-frame` codebase.
When I click, over here, on this "X" button, it shows me what event is `dispatch`-ed When I click, over here, on this "X" button, it shows me what event is `dispatch`-ed
and in what namespace the associated event handler is registered. And, and in what namespace the associated event handler is registered. And,
"oh look, that's interesting - four subscriptions recalculated". Etc. "oh look, that's interesting - four subscriptions recalculated". Etc.
3. It helps you with debugging. You see an x-ray of your app's functioning. 3. It helps you with debugging. You see an x-ray of your app's functioning.
In particular, it will assist you to write and debug In particular, it will assist you to write and debug
event handlers, which is useful because they hold most of the logic event handlers, which is useful because they hold most of the logic
in your `re-frame` apps. in your `re-frame` apps.
4. It helps you to find performance problems and/or detect where there is 4. It helps you to find performance problems and/or detect where there is
unnecessary computation occurring. unnecessary computation occurring.
Deeper knowledge is the goal. Easier debugging is the symptom.
### Temporary Warning ### Temporary Warning
> Some of the descriptions above are aspirational. `re-frame-trace` remains a WIP experiment. But we're getting there. > Some of the descriptions above are aspirational. `re-frame-trace` remains a WIP experiment. But we're getting there.
## A Visual Sampler ## A Visual Sampler