doc: add notes about non-conforming streams #29895
Conversation
nodejs-github-bot
added
doc
ronag
force-pushed
the
notes-about-override
branch
from
6c7173d
to
7ce4453
Compare
Yes, nothing we can do about that... but we can still discourage it so future users are able to implement streams as correctly as possible?
What do you mean? I don't think most people that override public methods are aware of the problems it might cause. |
|
typo in commit message: s/confirming/conforming/ |
|
Text looks fine to me but would prefer reviews from @nodejs/streams to mine. |
Trott
changed the title
doc/api/stream.md
Outdated
| @@ -1667,6 +1667,12 @@ of a stream that are intended for use by consumers (as described in the | |||
| [API for Stream Consumers][] section). Doing so may lead to adverse side effects | |||
| in application code consuming the stream. | |||
|
|
|||
| It is highly discouraged to override any public method or to emit | |||
| `'error'` events manually through `.emit(err)` instead of using API-provided | |||
There was a problem hiding this comment.
We also do not have "internal" events, so it's even more difficult to prevent any such usage.
I think that @BridgeAR was referring to events like 'data', 'finish', 'end', 'close', etc. not only 'error'.
There was a problem hiding this comment.
I see. Not sure what to do with that though? Should I add "internal events" to the paragraph?
ronag
force-pushed
the
notes-about-override
branch
from
a963259
to
e2207eb
Compare
ronag
force-pushed
the
notes-about-override
branch
from
3c45c5a
to
1ac15d1
Compare
|
Maybe a quick review from @mcollina? |
Trott
added
the
author ready
addaleax
removed
the
author ready
Co-Authored-By: Ruben Bridgewater <[email protected]>
|
@Trott: I believe this can land? |
|
Maybe @lundibundi & @yorkie has some last minute feedback? |
ronag
force-pushed
the
notes-about-override
branch
from
9a3f364
to
fdba619
Compare
|
I left a bunch of small suggestions, but none of them are blocking. Lite CI: https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/4087/ |
Trott
added
the
author ready
Co-Authored-By: Rich Trott <[email protected]>
PR-URL: #29895 Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: David Carlier <[email protected]> Reviewed-By: Denys Otrishko <[email protected]> Reviewed-By: Yorkie Liu <[email protected]> Reviewed-By: Rich Trott <[email protected]>
|
Landed in d67c377 |
PR-URL: #29895 Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: David Carlier <[email protected]> Reviewed-By: Denys Otrishko <[email protected]> Reviewed-By: Yorkie Liu <[email protected]> Reviewed-By: Rich Trott <[email protected]>
PR-URL: #29895 Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: David Carlier <[email protected]> Reviewed-By: Denys Otrishko <[email protected]> Reviewed-By: Yorkie Liu <[email protected]> Reviewed-By: Rich Trott <[email protected]>
PR-URL: #29895 Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: David Carlier <[email protected]> Reviewed-By: Denys Otrishko <[email protected]> Reviewed-By: Yorkie Liu <[email protected]> Reviewed-By: Rich Trott <[email protected]>
A lot of streams in the ecosystem are overriding public stream methods that lead to very subtle and hard to find bugs. Discourage this usage and encourage using the existing framework.
Checklist
make -j4 test(UNIX), orvcbuild test(Windows) passes