Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Consider adding a Reactive operator decision tree/flowchart/table reference #117

Open
banchan86 opened this issue Jan 14, 2025 · 3 comments · May be fixed by #130
Open

Consider adding a Reactive operator decision tree/flowchart/table reference #117

banchan86 opened this issue Jan 14, 2025 · 3 comments · May be fixed by #130
Labels
documentation Improvements or additions to documentation

Comments

@banchan86
Copy link
Contributor

banchan86 commented Jan 14, 2025 •
edited
Loading

Based on an idea proposed by @jonnew on Discord, to enhance our Reactive operator documentation, we might want to consider adding a decision tree to easily choose Reactive operators. This could be added as an article on the main docs (hence why this issue is raised here) and added as a link to the respective API pages for the Reactive operators.

Possible references
@banchan86 banchan86 added the article New documentation article label Jan 14, 2025
@banchan86
Copy link
Contributor Author

banchan86 commented Feb 10, 2025 •
edited
Loading

As I was playing around with this, I thought that maybe having a decision tree that leads to every single operator is a bit intimidating (has too many levels, hard to check at a glance).

  • A simple grouping might suffice, as represented in this mermaid diagram made from just the operators in the Bonsai.Reactive namespace.
  • Might be better as a table if it's just a single level.
  • Not final, I still need to check, there are definitely some operators missing (like the schedulers) and I need to verify each operator.
  • Currently too wide, but maybe we can split the operators that operate on a single observable sequence from those that take two sequences.
  • Can add links to each operators API reference page, as well as a short description on a hover tooltip.
flowchart TD
    id1(I want to...)
    id2(..do something with 1 sequence.)
    id3(..do something with more than 1 sequence.)
    id4("`**Compute a value**
    Accumulate
    Average
    Count
    ElementIndex
    IsEmpty
    Max / MaxBy
    Min / MinBy
    Sum
    `")
    id5("`**Filter or group elements**
    BufferCount
    BufferTime
    Distinct / DistinctBy 
    DistinctUntilChanged 
    DistinctUntilChangedBy 
    First / FirstOrDefault
    Last / LastOrDefault
    Skip / SkipLast
    Slice 
    Take / TakeLast
    WindowCount
    WindowTime
    `")
    id6("`**Do something with time**
    CombineTimestamp
    Delay
    DelaySubscription
    GateInterval
    SampleInterval
    Throttle
    Timeout
    Timer
    TimeInterval
    Timestamp
    `")
    id7("`**Repeat or Retry**
    Repeat
    RepeatCount
    Retry
    RetryCount
    `")
    id8("`**Transform a sequence**
    Materialize
    Dematerialize
    OrderBy
    OrderByDescending
    ThenBy
    ThenByDescending
    `")
    id9("`**Create new sequences**
    CreateObservable
    Defer
    GroupBy
    SelectMany
    `")
    id10("`**Create subscriptions**
    AsyncSubject
    BehaviourSubject
    Publish
    PublishSubject
    Replay
    ReplaySubject
    ResourceSubject
    `")
    id11("`**Filter or select elements**
    BufferTrigger
    Gate
    Sample
    SkipUntil
    SubscribeWhen
    TakeUntil
    Window
    WindowTrigger
    `")
    id12("`**Combine or merge sequences**
    Catch
    CombineLatest
    Concat
    Merge
    OnErrorResumeNext
    WithLatestFrom
    Zip
    `")
    id1 --> id2
    id1 --> id3
    id2 --> id4
    id2 --> id5
    id2 --> id6
    id2 --> id7
    id2 --> id8
    id2 --> id9
    id2 --> id10
    id3 --> id11
    id3 --> id12
Loading

@banchan86 banchan86 mentioned this issue Feb 11, 2025
Open
@banchan86
Copy link
Contributor Author

This is a mockup of the table format. We can include links to the API reference for each operator, together with a short description of each operator as a tooltip (I only did the first two as an example). If the table is too wide, we can further split it up.

Compute a value Filter or select elements Do something with time Repeat sequences Group or arrange elements Create new sequences Create subscriptions Filter or select elements using another sequence Combine or merge two or more sequences Handling exceptions
Accumulate
Average
Count
ElementIndex
IsEmpty
Max / MaxBy
Min / MinBy
Sum		 Distinct
DistinctBy
DistinctUntilChanged
DistinctUntilChangedBy
First / FirstOrDefault
Last / LastOrDefault
Skip / SkipLast
Slice
Take / TakeLast

CombineTimestamp
Delay
DelaySubscription
GateInterval
SampleInterval
Throttle
Timeout
Timer
TimeInterval
Timestamp		 Repeat
RepeatCount		 BufferCount
BufferTime
OrderBy
OrderByDescending
ThenBy
ThenByDescending
WindowCount
WindowTime		 CreateObservable
Defer
GroupBy
SelectMany		 AsyncSubject
BehaviourSubject
Publish
PublishSubject
Replay
ReplaySubject
ResourceSubject		 BufferTrigger
Gate
Sample
SkipUntil
SubscribeWhen
TakeUntil
Window
WindowTrigger
CombineLatest
Concat
Merge
WithLatestFrom
Zip		 Catch
Retry
RetryCount
Materialize
Dematerialize
OnErrorResumeNext

@banchan86 banchan86 changed the title Consider adding a Reactive operator decision tree/flowchart Consider adding a Reactive operator decision tree/flowchart/table reference Feb 17, 2025
@banchan86 banchan86 added documentation Improvements or additions to documentation and removed article New documentation article labels Feb 17, 2025
@banchan86
Copy link
Contributor Author

banchan86 commented Feb 21, 2025 •
edited
Loading

Another option for a table layout is having a tab layout, with each tab being a different grouping of reactive operators. Each table would just have two columns, the operator name, and the description. Unfortunately I am unable to generate a preview for that in the GitHub issue comment but it will look similar to what is being done for the editor shortcut PR.

@banchan86 banchan86 linked a pull request Feb 22, 2025 that will close this issue
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
documentation Improvements or additions to documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Add core reactive operator reference table banchan86/bonsai_docs_test
1 participant
@banchan86