lib: require a callback for end-of-stream

Make the callback mandatory as mostly done in all other Node.js
callback APIs so users explicitly have to decide what to do in error
cases.

This also documents the options for `Stream.finished()`.

When originally implemented it was missed that Stream.finished() has
an optional options object.

PR-URL: https://github.com/nodejs/node/pull/21058
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Mathias Buus <mathiasbuus@gmail.com>

1 files changed, 36 insertions, 2 deletions

diff --git a/test/parallel/test-stream-finished.js b/test/parallel/test-stream-finished.js
index 3aade5610c..2d7eefc494 100644
--- a/test/parallel/test-stream-finished.js
+++ b/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();
+}