util: add decorateErrorStack()

This commit adds the decorateErrorStack() method. This function
uses the internal util's getHiddenValue() method to extract
arrow messages from error objects and attach them to the
error's stack trace.

PR-URL: #4013
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>

Author: cjihrig

Diff for: lib/util.js

@@ -901,3 +901,14 @@ exports._exceptionWithHostPort = function(err,
   }
   return ex;
 };
+
+
+exports.decorateErrorStack = function(err) {
+  if (!(isError(err) && err.stack))
+    return;
+
+  const arrow = internalUtil.getHiddenValue(err, 'arrowMessage');
+
+  if (arrow)
+    err.stack = arrow + err.stack;
+};

Diff for: test/parallel/test-util-decorate-error-stack.js

@@ -0,0 +1,35 @@
+'use strict';
+const common = require('../common');
+const assert = require('assert');
+const util = require('util');
+
+assert.doesNotThrow(function() {
+  util.decorateErrorStack();
+  util.decorateErrorStack(null);
+  util.decorateErrorStack(1);
+  util.decorateErrorStack(true);
+});
+
+// Verify that a stack property is not added to non-Errors
+const obj = {};
+util.decorateErrorStack(obj);
+assert.strictEqual(obj.stack, undefined);
+
+// Verify that the stack is decorated when possible
+let err;
+
+try {
+  require('../fixtures/syntax/bad_syntax');
+} catch (e) {
+  err = e;
+  assert(!/var foo bar;/.test(err.stack));
+  util.decorateErrorStack(err);
+}
+
+assert(/var foo bar;/.test(err.stack));
+
+// Verify that the stack is unchanged when there is no arrow message
+err = new Error('foo');
+const originalStack = err.stack;
+util.decorateErrorStack(err);
+assert.strictEqual(originalStack, err.stack);