Repository navigation
[stream] Make _readableState and _writableState part of the public API #7629
Description
Following up from #7077 (comment), and other discussion.
One of the problem that has lead to breaking userland stream modules is related to the fact that they rely on functionality available in _readableState and _writableState that is not documented, and that is the only possible way for solving some issues, like knowing if a stream is in objectMode: true, clearing up the leftover write callbacks, and many other functionalities.
I propose we document, standardize and test a piece of _readableState and _writableState.
I think we should have been able to spot mafintosh/duplexify#6 before releasing, sigh. @calvinmetcalf @thealphanerd are we setting readable-stream in passthrough mode for citgm run?
I am opening this discussion here rather than in readable-stream because I would like all possible feedback. As @mikeal said, "So, what are we gonna do about streams?" openjs-foundation/summit#16 (comment).
@nodejs/streams we might want probably put this at in our next meeting.
Activity
[-]Make _readableStream and _writableStream part of the public API[/-][+][stream] Make _readableStream and _writableStream part of the public API[/+]vsemozhetbyt commentedon Jul 9, 2016
Are the '_readableStream' and '_writableStream' typos in the title?
[-][stream] Make _readableStream and _writableStream part of the public API[/-][+][stream] Make _readableState and _writableState part of the public API[/+]mcollina commentedon Jul 9, 2016
@vsemozhetbyt good catch!
mscdex commentedon Jul 9, 2016
Related: #6799
mscdex commentedon Jul 9, 2016
I personally think that having a single, non-underscore-prefixed property (to minimize impact) to house all state would be ideal (e.g.
stream.streamStatewithstream.streamState._readable, etc. as necessary).mafintosh commentedon Jul 9, 2016
Adding any properties by now will just make things more complicated in userland though as you'd have yet another thing to test for.
I'm 👍 on just making _readableState and _writableState part of the public readonly api - this is how they are used right now anyway.
mscdex commentedon Jul 9, 2016
Well technically it'd be trading two existing properties for one ;-)
I just don't like setting a precedent by documenting an underscore-prefixed property. It's already bad enough that
_readableStateis already publicly "documented" and its use is being encouraged....mcollina commentedon Jul 9, 2016
@mscdex Technically a single property is not correct, as you can have a
Transformthat is inobjectModeonly on one side.vkurchatkin commentedon Jul 9, 2016
_readableStateand_writableStateshould remain private. If some functionality is missing, it should be added to stream instances insteadmafintosh commentedon Jul 9, 2016
adding the properties directly on the stream instances will likely break some modules as inheritance from streams is encouraged. it'll also make it complicated for module authors to determine if a property was set by the stream impl or the userland subclass as you dont know which version of streams an instance was created with
vkurchatkin commentedon Jul 9, 2016
We have 2 options:
mcollina commentedon Jul 9, 2016
I'm not convinced on new properties, because it won't have an impact short-term. There are modules/applications that depends on these properties, because there aren't ways of solving certain issues using public APIs in a backward-compatible way.
vkurchatkin commentedon Jul 9, 2016
Documenting properties, prefixed with underscore essentially destroys convention and will eventually lead to a situation where we have to document all private properties.
So, a that very least, we need to remove underscores.
mcollina commentedon Jul 11, 2016
@vkurchatkin I agree. However the problem is that modules uses the
_-prefixed properties in the wild. At this point in time, it's impossible for us to know what should we should semver about or not.So, this solution helps in the long-term but not in the short-term.
I'm also a solution I could be happy with. My point is that we need to something to avoid this issue.
lance commentedon Jul 11, 2016
Note this was also discussed here #6799
win,msi: change InstallScope to perMachine
Trott commentedon Jul 8, 2017
Although conversation appears stalled, this hasn't reached a conclusion one way or the other, has it?
mcollina commentedon Jul 8, 2017
There is no consensus on this one and all the relative issues. I can put to together a report for @nodejs/ctc, and we might want to pick a direction. I do not think we can reach consensus otherwise.
caub commentedon Nov 8, 2017
I don't understand the few people who thumbed down
also maybe just simpler getters
stream.readableStatewould return_readableStatemcollina commentedon Mar 17, 2018
This can be closed, we are pursuing #445 and adding accessors for the properties that needs access to
_readableStateand_writableState. Sorry for the long wait, this could have been closed earlier.