doc: Improve description of action and transaction (#3017)
#3018
Conversation
Closer description of actual implementation.
|
docs/actions.md
Outdated
| @@ -18,7 +18,7 @@ All applications have actions. An action is any piece of code that modifies the | |||
|
|
|||
| MobX requires that you declare your actions, although [`makeAutoObservable`](observable-state.md#makeautoobservable) can automate much of this job. Actions help you structure your code better and offer the following performance benefits: | |||
|
|
|||
| 1. They are run inside [transactions](api.md#transaction). No observers will be updated until the outer-most action has finished, guaranteeing that intermediate or incomplete values produced during an action are not visible to the rest of the application until the action has completed. | |||
| 1. They are run inside [transactions](api.md#transaction). No reactions will be run until the outer-most action has finished, guaranteeing that intermediate or incomplete values produced during an action are not visible to the rest of the application until the action has completed. However, computeds will update when they have become stale and are read during an action. | |||
There was a problem hiding this comment.
However, computeds will update when they have become stale and are read during an action.
I don't think it makes sense to mention computed here as some special case. It behaves the same as any observable value in regards to transactions. It always yields most up to date value, (trans)action or not. It is a computed value in the end.
Perhaps if necessary, something like:
"Observable values (including computeds) are unaffected by action and always yield current value."
??
There was a problem hiding this comment.
Fair enough, it was more to contrast computed from reaction as an observer, but that was due to the previous text mentioning observers. Since that is gone, indeed no need to have computed here at all.
There was a problem hiding this comment.
Just to elaborate a bit and perhaps justify the original wording a little...
From user's perspective the library conceptually consists of two parts: consumers (observers) and consumables (observables).
Computed is part of the consumable part (observable). While computed is internally "observer", it can't be used alone to consume observables.
Action is only relevant for the consuming part (observers) - reaction/autorun/observer.
Unfortunatelly neither the implementation or API maps to this natural division very well.
The most precise word to use here, would be Reaction (with capital R), which is internally used to implement all consumers (observers) - however since it's just an internal concept, nobody would understand that either.
There was a problem hiding this comment.
Right, yeah, building a consistent & coherent DSL is hard, especially if it happens incrementally, I feel ya : )
Closer description of actual implementation.