Skip to content

Commit

Permalink
process: add optional detail to process emitWarning
Browse files Browse the repository at this point in the history 
Adds a new method signature variant for process.emitWarning()
that accepts an options object. The options object may include
a new `detail` option that allows additional detail text to be
associated with the warning. By default, this additional text
will be printed to stderr along with the warning, and included
on the Warning Error object using the `.detail` property.

e.g.

```js
process.emitWarning('A message', {
  code: 'WARNING123',
  detail: 'This is additional detail'
});
// Emits:
// (node {pid}) [WARNING123] Warning: A message
// This is additional detail
```

PR-URL: #12725
Reviewed-By: Colin Ihrig <[email protected]>
  • Loading branch information
@jasnell
jasnell committed May 1, 2017
1 parent 23fc082 commit dd20e68
Show file tree
Hide file tree
Showing 3 changed files with 107 additions and 36 deletions.
56 changes: 51 additions & 5 deletions doc/api/process.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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!
```
Expand Down Expand Up @@ -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`
Expand Down
30 changes: 19 additions & 11 deletions lib/internal/process/warning.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -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)) {
Expand Down
57 changes: 37 additions & 20 deletions test/parallel/test-process-emitwarning.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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);
Expand Down

0 comments on commit dd20e68

Please sign in to comment.