Close #1303 Stream.pipe returns the destination

Squashed:

* Simple change to make Stream.pipe(destination) return the destination Stream
* Test: ensure Stream.pipe(destination) returns the destination Stream
* updated Stream.pipe() documentation to reflect that it now returns the
  destination stream

diff --git a/doc/api/streams.markdown b/doc/api/streams.markdown
index 2bc05f3..01a841a 100644 (file)
--- a/doc/api/streams.markdown
+++ b/doc/api/streams.markdown
@@ -78,6 +78,8 @@ Connects this read stream to `destination` WriteStream. Incoming
 data on this stream gets written to `destination`. The destination and source
 streams are kept in sync by pausing and resuming as necessary.
 
+This function returns the `destination` stream.
+
 Emulating the Unix `cat` command:
 
     process.stdin.resume();

diff --git a/lib/stream.js b/lib/stream.js
index 1ad08ec..2869e82 100644 (file)
--- a/lib/stream.js
+++ b/lib/stream.js
@@ -157,4 +157,7 @@ Stream.prototype.pipe = function(dest, options) {
   dest.on('close', cleanup);
 
   dest.emit('pipe', source);
+
+  // Allow for unix-like usage: A.pipe(B).pipe(C)
+  return dest;
 };

diff --git a/test/simple/test-pipe-return-val.js b/test/simple/test-pipe-return-val.js
new file mode 100644 (file)
index 0000000..f82b26e
--- /dev/null
+++ b/test/simple/test-pipe-return-val.js
@@ -0,0 +1,33 @@
+// Copyright Joyent, Inc. and other Node contributors.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the
+// "Software"), to deal in the Software without restriction, including
+// without limitation the rights to use, copy, modify, merge, publish,
+// distribute, sublicense, and/or sell copies of the Software, and to permit
+// persons to whom the Software is furnished to do so, subject to the
+// following conditions:
+//
+// The above copyright notice and this permission notice shall be included
+// in all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+// USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+// This test ensures SourceStream.pipe(DestStream) returns DestStream
+
+var Stream = require('stream').Stream;
+var assert = require('assert');
+var util = require('util');
+
+var sourceStream = new Stream();
+var destStream = new Stream();
+var result = sourceStream.pipe(destStream);
+
+assert.strictEqual(result, destStream);
+