Repository navigation
docs: clarify streaming resource data flow - #71233
joaodemarco wants to merge 2 commits into
Conversation
Clarify the Streaming Resources documentation to make the data flow between the source signal and the resource explicit. - Explain that `stream` should return a signal representing a continuously updating data source. - Clarify that the resource consumes the signal's value and updates when the signal changes. - Explain that `userUpdates` simulates an external source such as WebSocket or SSE. - Update the example comment to make the direction of the data flow explicit. - Distinguish `stream` from `loader` for continuously updating versus one-time asynchronous operations.
atscott
left a comment
atscott
left a comment
There was a problem hiding this comment.
The update to the comment in the code snippet (// Simulate a new value arriving from the external data source:) is helpful for making it clear that userUpdates is just mocking incoming events rather than something the resource writes back to.
However, the added prose introduces quite a bit of repetition. Paragraphs 2 and 4 end up saying the same thing back-to-back ("The resource uses the signal's value as its current value and updates when the signal changes" vs "The resource reads the signal's value and updates its own value whenever the signal changes"). It's also slightly imprecise to say the resource uses the signal's value directly as its current value, since stream expects a ResourceStreamItem wrapper ({value: T} | {error: Error}) that gets unpacked.
I'd suggest keeping the updated code comment and either dropping the extra prose or trimming it to a single sentence introducing the example, leaving the original contrast between stream and loader intact.
|
Thanks for the feedback! I've removed the repetitive explanation and kept the original |
joaodemarco
changed the title
|
I removed the |
|
No need for a scope for docs commit, can you make sure to squash both commits. We want this change to be a single commit. Thank you. |
3 participants
Clarify the Streaming Resources documentation to make the data flow between the source signal and the resource explicit.
streamshould return a signal representing a continuously updating data source.userUpdatessimulates an external source such as WebSocket or SSE.streamfromloaderfor continuously updating versus one-time asynchronous operations.PR Checklist
Please check if your PR fulfills the following requirements:
PR Type
What kind of change does this PR introduce?
What is the current behavior?
The Streaming Resources documentation does not clearly explain the data flow between the source signal and the resource.
The current example may give the impression that the Resource updates the source signal, rather than consuming a signal that represents an external, continuously updating data source.
Issue Number: N/A
What is the new behavior?
The documentation now explicitly explains that:
streamshould return a signal representing a continuously updating data source.Does this PR introduce a breaking change?
Other information
This PR only updates the documentation and example comments. It does not modify the Resource API or application behavior.