streams documentation for writable.write(chunk) describes return value incorrectly

[binki]

The return value indicates whether the written chunk was buffered internally and the buffer has exceeded the highWaterMark configured when the stream was created. If false is returned, further attempts to write data to the stream should be paused until the 'drain' event is emitted.

This suggests that when writable.write(chunk) returns false, the passed chunk was not buffered. In reality, write() always unconditionally buffers the chunk regardless of what it returns. Its return value is only advisory.

I would suggest language like this

The return value is true if the internal buffer does not exceed highWaterMark configured when the stream was created after admitting chunk. If false is returned, further attempts to write data to the stream should be paused until the 'drain' event is emitted. However, the false return value is only advisory and the writable stream will unconditionally accept chunk even if it has not not been allowed to drain.

[binki]

I was thinking about how highWaterMark works and how I hope it should work today, and I realized that the text I suggested is wrong. I suggested this:

The return value is true if the internal buffer does not exceed highWaterMark

when, in reality, (and more sensibly with how streams should work):

The return value is true if the internal buffer is smaller than highWaterMark

The associated PR needs to be updated accordingly. I’m basing this on my reading of

node/lib/_stream_writable.js

Line 305 in 9b0f53d

var ret = state.length < state.highWaterMark;

and also this demo:

> require('through2')({highWaterMark: 1, objectMode: true, }, function (chunk, encoding, callback) {}).write({})
false
> require('through2')({highWaterMark: 2, objectMode: true, }, function (chunk, encoding, callback) {}).write({})
true