From 960be159ac3b21bf8a4f8c3bca7e733d483fb7d9 Mon Sep 17 00:00:00 2001
From: Robert Nagy <ronagy@icloud.com>
Date: Mon, 2 Mar 2020 12:44:42 +0100
Subject: [PATCH] stream: add comments to pipeline implementation

Fixes: https://github.com/nodejs/node/issues/32039

PR-URL: https://github.com/nodejs/node/pull/32042
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
---
 lib/internal/streams/pipeline.js | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/lib/internal/streams/pipeline.js b/lib/internal/streams/pipeline.js
index 46d499709ee45e..c1299a6db42a3d 100644
--- a/lib/internal/streams/pipeline.js
+++ b/lib/internal/streams/pipeline.js
@@ -202,6 +202,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
@@ -236,6 +241,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;
 }