process: add optional detail to process emitWarning

doc/api/process.md

@@ -637,6 +637,52 @@ process's [`ChildProcess.disconnect()`][].
 If the Node.js process was not spawned with an IPC channel,
 `process.disconnect()` will be `undefined`.
 
+## process.emitWarning(warning[, options])
+<!-- YAML
+added: REPLACEME
+-->
+
+* `warning` {string|Error} The warning to emit.
+* `options` {Object}
+  * `type` {string} When `warning` is a String, `type` is the name to use
+    for the *type* of warning being emitted. Default: `Warning`.
+  * `code` {string} A unique identifier for the warning instance being emitted.
+  * `ctor` {Function} When `warning` is a String, `ctor` is an optional
+    function used to limit the generated stack trace. Default
+    `process.emitWarning`
+  * `detail` {string} Additional text to include with the error.
+
+The `process.emitWarning()` method can be used to emit custom or application
+specific process warnings. These can be listened for by adding a handler to the
+[`process.on('warning')`][process_warning] event.
+
+```js
+// Emit a warning with a code and additional detail.
+process.emitWarning('Something happened!', {
+  code: 'MY_WARNING',
+  detail: 'This is some additional information'
+});
+// Emits:
+// (node:56338) [MY_WARNING] Warning: Something happened!
+// This is some additional information
+```
+
+In this example, an `Error` object is generated internally by
+`process.emitWarning()` and passed through to the
+[`process.on('warning')`][process_warning] event.
+
+```js
+process.on('warning', (warning) => {
+  console.warn(warning.name);    // 'Warning'
+  console.warn(warning.message); // 'Something happened!'
+  console.warn(warning.code);    // 'MY_WARNING'
+  console.warn(warning.stack);   // Stack trace
+  console.warn(warning.detail);  // 'This is some additional information'
+});
+```
+
+If `warning` is passed as an `Error` object, the `options` argument is ignored.
+
 ## process.emitWarning(warning[, type[, code]][, ctor])
 <!-- YAML
 added: v6.0.0
@@ -655,13 +701,13 @@ specific process warnings. These can be listened for by adding a handler to the
 [`process.on('warning')`][process_warning] event.
 
 ```js
-// Emit a warning using a string...
+// Emit a warning using a string.
 process.emitWarning('Something happened!');
 // Emits: (node: 56338) Warning: Something happened!
 ```
 
 ```js
-// Emit a warning using a string and a type...
+// Emit a warning using a string and a type.
 process.emitWarning('Something Happened!', 'CustomWarning');
 // Emits: (node:56338) CustomWarning: Something Happened!
 ```
@@ -689,14 +735,14 @@ If `warning` is passed as an `Error` object, it will be passed through to the
 `code` and `ctor` arguments will be ignored):
 
 ```js
-// Emit a warning using an Error object...
-const myWarning = new Error('Warning! Something happened!');
+// Emit a warning using an Error object.
+const myWarning = new Error('Something happened!');
 // Use the Error name property to specify the type name
 myWarning.name = 'CustomWarning';
 myWarning.code = 'WARN001';
 
 process.emitWarning(myWarning);
-// Emits: (node:56338) [WARN001] CustomWarning: Warning! Something happened!
+// Emits: (node:56338) [WARN001] CustomWarning: Something happened!
 ```
 
 A `TypeError` is thrown if `warning` is anything other than a string or `Error`

lib/internal/process/warning.js

@@ -90,30 +90,37 @@ function setupProcessWarnings() {
       if (isDeprecation && process.noDeprecation) return;
       const trace = process.traceProcessWarnings ||
                     (isDeprecation && process.traceDeprecation);
+      let msg = `${prefix}`;
+      if (warning.code)
+        msg += `[${warning.code}] `;
       if (trace && warning.stack) {
-        if (warning.code) {
-          output(`${prefix}[${warning.code}] ${warning.stack}`);
-        } else {
-          output(`${prefix}${warning.stack}`);
-        }
+        msg += `${warning.stack}`;
       } else {
         const toString =
           typeof warning.toString === 'function' ?
             warning.toString : Error.prototype.toString;
-        if (warning.code) {
-          output(`${prefix}[${warning.code}] ${toString.apply(warning)}`);
-        } else {
-          output(`${prefix}${toString.apply(warning)}`);
-        }
+        msg += `${toString.apply(warning)}`;
       }
+      if (typeof warning.detail === 'string') {
+        msg += `\n${warning.detail}`;
+      }
+      output(msg);
     });
   }
 
   // process.emitWarning(error)
   // process.emitWarning(str[, type[, code]][, ctor])
+  // process.emitWarning(str[, options])
   process.emitWarning = function(warning, type, code, ctor) {
     const errors = lazyErrors();
-    if (typeof type === 'function') {
+    var detail;
+    if (type !== null && typeof type === 'object' && !Array.isArray(type)) {
+      ctor = type.ctor;
+      code = type.code;
+      if (typeof type.detail === 'string')
+        detail = type.detail;
+      type = type.type || 'Warning';
+    } else if (typeof type === 'function') {
       ctor = type;
       code = undefined;
       type = 'Warning';
@@ -130,6 +137,7 @@ function setupProcessWarnings() {
       warning = new Error(warning);
       warning.name = String(type || 'Warning');
       if (code !== undefined) warning.code = code;
+      if (detail !== undefined) warning.detail = detail;
       Error.captureStackTrace(warning, ctor || process.emitWarning);
     }
     if (!(warning instanceof Error)) {

test/parallel/test-process-emitwarning.js

@@ -4,30 +4,48 @@
 
 const common = require('../common');
 const assert = require('assert');
-const util = require('util');
+
+const testMsg = 'A Warning';
+const testCode = 'CODE001';
+const testDetail = 'Some detail';
+const testType = 'CustomWarning';
 
 process.on('warning', common.mustCall((warning) => {
   assert(warning);
   assert(/^(Warning|CustomWarning)/.test(warning.name));
-  assert.strictEqual(warning.message, 'A Warning');
-  if (warning.code) assert.strictEqual(warning.code, 'CODE001');
-}, 8));
-
-process.emitWarning('A Warning');
-process.emitWarning('A Warning', 'CustomWarning');
-process.emitWarning('A Warning', CustomWarning);
-process.emitWarning('A Warning', 'CustomWarning', CustomWarning);
-process.emitWarning('A Warning', 'CustomWarning', 'CODE001');
-
-function CustomWarning() {
-  Error.call(this);
-  this.name = 'CustomWarning';
-  this.message = 'A Warning';
-  this.code = 'CODE001';
-  Error.captureStackTrace(this, CustomWarning);
+  assert.strictEqual(warning.message, testMsg);
+  if (warning.code) assert.strictEqual(warning.code, testCode);
+  if (warning.detail) assert.strictEqual(warning.detail, testDetail);
+}, 15));
+
+class CustomWarning extends Error {
+  constructor() {
+    super();
+    this.name = testType;
+    this.message = testMsg;
+    this.code = testCode;
+    Error.captureStackTrace(this, CustomWarning);
+  }
 }
-util.inherits(CustomWarning, Error);
-process.emitWarning(new CustomWarning());
+
+[
+  [testMsg],
+  [testMsg, testType],
+  [testMsg, CustomWarning],
+  [testMsg, testType, CustomWarning],
+  [testMsg, testType, testCode],
+  [testMsg, { type: testType }],
+  [testMsg, { type: testType, code: testCode }],
+  [testMsg, { type: testType, code: testCode, detail: testDetail }],
+  [new CustomWarning()],
+  // detail will be ignored for the following. No errors thrown
+  [testMsg, { type: testType, code: testCode, detail: true }],
+  [testMsg, { type: testType, code: testCode, detail: [] }],
+  [testMsg, { type: testType, code: testCode, detail: null }],
+  [testMsg, { type: testType, code: testCode, detail: 1 }]
+].forEach((i) => {
+  assert.doesNotThrow(() => process.emitWarning.apply(null, i));
+});
 
 const warningNoToString = new CustomWarning();
 warningNoToString.toString = null;
@@ -47,7 +65,6 @@ assert.throws(() => process.emitWarning(1), expectedError);
 assert.throws(() => process.emitWarning({}), expectedError);
 assert.throws(() => process.emitWarning(true), expectedError);
 assert.throws(() => process.emitWarning([]), expectedError);
-assert.throws(() => process.emitWarning('', {}), expectedError);
 assert.throws(() => process.emitWarning('', '', {}), expectedError);
 assert.throws(() => process.emitWarning('', 1), expectedError);
 assert.throws(() => process.emitWarning('', '', 1), expectedError);