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

Docs

This commit is contained in:
Mike Thompson 2018-01-18 14:21:03 +11:00
parent 0f8adeeab5
commit e6415c849c
1 changed files with 24 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
README.md
View File

@ -1,7 +1,7 @@
# re-frame-trace # re-frame-trace
`re-frame-trace` is a programmer's dashboard. It allows you to see inside a running `re-frame` `re-frame-trace` is a programmer's dashboard. It helps you to see inside a running `re-frame`
application, helping you to understand it and debug it. application, allowing you to better understand it and debug it.
**Status:** Alpha. [![Clojars Project](https://img.shields.io/clojars/v/day8.re-frame/trace.svg)](https://clojars.org/day8.re-frame/trace) **Status:** Alpha. [![Clojars Project](https://img.shields.io/clojars/v/day8.re-frame/trace.svg)](https://clojars.org/day8.re-frame/trace)
@ -9,24 +9,23 @@ application, helping you to understand it and debug it.
**Note** [the latest version 0.1.14](https://github.com/Day8/re-frame-trace/releases/tag/0.1.14) ALSO requires the latest version of re-frame itself - `v0.10.3-alpha2`. **Note** [the latest version 0.1.14](https://github.com/Day8/re-frame-trace/releases/tag/0.1.14) ALSO requires the latest version of re-frame itself - `v0.10.3-alpha2`.
## How It Might Help You ### What It Can Do For You
What it can do for you: > The following list is aspirational. `re-frame-trace` remains a WIP. We're getting there.
- Help you to learn `re-frame`. If you are new to `re-frame`, it will assist you to
1. Helps you to learn `re-frame`. If you are new to `re-frame`, it will assist you to
understand the data flows involved (the dominoes). understand the data flows involved (the dominoes).
- Help you to explore and learn an unfamiliar `re-frame` codebase. 2. Helps you to explore and learn an unfamiliar `re-frame` codebase.
When I click on this "X" button, it shows me what event is `dispatch`-ed When I click 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.
- Help you with debugging. In particular, it will assist you to write and debug 3. Helps you with debugging. In particular, it will assist you to write and debug
event handlers, which is useful because they hold most of the logic in your `re-frame` apps. event handlers, which is useful because they hold most of the logic in your `re-frame` apps.
- Help you to find performance problems and/or detect where there is
4. Helps you to find performance problems and/or detect where there is
unnecessary computation occurring. unnecessary computation occurring.
(Okay, so this list is slightly aspirational. `re-frame-trace` is ### Epoch Oriented
absolutely useful, and you should use it, but delivery against the ideal above is uneven)
## 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 (dominoes),
@ -38,31 +37,31 @@ Each `re-frame` event and its consequent computation forms a discrete "epoch"
which can be inspected, analysed and understood independently of other epochs. This which can be inspected, analysed and understood independently of other epochs. This
tool is epoch-oriented. tool is epoch-oriented.
And, yes, there's the ability to do time travel debugging - you can go backwards And, yes, it is something of a "time travel debugger" - you can go backwards
and forwards through epochs - but that's really not the most interesting aspect and forwards through epochs - but that's really not the most interesting or powerful
of what you get. aspect of what `re-frame-trace` delivers.
## It is about Data ### It is about Data
As it runs, `re-frame` generates detailed "trace" which is captured as data (not strings). As it runs, `re-frame` generates detailed "trace" which is captured as data, not strings.
This trace is like an x-ray of the app's functioning. This trace provides an x-ray of your app's functioning.
In addition, re-frame is as much "data oriented" as it is functional in design. In addition, re-frame is as much "data oriented" as it is functional in design.
It "flows" data, in a loop, through the functions you provide. It "flows" data, in a loop, through the functions you provide.
So, data is at the center of `re-frame-trace`. So, data is at the center of `re-frame-trace`.
## Data Dashboard ### Data Dashboard
There's often too much data - too much detail. There's often too much data - too much detail.
So, `re-frame-trace` tries to be something of a "dashboard" in the sense that So, `re-frame-trace` tries to be something of a "dashboard" in the sense that
it tries to turn "raw data" into "information" through curated analysis, and "roll ups" it tries to turn "raw data" into "information" through curated analysis, and "roll ups"
which deliver insight "at a glance". Then allowing you to "drill into the detail". designed to deliver insight "at a glance". But still allowing you to "drill into the detail".
Right. So, this tool an epoch-oriented, interactive data dashboard for Right. So, this tool an epoch-oriented, interactive data dashboard for
gaining insights and assisting debugging. It is also a work in progress, gaining insights and assisting debugging. But, it is also a work in progress,
so this grand description runs well ahead of what is delivered right now. so these magnificent descriptions run well ahead of what is delivered right now.
But we're getting there. But we're getting there.