errors: convert 'fs'

covert lib/fs.js over to using lib/internal/errors.js
i have not addressed the cases that use errnoException(),
for reasons described in GH-12926

- throw the ERR_INVALID_CALLBACK error
  when the the callback is invalid
- replace the ['object', 'string'] with
  ['string', 'object'] in the error constructor call,
  to better match the previous err msg
  in the getOptions() function
- add error ERR_VALUE_OUT_OF_RANGE in lib/internal/errors.js,
  this error is thrown when a numeric value is out of range
- document the ERR_VALUE_OUT_OF_RANGE err in errors.md
- correct the expected args, in the error thrown in the function
  fs._toUnixTimestamp() to ['Date', 'time in seconds'] (lib/fs.js)
- update the listener error type in the fs.watchFile() function,
  from Error to TypeError (lib/fs.js)
- update errors from ERR_INVALID_OPT_VALUE to ERR_INVALID_ARG_TYPE
  in the functions fs.ReadStream() and fs.WriteStream(),
  for the cases of range errors use the new error:
  ERR_VALUE_OUT_OF_RANGE (lib/fs.js)

PR-URL: https://github.com/nodejs/node/pull/15043
Refs: https://github.com/nodejs/node/issues/11273
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

14 files changed, 183 insertions, 98 deletions

diff --git a/test/parallel/test-file-write-stream3.js b/test/parallel/test-file-write-stream3.js
index 83b1d7bf43..cdc01e8733 100644
--- a/test/parallel/test-file-write-stream3.js
+++ b/test/parallel/test-file-write-stream3.js
@@ -176,12 +176,15 @@ function run_test_3() {
 
 const run_test_4 = common.mustCall(function() {
   //  Error: start must be >= zero
-  assert.throws(
-    function() {
-      fs.createWriteStream(filepath, { start: -5, flags: 'r+' });
-    },
-    /"start" must be/
-  );
+  const block = () => {
+    fs.createWriteStream(filepath, { start: -5, flags: 'r+' });
+  };
+  const err = {
+    code: 'ERR_VALUE_OUT_OF_RANGE',
+    message: 'The value of "start" must be >= 0. Received "{start: -5}"',
+    type: RangeError
+  };
+  common.expectsError(block, err);
 });
 
 run_test_1();
diff --git a/test/parallel/test-fs-access.js b/test/parallel/test-fs-access.js
index f378824cbc..d3140941bd 100644
--- a/test/parallel/test-fs-access.js
+++ b/test/parallel/test-fs-access.js
@@ -85,13 +85,23 @@ assert.throws(() => {
   fs.access(100, fs.F_OK, common.mustNotCall());
 }, /^TypeError: path must be a string or Buffer$/);
 
-assert.throws(() => {
-  fs.access(__filename, fs.F_OK);
-}, /^TypeError: "callback" argument must be a function$/);
-
-assert.throws(() => {
-  fs.access(__filename, fs.F_OK, {});
-}, /^TypeError: "callback" argument must be a function$/);
+common.expectsError(
+  () => {
+    fs.access(__filename, fs.F_OK);
+  },
+  {
+    code: 'ERR_INVALID_CALLBACK',
+    type: TypeError
+  });
+
+common.expectsError(
+  () => {
+    fs.access(__filename, fs.F_OK, {});
+  },
+  {
+    code: 'ERR_INVALID_CALLBACK',
+    type: TypeError
+  });
 
 assert.doesNotThrow(() => {
   fs.accessSync(__filename);
diff --git a/test/parallel/test-fs-make-callback.js b/test/parallel/test-fs-make-callback.js
index 8a19e1cc96..79cf4e0bed 100644
--- a/test/parallel/test-fs-make-callback.js
+++ b/test/parallel/test-fs-make-callback.js
@@ -2,7 +2,6 @@
 const common = require('../common');
 const assert = require('assert');
 const fs = require('fs');
-const cbTypeError = /^TypeError: "callback" argument must be a function$/;
 const callbackThrowValues = [null, true, false, 0, 1, 'foo', /foo/, [], {}];
 
 const { sep } = require('path');
@@ -24,7 +23,10 @@ assert.doesNotThrow(testMakeCallback());
 
 function invalidCallbackThrowsTests() {
   callbackThrowValues.forEach((value) => {
-    assert.throws(testMakeCallback(value), cbTypeError);
+    common.expectsError(testMakeCallback(value), {
+      code: 'ERR_INVALID_CALLBACK',
+      type: TypeError
+    });
   });
 }
 
diff --git a/test/parallel/test-fs-makeStatsCallback.js b/test/parallel/test-fs-makeStatsCallback.js
index 12120e9737..0982fcc3c7 100644
--- a/test/parallel/test-fs-makeStatsCallback.js
+++ b/test/parallel/test-fs-makeStatsCallback.js
@@ -2,7 +2,6 @@
 const common = require('../common');
 const assert = require('assert');
 const fs = require('fs');
-const cbTypeError = /^TypeError: "callback" argument must be a function$/;
 const callbackThrowValues = [null, true, false, 0, 1, 'foo', /foo/, [], {}];
 const warn = 'Calling an asynchronous function without callback is deprecated.';
 
@@ -23,7 +22,10 @@ assert.doesNotThrow(testMakeStatsCallback());
 
 function invalidCallbackThrowsTests() {
   callbackThrowValues.forEach((value) => {
-    assert.throws(testMakeStatsCallback(value), cbTypeError);
+    common.expectsError(testMakeStatsCallback(value), {
+      code: 'ERR_INVALID_CALLBACK',
+      type: TypeError
+    });
   });
 }
 
diff --git a/test/parallel/test-fs-mkdtemp-prefix-check.js b/test/parallel/test-fs-mkdtemp-prefix-check.js
index 786d0fe7ba..4573dbbaae 100644
--- a/test/parallel/test-fs-mkdtemp-prefix-check.js
+++ b/test/parallel/test-fs-mkdtemp-prefix-check.js
@@ -1,22 +1,29 @@
 'use strict';
 const common = require('../common');
-const assert = require('assert');
 const fs = require('fs');
 
-const expectedError = /^TypeError: filename prefix is required$/;
 const prefixValues = [undefined, null, 0, true, false, 1, ''];
 
 function fail(value) {
-  assert.throws(
-    () => fs.mkdtempSync(value, {}),
-    expectedError
-  );
+  common.expectsError(
+    () => {
+      fs.mkdtempSync(value, {});
+    },
+    {
+      code: 'ERR_INVALID_ARG_TYPE',
+      type: TypeError
+    });
 }
 
 function failAsync(value) {
-  assert.throws(
-    () => fs.mkdtemp(value, common.mustNotCall()), expectedError
-  );
+  common.expectsError(
+    () => {
+      fs.mkdtemp(value, common.mustNotCall());
+    },
+    {
+      code: 'ERR_INVALID_ARG_TYPE',
+      type: TypeError
+    });
 }
 
 prefixValues.forEach((prefixValue) => {
diff --git a/test/parallel/test-fs-non-number-arguments-throw.js b/test/parallel/test-fs-non-number-arguments-throw.js
index 5e4deb12a8..9e73502c29 100644
--- a/test/parallel/test-fs-non-number-arguments-throw.js
+++ b/test/parallel/test-fs-non-number-arguments-throw.js
@@ -13,20 +13,32 @@ fs.writeFileSync(tempFile, 'abc\ndef');
 const sanity = 'def';
 const saneEmitter = fs.createReadStream(tempFile, { start: 4, end: 6 });
 
-assert.throws(function() {
-  fs.createReadStream(tempFile, { start: '4', end: 6 });
-}, /^TypeError: "start" option must be a Number$/,
-              "start as string didn't throw an error for createReadStream");
+common.expectsError(
+  () => {
+    fs.createReadStream(tempFile, { start: '4', end: 6 });
+  },
+  {
+    code: 'ERR_INVALID_ARG_TYPE',
+    type: TypeError
+  });
 
-assert.throws(function() {
-  fs.createReadStream(tempFile, { start: 4, end: '6' });
-}, /^TypeError: "end" option must be a Number$/,
-              "end as string didn't throw an error for createReadStream");
+common.expectsError(
+  () => {
+    fs.createReadStream(tempFile, { start: 4, end: '6' });
+  },
+  {
+    code: 'ERR_INVALID_ARG_TYPE',
+    type: TypeError
+  });
 
-assert.throws(function() {
-  fs.createWriteStream(tempFile, { start: '4' });
-}, /^TypeError: "start" option must be a Number$/,
-              "start as string didn't throw an error for createWriteStream");
+common.expectsError(
+  () => {
+    fs.createWriteStream(tempFile, { start: '4' });
+  },
+  {
+    code: 'ERR_INVALID_ARG_TYPE',
+    type: TypeError
+  });
 
 saneEmitter.on('data', common.mustCall(function(data) {
   assert.strictEqual(
diff --git a/test/parallel/test-fs-null-bytes.js b/test/parallel/test-fs-null-bytes.js
index 0552801b2d..44defc782e 100644
--- a/test/parallel/test-fs-null-bytes.js
+++ b/test/parallel/test-fs-null-bytes.js
@@ -26,17 +26,27 @@ const fs = require('fs');
 const URL = require('url').URL;
 
 function check(async, sync) {
-  const expected = /Path must be a string without null bytes/;
   const argsSync = Array.prototype.slice.call(arguments, 2);
   const argsAsync = argsSync.concat((er) => {
-    assert(er && expected.test(er.message));
-    assert.strictEqual(er.code, 'ENOENT');
+    common.expectsError(
+      () => {
+        throw er;
+      },
+      {
+        code: 'ERR_INVALID_ARG_TYPE',
+        type: Error
+      });
   });
 
   if (sync) {
-    assert.throws(() => {
-      sync.apply(null, argsSync);
-    }, expected);
+    common.expectsError(
+      () => {
+        sync.apply(null, argsSync);
+      },
+      {
+        code: 'ERR_INVALID_ARG_TYPE',
+        type: Error,
+      });
   }
 
   if (async) {
diff --git a/test/parallel/test-fs-read-stream-inherit.js b/test/parallel/test-fs-read-stream-inherit.js
index ddb07274d1..1a7fc7b5bb 100644
--- a/test/parallel/test-fs-read-stream-inherit.js
+++ b/test/parallel/test-fs-read-stream-inherit.js
@@ -108,9 +108,18 @@ const rangeFile = path.join(common.fixturesDir, 'x.txt');
 }
 
 {
-  assert.throws(function() {
-    fs.createReadStream(rangeFile, Object.create({ start: 10, end: 2 }));
-  }, /"start" option must be <= "end" option/);
+  const message =
+    'The value of "start" must be <= "end". Received "{start: 10, end: 2}"';
+
+  common.expectsError(
+    () => {
+      fs.createReadStream(rangeFile, Object.create({ start: 10, end: 2 }));
+    },
+    {
+      code: 'ERR_VALUE_OUT_OF_RANGE',
+      message,
+      type: RangeError
+    });
 }
 
 {
diff --git a/test/parallel/test-fs-read-stream-throw-type-error.js b/test/parallel/test-fs-read-stream-throw-type-error.js
index b6e1869fdc..61308ea97b 100644
--- a/test/parallel/test-fs-read-stream-throw-type-error.js
+++ b/test/parallel/test-fs-read-stream-throw-type-error.js
@@ -19,16 +19,18 @@ assert.doesNotThrow(function() {
   fs.createReadStream(example, { encoding: 'utf8' });
 });
 
-const errMessage = /"options" must be a string or an object/;
-assert.throws(function() {
-  fs.createReadStream(example, 123);
-}, errMessage);
-assert.throws(function() {
-  fs.createReadStream(example, 0);
-}, errMessage);
-assert.throws(function() {
-  fs.createReadStream(example, true);
-}, errMessage);
-assert.throws(function() {
-  fs.createReadStream(example, false);
-}, errMessage);
+const createReadStreamErr = (path, opt) => {
+  common.expectsError(
+    () => {
+      fs.createReadStream(path, opt);
+    },
+    {
+      code: 'ERR_INVALID_ARG_TYPE',
+      type: TypeError
+    });
+};
+
+createReadStreamErr(example, 123);
+createReadStreamErr(example, 0);
+createReadStreamErr(example, true);
+createReadStreamErr(example, false);
diff --git a/test/parallel/test-fs-read-stream.js b/test/parallel/test-fs-read-stream.js
index 04c10b5a44..ecc00edc85 100644
--- a/test/parallel/test-fs-read-stream.js
+++ b/test/parallel/test-fs-read-stream.js
@@ -140,9 +140,16 @@ const rangeFile = fixtures.path('x.txt');
   }));
 }
 
-assert.throws(function() {
-  fs.createReadStream(rangeFile, { start: 10, end: 2 });
-}, /"start" option must be <= "end" option/);
+common.expectsError(
+  () => {
+    fs.createReadStream(rangeFile, { start: 10, end: 2 });
+  },
+  {
+    code: 'ERR_VALUE_OUT_OF_RANGE',
+    message:
+      'The value of "start" must be <= "end". Received "{start: 10, end: 2}"',
+    type: RangeError
+  });
 
 {
   const stream = fs.createReadStream(rangeFile, { start: 0, end: 0 });
diff --git a/test/parallel/test-fs-timestamp-parsing-error.js b/test/parallel/test-fs-timestamp-parsing-error.js
index c37cf674a4..3680b5fece 100644
--- a/test/parallel/test-fs-timestamp-parsing-error.js
+++ b/test/parallel/test-fs-timestamp-parsing-error.js
@@ -1,15 +1,27 @@
 'use strict';
-require('../common');
+const common = require('../common');
 const fs = require('fs');
 const assert = require('assert');
 
 [Infinity, -Infinity, NaN].forEach((input) => {
-  assert.throws(() => fs._toUnixTimestamp(input),
-                new RegExp(`^Error: Cannot parse time: ${input}$`));
+  common.expectsError(
+    () => {
+      fs._toUnixTimestamp(input);
+    },
+    {
+      code: 'ERR_INVALID_ARG_TYPE',
+      type: Error
+    });
 });
 
-assert.throws(() => fs._toUnixTimestamp({}),
-              /^Error: Cannot parse time: \[object Object\]$/);
+common.expectsError(
+  () => {
+    fs._toUnixTimestamp({});
+  },
+  {
+    code: 'ERR_INVALID_ARG_TYPE',
+    type: Error
+  });
 
 const okInputs = [1, -1, '1', '-1', Date.now()];
 okInputs.forEach((input) => {
diff --git a/test/parallel/test-fs-watchfile.js b/test/parallel/test-fs-watchfile.js
index 43e2594463..f980d8f3fc 100644
--- a/test/parallel/test-fs-watchfile.js
+++ b/test/parallel/test-fs-watchfile.js
@@ -6,13 +6,23 @@ const fs = require('fs');
 const path = require('path');
 
 // Basic usage tests.
-assert.throws(function() {
-  fs.watchFile('./some-file');
-}, /^Error: "watchFile\(\)" requires a listener function$/);
+common.expectsError(
+  () => {
+    fs.watchFile('./some-file');
+  },
+  {
+    code: 'ERR_INVALID_ARG_TYPE',
+    type: TypeError
+  });
 
-assert.throws(function() {
-  fs.watchFile('./another-file', {}, 'bad listener');
-}, /^Error: "watchFile\(\)" requires a listener function$/);
+common.expectsError(
+  () => {
+    fs.watchFile('./another-file', {}, 'bad listener');
+  },
+  {
+    code: 'ERR_INVALID_ARG_TYPE',
+    type: TypeError
+  });
 
 assert.throws(function() {
   fs.watchFile(new Object(), common.mustNotCall());
diff --git a/test/parallel/test-fs-whatwg-url.js b/test/parallel/test-fs-whatwg-url.js
index c80fb5ca9e..b9aaee9c30 100644
--- a/test/parallel/test-fs-whatwg-url.js
+++ b/test/parallel/test-fs-whatwg-url.js
@@ -36,9 +36,14 @@ fs.readFile(httpUrl, common.expectsError({
 
 // pct-encoded characters in the path will be decoded and checked
 fs.readFile(new URL('file:///c:/tmp/%00test'), common.mustCall((err) => {
-  assert(err);
-  assert.strictEqual(err.message,
-                     'Path must be a string without null bytes');
+  common.expectsError(
+    () => {
+      throw err;
+    },
+    {
+      code: 'ERR_INVALID_ARG_TYPE',
+      type: Error
+    });
 }));
 
 if (common.isWindows) {
diff --git a/test/parallel/test-fs-write-stream-throw-type-error.js b/test/parallel/test-fs-write-stream-throw-type-error.js
index 5652e9e5e6..42538906a5 100644
--- a/test/parallel/test-fs-write-stream-throw-type-error.js
+++ b/test/parallel/test-fs-write-stream-throw-type-error.js
@@ -4,12 +4,6 @@ const assert = require('assert');
 const fs = require('fs');
 const path = require('path');
 
-const numberError =
-  /^TypeError: "options" must be a string or an object, got number instead\.$/;
-
-const booleanError =
-  /^TypeError: "options" must be a string or an object, got boolean instead\.$/;
-
 const example = path.join(common.tmpDir, 'dummy');
 
 common.refreshTmpDir();
@@ -30,18 +24,18 @@ assert.doesNotThrow(() => {
   fs.createWriteStream(example, { encoding: 'utf8' });
 });
 
-assert.throws(() => {
-  fs.createWriteStream(example, 123);
-}, numberError);
-
-assert.throws(() => {
-  fs.createWriteStream(example, 0);
-}, numberError);
-
-assert.throws(() => {
-  fs.createWriteStream(example, true);
-}, booleanError);
-
-assert.throws(() => {
-  fs.createWriteStream(example, false);
-}, booleanError);
+const createWriteStreamErr = (path, opt) => {
+  common.expectsError(
+    () => {
+      fs.createWriteStream(path, opt);
+    },
+    {
+      code: 'ERR_INVALID_ARG_TYPE',
+      type: TypeError
+    });
+};
+
+createWriteStreamErr(example, 123);
+createWriteStreamErr(example, 0);
+createWriteStreamErr(example, true);
+createWriteStreamErr(example, false);