stream: add comments to pipeline implementation

Fixes: #32039

PR-URL: #32042
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: James M Snell <[email protected]>

Author: ronag

lib/internal/streams/pipeline.js

@@ -219,6 +219,11 @@ function pipeline(...streams) {
           PassThrough = require('_stream_passthrough');
         }
 
+        // If the last argument to pipeline is not a stream
+        // we must create a proxy stream so that pipeline(...)
+        // always returns a stream which can be further
+        // composed through `.pipe(stream)`.
+
         const pt = new PassThrough();
         if (isPromise(ret)) {
           ret
@@ -253,6 +258,9 @@ function pipeline(...streams) {
     }
   }
 
+  // TODO(ronag): Consider returning a Duplex proxy if the first argument
+  // is a writable. Would improve composability.
+  // See, https://github.com/nodejs/node/issues/32020
   return ret;
 }