Docs: provide examples regarding stateful encapsulation and "Good Action Hygiene"

[damienwebdev]

I was watching the talk on Good Action Hygiene @MikeRyanDev gave at ngConf and it led me to a few obvious questions that I don't think are well documented or described by existing documentation.

Example

To illustrate some of these questions, I propose the following example:

1. I have a sidebar in my application that has the following state changes "close" or "toggle."
2. I have a button that I can click to trigger "toggle"
3. I have a "close" button that can be clicked to trigger "close"
4. I also trigger "close" when a routing event occurs.

In order to keep "Good Action Hygiene", theoretically my sidebar reducer has to be aware of two unique state changes:

1. "Sidebar Toggle"
2. "Sidebar Close"

Attempting to keep "Good Action Hygiene" when my sidebar "dumb" component starts to become reused in multiple instances across various aspects of the application is hard and creates the following two problems:

Difficult/Impossible Stateful Code Reuse

Reusing state, actions, reducers, selectors, and effects of a given feature is not described well currently and at the moment seems difficult and pretty much impossible whilst maintaining "Good Action Hygiene".

Poor Encapsulation

The more major issue in this scenario is poor encapsulation and violation of the "Open/Closed" Principle.

In the above example I see the following issues:

1. For 2 & 3, the sidebar has to be aware of an external button that can "toggle" it. Good Action Hygiene forces me to change my sidebar reducer when I add a new button that can control it.
2. For 4, Good Action Hygiene forces me to change my sidebar's reducer when I add route monitoring to my sidebar.

Potential Solutions

I see three approaches here:

1. Reusing the same action
   • Appears bad due to lack of clarity, painful debugging and maintenance (you mentioned this).
2. Update my sidebar to always be aware of the new features that can control it
   • Seems bad because it clearly violates Open/Closed Principle
   • From the talk, it appears that you're advocating for this one.
3. Add a "transformation" layer (potentially effects) in each new feature area to transform any new actions generated by the feature area into the appropriate actions in the "sidebar".
   • Seems bad because I'm adding code to handle a "maybe?" bad abstraction

Personally, I dislike all three of those which makes me uncertain about what the best approach is here; thus the desire for documentation. Do you happen to have a recommendation, pattern or documentation to remediate the above?

Additional Comments

Packaging Stateful Components

This conceptual issue, the lack of pattern, and the lack of documentation make writing modularized features that use @ngrx/store (think npm packages) really hard to reason about. As I understand it, I would never be able to publish a stateful package because it would be useless to any consumers since they can't add their own actions to the reducers of the system, as it would violate "Good Action Hygiene".

Robustness Principle Considerations

The idea of actions is very much like HTTP or any kind of messaging protocol. Which leads us basically back to the idea of contravariance and covariance and the Robustness Principle, so these should probably be taken into consideration.

Polymorphism

In the talk, there's even an argument against subtyping, which throws out the concept of polymorphic actions, so there's even more pain point there, and probably should be documented.

I would be willing to submit a PR for the docs ❤️

[x] Yes (Assistance is provided if you need help submitting a pull request)
[ ] No

Final Notes

According to @timdeschryver this may well be covered by this article, yet even @timdeschryver admits this problem is hard and that:

sometimes being a dev is hard

So I think this issue is worth addressing.

cc: @MikeRyanDev @brandonroberts @timdeschryver

[damienwebdev]

As this got bumped, I figured I would revitalize this conversation with some additional learnings and commentary on how we've addressed this in Daffodil(the original reason for this question).

Of interest to those curious about solving this problem may be this PR (which references a .drawio file, but I'll add a picture to the PR as well).

In short, there's a documentation weakness that I see in @ngrx/store today: using dependency injected reducers.

To clarify, the sidebar problem can be fixed by:

1. Exposing a few "helper" functions from your custom package's state API (much like entity adapter does)
2. Allowing other packages to process their own actions, and as a result, modify the existing state diagram (with the previously described functions exposed by your state library) by injecting their own reducers
3. Having the exposing package compose the reducers together in some meaningful way.

What this means may be different for every package, but the pattern is useful.

Although, I will be the first to say that this pattern has drawbacks:

• The order in which injected reducers run becomes relevant (so exposing an ordering mechanism becomes likely).
• Typing becomes more difficult to reason about at the level of the "composed" result in dependent code that uses the state computed by DI'd reducers. For example, consider what happens when a DI'd reducer is removed; all of a sudden the expected type isn't correct.

But, the benefits far outweigh the costs IMHO:

1. Your action stream winds short and precise.
2. Your redux log is simple and you can see precisely how state gets changed without all sorts of complicated actions littered in your logs.
3. Actions are more explicit about where they come from. The action may touch on many aspects of state -- but guess what, that's likely what you intended.

As a final commentary, composing packages together has always been one of the most important aspects of building well-architected software. Without it, software becomes heavy, unwieldy, and monolithic. With it, software becomes wiry and complicated: See node_modules.

You have to drink poison, regardless of which you choose.

@alex-okrushko and I had a discussion on this topic a year or so back, and DI'd reducers were advised against, Since that, I've seen @alex-okrushko dislike meta-reducers as well.

IMHO I think it's a choice that one has to make. For most, DI'd reducers and meta-reducers are overkill and confusing. Yet, for the select few they are quite the useful hammer.