fixup: address comments & add tests

doc/api/stream.md

@@ -1301,14 +1301,14 @@ added: v10.0.0
 
 * `stream` {Stream} A readable and/or writable stream.
 * `options` {Object}
-  * `error` {boolean} If set to `false` a call to emit('error', err) is not
-    treated finished. **Default**: `true`.
-  * `readable` {boolean} When set to `false` the callback will be called after
-    the stream ended but the stream might still be readable. **Default**:
-    `true`.
-  * `writable` {boolean} When set to `false` the callback will be called after
-    the stream ended but the stream might still be writable. **Default**:
-    `true`.
+  * `error` {boolean} If set to `false`, then a call to `emit('error', err)` is
+    not treated as finished. **Default**: `true`.
+  * `readable` {boolean} When set to `false`, the callback will be called when
+    the stream ends even though the stream might still be readable.
+    **Default**: `true`.
+  * `writable` {boolean} When set to `false`, the callback will be called when
+    the stream ends even though the stream might still be writable.
+    **Default**: `true`.
 * `callback` {Function} A callback function that takes an optional error
   argument.
 
@@ -2447,7 +2447,7 @@ contain multi-byte characters.
 [zlib]: zlib.html
 [hwm-gotcha]: #stream_highwatermark_discrepancy_after_calling_readable_setencoding
 [pipeline]: #stream_stream_pipeline_streams_callback
-[finished]: #stream_stream_finished_stream_callback
+[finished]: #stream_stream_finished_stream_options_callback
 [stream-_flush]: #stream_transform_flush_callback
 [stream-_read]: #stream_readable_read_size_1
 [stream-_transform]: #stream_transform_transform_chunk_encoding_callback

lib/internal/streams/end-of-stream.js

@@ -25,8 +25,7 @@ function eos(stream, opts, callback) {
   if (arguments.length === 2) {
     callback = opts;
     opts = {};
-  }
-  if (opts == null) {
+  } else if (opts == null) {
     opts = {};
   } else if (typeof opts !== 'object') {
     throw new ERR_INVALID_ARG_TYPE('opts', 'object', opts);

test/parallel/test-stream-finished.js

@@ -91,8 +91,8 @@ const { promisify } = require('util');
 {
   const rs = fs.createReadStream('file-does-not-exist');
 
-  finished(rs, common.mustCall((err) => {
-    assert.strictEqual(err.code, 'ENOENT');
+  finished(rs, common.expectsError({
+    code: 'ENOENT'
   }));
 }
 
@@ -119,3 +119,37 @@ const { promisify } = require('util');
   rs.push(null);
   rs.resume();
 }
+
+// Test faulty input values and options.
+{
+  const rs = new Readable({
+    read() {}
+  });
+
+  assert.throws(
+    () => finished(rs, 'foo'),
+    {
+      name: /ERR_INVALID_ARG_TYPE/,
+      message: /callback/
+    }
+  );
+  assert.throws(
+    () => finished(rs, 'foo', () => {}),
+    {
+      name: /ERR_INVALID_ARG_TYPE/,
+      message: /opts/
+    }
+  );
+  assert.throws(
+    () => finished(rs, {}, 'foo'),
+    {
+      name: /ERR_INVALID_ARG_TYPE/,
+      message: /callback/
+    }
+  );
+
+  finished(rs, null, common.mustCall());
+
+  rs.push(null);
+  rs.resume();
+}