Stream pipe documentation is confusing

[jplaisted]

• Version: 10
• Platform: n/a
• Subsystem: stream

Newbie to using NodeJS + NodeJS streams and I find the documentation very confusing, especially around pipes. I get the idea of piping streams but the documentation on pipe says it is on Readable, accepts a Writable, and returns a Writable and then mentions that it is possible to chain calls to pipe (e.g. r.pipe(z).pipe(w);). However it makes zero mention of how this is possible in the document. pipe returns a Writable, yet according to the document Writable has no pipe method. So how can they be chained?

Fiddling around in node inspecting things I see that the stream package is a class that both Readable and Writable inherit from. Perhaps having the documentation actually show this hierarchy and have more "standard" class documentation would help?

Maybe this isn't shown because piping a Writable stream to another stream makes no sense. What are you piping? You can't read from it. Unless you actually can and the idea of a Writable stream is a lie and everything is a Duplex? Or does it just pass the data over that writable and on to the next stream? Maybe this just a general design issue with Node streams? Or maybe there's an undocumented requirement that in order to chain pipe the argument to pipe must be a Duplex? (Digging further that appears to be the case - Writable has a pipe method that throws when called because it is not readable).

Site note: The example in pipe pipes through a Gzip object. But the documentation for Gzip is non existent and makes no mention that is a stream of any kind except in the small examples at the top of the zlib page. It seems pretty important to me to know that it is not only a stream, but a Transform that zips the input stream and outputs the zipped data.

I'm not looking for help using streams or gzip or anything else. Just noting that as someone totally new the documentation is in need of improvement. Especially for something that is presumably very core to Node as streams. Basically clearer documentation around pipe and its requirements (chaining requires streams be Duplexs) and what classes are streams - specifically what kind of stream (like Gzip is a Transform). More generally I'd say the "classic" documentation of documenting classes, methods, and hierarchies is more useful than entirely example based documentation.

[mscdex]

As far as I can see, the only real error here is in the 'Returns' section for readable.pipe(). Instead of what is currently shown:

Returns: <stream.Writable> making it possible to set up chains of piped streams

it's probably meant to instead say:

Returns: destination, making it possible to set up chains of piped streams

since if you read further into the readable.pipe() description it notes (emphasis mine):

The readable.pipe() method returns a reference to the destination stream making it possible to set up chains of piped streams

[addaleax]

I think we should also at least link back from the zlib reference docs to stream.Transform.

[HarshithaKP]

Looks like this is fixed in #22354