Update CHANGELOG.md and README.md

solid-process · Mar 15, 2024 · 20a1594 · 20a1594
1 parent c11b6ff
commit 20a1594
Show file tree

Hide file tree

Showing 2 changed files with 64 additions and 24 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,36 +1,37 @@
 - [\[Unreleased\]](#unreleased)
+  - [Changed](#changed)
 - [\[0.13.0\] - 2024-02-01](#0130---2024-02-01)
   - [Added](#added)
-  - [Changed](#changed)
+  - [Changed](#changed-1)
 - [\[0.12.0\] - 2024-01-07](#0120---2024-01-07)
   - [Added](#added-1)
-  - [Changed](#changed-1)
+  - [Changed](#changed-2)
 - [\[0.11.0\] - 2024-01-02](#0110---2024-01-02)
   - [Added](#added-2)
-  - [Changed](#changed-2)
+  - [Changed](#changed-3)
 - [\[0.10.0\] - 2023-12-31](#0100---2023-12-31)
   - [Added](#added-3)
 - [\[0.9.1\] - 2023-12-12](#091---2023-12-12)
-  - [Changed](#changed-3)
+  - [Changed](#changed-4)
   - [Fixed](#fixed)
 - [\[0.9.0\] - 2023-12-12](#090---2023-12-12)
   - [Added](#added-4)
-  - [Changed](#changed-4)
+  - [Changed](#changed-5)
 - [\[0.8.0\] - 2023-12-11](#080---2023-12-11)
   - [Added](#added-5)
-  - [Changed](#changed-5)
+  - [Changed](#changed-6)
   - [Removed](#removed)
 - [\[0.7.0\] - 2023-10-27](#070---2023-10-27)
   - [Added](#added-6)
-  - [Changed](#changed-6)
+  - [Changed](#changed-7)
 - [\[0.6.0\] - 2023-10-11](#060---2023-10-11)
   - [Added](#added-7)
-  - [Changed](#changed-7)
+  - [Changed](#changed-8)
 - [\[0.5.0\] - 2023-10-09](#050---2023-10-09)
   - [Added](#added-8)
 - [\[0.4.0\] - 2023-09-28](#040---2023-09-28)
   - [Added](#added-9)
-  - [Changed](#changed-8)
+  - [Changed](#changed-9)
   - [Removed](#removed-1)
 - [\[0.3.0\] - 2023-09-26](#030---2023-09-26)
   - [Added](#added-10)
@@ -42,6 +43,13 @@
 
 ## [Unreleased]
 
+### Changed
+
+- **(BREAKING)** Replace trasitions metadata `:ids_tree`, and `:ids_matrix` with `:ids` property. This property is a hash with the following keys:
+  - `:tree`, a graph/tree representation of the transitions ids.
+  - `:level_parent`, a hash with the level (depth) of each transition and its parent id.
+  - `:matrix`, a matrix representation of the transitions ids. It is a simplification of the `:tree` property.
+
 ## [0.13.0] - 2024-02-01
 
 ### Added

diff --git a/README.md b/README.md
@@ -73,7 +73,7 @@ Use it to enable the [Railway Oriented Programming](https://fsharpforfunandprofi
     - [`BCDD::Result::Context::Expectations`](#bcddresultcontextexpectations)
     - [Mixin add-ons](#mixin-add-ons)
 - [`BCDD::Result.transitions`](#bcddresulttransitions)
-  - [`ids_tree` *versus* `ids_matrix`](#ids_tree-versus-ids_matrix)
+  - [`metadata: {ids:}`](#metadata-ids)
   - [Configuration](#configuration)
     - [Turning on/off](#turning-onoff)
     - [Setting a `trace_id` fetcher](#setting-a-trace_id-fetcher)
@@ -1860,8 +1860,11 @@ result.transitions
   :metadata => {
     :duration => 0,   # milliseconds
     :trace_id => nil, # can be set through configuration
-    :ids_tree => [0, [[1, []], [2, []]]],
-    :ids_matrix => {0 => [0, 0], 1 => [1, 1], 2 => [2, 1]}
+    :ids => {
+      :tree => [0, [[1, []], [2, []]]],
+      :matrix => { 0 => [0, 0], 1 => [1, 1], 2 => [2, 1]},
+      :level_parent => { 0 => [0, 0], 1 => [1, 0], 2 => [1, 0]}
+    }
   },
   :records=> [
     {
@@ -1942,18 +1945,21 @@ result.transitions
 
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
-### `ids_tree` *versus* `ids_matrix`
-
-The `:ids_matrix`. It is a simplification of the `:ids_tree` property (a graph/tree representation of the transitions ids).
+### `metadata: {ids:}`
 
-The matrix rows are the direct transitions from the root transition block, and the columns are the transitions nested from the direct transitions.
+The `:ids` metadata property is a hash with three properties:
+- `:tree`, a graph/tree representation of the transitions ids.
+- `:level_parent`, a hash with the level (depth) of each transition and its parent id.
+- `:matrix`, a matrix representation of the transitions ids. It is a simplification of the `:tree` property.
 
-Use these data structures to build your own visualization of the transitions.
+Use these data structures to build your own visualization.
 
 > Check out [Transitions Listener example](examples/single_listener/lib/single_transitions_listener.rb) to see how a listener can be used to build a visualization of the transitions, using these properties.
 
 ```ruby
-# ids_tree         #
+# tree:
+# A graph representation (array of arrays) of the transitions ids.
+#
 0                  # [0, [
 |- 1               #   [1, [[2, []]]],
 |  |- 2            #   [3, []],
@@ -1964,7 +1970,24 @@ Use these data structures to build your own visualization of the transitions.
 |     |- 7         #   [8, []]
 |- 8               # ]]
 
-# ids_matrix       # {
+# level_parent:
+# Transition ids are the keys, and the level (depth) and parent id the values.
+                   # {
+0                  #   0 => [0, 0],
+|- 1               #   1 => [1, 0],
+|  |- 2            #   2 => [2, 1],
+|- 3               #   3 => [1, 0],
+|- 4               #   4 => [1, 0],
+|  |- 5            #   5 => [2, 4],
+|  |- 6            #   6 => [2, 4],
+|     |- 7         #   7 => [3, 6],
+|- 8               #   8 => [1, 0]
+                   # }
+
+# matrix:
+# The rows are the direct transitions from the root transition block,
+# and the columns are the nested transitions from the direct ones.
+                   # {
 0 | 1 | 2 | 3 | 4  #   0 => [0, 0],
 - | - | - | - | -  #   1 => [1, 1],
 0 |   |   |   |    #   2 => [1, 2],
@@ -1994,8 +2017,14 @@ result = SumDivisionsByTwo.call(20, 10)
 # => #<BCDD::Result::Success type=:sum value=15>
 
 result.transitions
-
-{:version=>1, :records=>[], :metadata=>{:duration=>0, :ids_tree=>[]}}
+{
+  :version=>1,
+  :records=>[],
+  :metadata=>{
+    :duration=>0,
+    :ids=>{:tree=>[], :matrix=>{}, :level_parent=>{}}, :trace_id=>nil
+  }
+}
 ```
 
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
@@ -2020,7 +2049,7 @@ Use it to build your additional logic on top of the transitions tracking. Exampl
   - Log the transitions.
   - Perform a trace of the transitions.
   - Instrument the transitions (measure/report).
-  - Build a visualization of the transitions (Diagrams, using the `records` + `:ids_tree` and `:ids_matrix` properties).
+  - Build a visualization of the transitions (Diagrams, using the `records` + `metadata: {ids:}` properties).
 
 After implementing your listener, you can set it to the `BCDD::Result.config.transitions.listener=`:
 
@@ -2086,8 +2115,11 @@ class MyTransitionsListener
   #   :metadata => {
   #     :duration => 0,
   #     :trace_id => nil,
-  #     :ids_tree => [0, [[1, []], [2, []]]],
-  #     :ids_matrix => {0 => [0, 0], 1 => [1, 1], 2 => [2, 1]}
+  #     :ids => {
+  #       :tree => [0, [[1, []], [2, []]]],
+  #       :matrix => { 0 => [0, 0], 1 => [1, 1], 2 => [2, 1]},
+  #       :level_parent => { 0 => [0, 0], 1 => [1, 0], 2 => [1, 0]}
+  #     }
   #   },
   #   :records => [
   #     # ...