lib: improve error handling in Buffer.concat

- Replace ERR_INVALID_ARG_TYPE with ERR_INVALID_CONTAINER_ELEMENT_TYPE
  for clarity in error messages
- Update test-buffer-concat.js with new error code and message format
- Add new error ERR_INVALID_CONTAINER_ELEMENT_TYPE
  in lib/internal/errors.js
- Add document for ERR_INVALID_CONTAINER_ELEMENT_TYPE
  in doc/api/errors.md

Author: SeokhunEom

doc/api/errors.md

@@ -1930,6 +1930,12 @@ operation.
 
 Invalid characters were detected in headers.
 
+<a id="ERR_INVALID_CONTAINER_ELEMENT_TYPE"></a>
+
+### `ERR_INVALID_CONTAINER_ELEMENT_TYPE`
+
+A container element (e.g. array, set, map, etc.) of the wrong type was passed to a Node.js API.
+
 <a id="ERR_INVALID_CURSOR_POS"></a>
 
 ### `ERR_INVALID_CURSOR_POS`

lib/buffer.js

@@ -105,6 +105,7 @@ const {
     ERR_INVALID_ARG_TYPE,
     ERR_INVALID_ARG_VALUE,
     ERR_INVALID_BUFFER_SIZE,
+    ERR_INVALID_CONTAINER_ELEMENT_TYPE,
     ERR_MISSING_ARGS,
     ERR_OUT_OF_RANGE,
     ERR_UNKNOWN_ENCODING,
@@ -595,10 +596,8 @@ Buffer.concat = function concat(list, length) {
   for (let i = 0; i < list.length; i++) {
     const buf = list[i];
     if (!isUint8Array(buf)) {
-      // TODO(BridgeAR): This should not be of type ERR_INVALID_ARG_TYPE.
-      // Instead, find the proper error code for this.
-      throw new ERR_INVALID_ARG_TYPE(
-        `list[${i}]`, ['Buffer', 'Uint8Array'], list[i]);
+      throw new ERR_INVALID_CONTAINER_ELEMENT_TYPE(
+        'list', i, ['Buffer', 'Uint8Array'], list[i]);
     }
     pos += _copyActual(buf, buffer, pos, 0, buf.length);
   }

lib/internal/errors.js

@@ -1480,6 +1480,90 @@ E('ERR_INVALID_CHAR',
     if (field !== undefined) {
       msg += ` ["${field}"]`;
     }
+    return msg;
+  }, TypeError, HideStackFramesError);
+E('ERR_INVALID_CONTAINER_ELEMENT_TYPE',
+  (containerName, key, expected, actual) => {
+    assert(typeof containerName === 'string', "'containerName' must be a string");
+    assert(typeof key === 'string' || typeof key === 'number' || typeof key === 'symbol',
+           "'key' must be a string, number, or symbol");
+    if (!ArrayIsArray(expected)) {
+      expected = [expected];
+    }
+
+    let elementRef;
+    if (typeof key === 'number') {
+      elementRef = `"${containerName}[${key}]"`;
+    } else if (typeof key === 'string') {
+      elementRef = `"${containerName}" element "${key}"`;
+    } else {
+      // Handle symbol keys
+      const symbolDesc = key.description;
+      const symbolStr = String(key);
+      if (symbolDesc !== undefined) {
+        elementRef = `"${containerName}" element "${symbolDesc}"`;
+      } else if (symbolStr === 'Symbol()') {
+        elementRef = `"${containerName}" element`;
+      } else {
+        const match = symbolStr.match(/^Symbol\((.+)\)$/);
+        elementRef = `"${containerName}" element "${match ? match[1] : symbolStr}"`;
+      }
+    }
+
+    let msg = `The ${elementRef} must be `;
+
+    const types = [];
+    const instances = [];
+    const other = [];
+
+    for (const value of expected) {
+      assert(typeof value === 'string',
+             'All expected entries have to be of type string');
+      if (ArrayPrototypeIncludes(kTypes, value)) {
+        ArrayPrototypePush(types, StringPrototypeToLowerCase(value));
+      } else if (RegExpPrototypeExec(classRegExp, value) !== null) {
+        ArrayPrototypePush(instances, value);
+      } else {
+        assert(value !== 'object',
+               'The value "object" should be written as "Object"');
+        ArrayPrototypePush(other, value);
+      }
+    }
+
+    // Special handle `object` in case other instances are allowed to outline
+    // the differences between each other.
+    if (instances.length > 0) {
+      const pos = ArrayPrototypeIndexOf(types, 'object');
+      if (pos !== -1) {
+        ArrayPrototypeSplice(types, pos, 1);
+        ArrayPrototypePush(instances, 'Object');
+      }
+    }
+
+    if (types.length > 0) {
+      msg += `${types.length > 1 ? 'one of type' : 'of type'} ${formatList(types, 'or')}`;
+      if (instances.length > 0 || other.length > 0)
+        msg += ' or ';
+    }
+
+    if (instances.length > 0) {
+      msg += `an instance of ${formatList(instances, 'or')}`;
+      if (other.length > 0)
+        msg += ' or ';
+    }
+
+    if (other.length > 0) {
+      if (other.length > 1) {
+        msg += `one of ${formatList(other, 'or')}`;
+      } else {
+        if (StringPrototypeToLowerCase(other[0]) !== other[0])
+          msg += 'an ';
+        msg += `${other[0]}`;
+      }
+    }
+
+    msg += `. Received ${determineSpecificType(actual)}`;
+
     return msg;
   }, TypeError, HideStackFramesError);
 E('ERR_INVALID_CURSOR_POS',

test/parallel/test-buffer-concat.js

@@ -58,17 +58,17 @@ assert.strictEqual(flatLongLen.toString(), check);
   assert.throws(() => {
     Buffer.concat(value);
   }, {
-    code: 'ERR_INVALID_ARG_TYPE',
-    message: 'The "list[0]" argument must be an instance of Buffer ' +
+    code: 'ERR_INVALID_CONTAINER_ELEMENT_TYPE',
+    message: 'The "list[0]" must be an instance of Buffer ' +
              `or Uint8Array.${common.invalidArgTypeHelper(value[0])}`
   });
 });
 
 assert.throws(() => {
   Buffer.concat([Buffer.from('hello'), 3]);
 }, {
-  code: 'ERR_INVALID_ARG_TYPE',
-  message: 'The "list[1]" argument must be an instance of Buffer ' +
+  code: 'ERR_INVALID_CONTAINER_ELEMENT_TYPE',
+  message: 'The "list[1]" must be an instance of Buffer ' +
            'or Uint8Array. Received type number (3)'
 });