From 55906f9077f1c957d9b3ee9de824c69483f59c2e Mon Sep 17 00:00:00 2001
From: Anna Henningsen <anna@addaleax.net>
Date: Fri, 19 Aug 2016 00:26:36 +0200
Subject: [PATCH 1/3] util: allow symbol-based custom inspection methods
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a `util.inspect.custom` Symbol which can be used to customize
`util.inspect()` output. Providing `obj[util.inspect.custom]`
works like providing `obj.inspect`, except that the former allows
avoiding name clashes with other `inspect()` methods.

Fixes: https://github.com/nodejs/node/issues/8071
PR-URL: https://github.com/nodejs/node/pull/8174
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michaël Zasso <mic.besace@gmail.com>
---
 doc/api/util.md                    | 45 ++++++++++++---
 lib/buffer.js                      |  5 +-
 lib/internal/util.js               |  4 ++
 lib/util.js                        | 29 ++++++----
 test/parallel/test-util-inspect.js | 91 +++++++++++++++++++++++++++---
 5 files changed, 142 insertions(+), 32 deletions(-)

diff --git a/doc/api/util.md b/doc/api/util.md
index 662c360359a307..4b056a96049135 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -234,18 +234,19 @@ Predefined color codes are: `white`, `grey`, `black`, `blue`, `cyan`,
 `green`, `magenta`, `red` and `yellow`.
 There are also `bold`, `italic`, `underline` and `inverse` codes.
 
-### Custom `inspect()` function on Objects
+### Custom inspection functions on Objects
 
 <!-- type=misc -->
 
-Objects also may define their own `inspect(depth)` function which `util.inspect()`
-will invoke and use the result of when inspecting the object:
+Objects may also define their own `[util.inspect.custom](depth, opts)`
+(or, equivalently `inspect(depth, opts)`) function that `util.inspect()` will
+invoke and use the result of when inspecting the object:
 
 ```js
 const util = require('util');
 
-var obj = { name: 'nate' };
-obj.inspect = function(depth) {
+const obj = { name: 'nate' };
+obj[util.inspect.custom] = function(depth) {
   return `{${this.name}}`;
 };
 
@@ -253,12 +254,29 @@ util.inspect(obj);
   // "{nate}"
 ```
 
-You may also return another Object entirely, and the returned String will be
-formatted according to the returned Object. This is similar to how
-`JSON.stringify()` works:
+Custom `[util.inspect.custom](depth, opts)` functions typically return a string
+but may return a value of any type that will be formatted accordingly by
+`util.inspect()`.
+
+```js
+const util = require('util');
+
+const obj = { foo: 'this will not show up in the inspect() output' };
+obj[util.inspect.custom] = function(depth) {
+  return { bar: 'baz' };
+};
+
+util.inspect(obj);
+  // "{ bar: 'baz' }"
+```
+
+A custom inspection method can alternatively be provided by exposing
+an `inspect(depth, opts)` method on the object:
 
 ```js
-var obj = { foo: 'this will not show up in the inspect() output' };
+const util = require('util');
+
+const obj = { foo: 'this will not show up in the inspect() output' };
 obj.inspect = function(depth) {
   return { bar: 'baz' };
 };
@@ -267,6 +285,14 @@ util.inspect(obj);
   // "{ bar: 'baz' }"
 ```
 
+### util.inspect.custom
+<!-- YAML
+added: REPLACEME
+-->
+
+A Symbol that can be used to declare custom inspect functions, see
+[Custom inspection functions on Objects][].
+
 ## util.isArray(object)
 <!-- YAML
 added: v0.6.0
@@ -656,6 +682,7 @@ Deprecated predecessor of `console.log`.
 [constructor]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/constructor
 [Customizing `util.inspect` colors]: #util_customizing_util_inspect_colors
 [here]: #util_customizing_util_inspect_colors
+[Custom inspection functions on Objects]: #util_custom_inspection_functions_on_objects
 [`Error`]: errors.html#errors_class_error
 [`console.log()`]: console.html#console_console_log_data
 [`console.error()`]: console.html#console_console_error_data
diff --git a/lib/buffer.js b/lib/buffer.js
index 7bad03939f5e5e..94306f72034f2f 100644
--- a/lib/buffer.js
+++ b/lib/buffer.js
@@ -469,8 +469,8 @@ Buffer.prototype.equals = function equals(b) {
 };
 
 
-// Inspect
-Buffer.prototype.inspect = function inspect() {
+// Override how buffers are presented by util.inspect().
+Buffer.prototype[internalUtil.inspectSymbol] = function inspect() {
   var str = '';
   var max = exports.INSPECT_MAX_BYTES;
   if (this.length > 0) {
@@ -480,6 +480,7 @@ Buffer.prototype.inspect = function inspect() {
   }
   return '<' + this.constructor.name + ' ' + str + '>';
 };
+Buffer.prototype.inspect = Buffer.prototype[internalUtil.inspectSymbol];
 
 
 Buffer.prototype.compare = function compare(b) {
diff --git a/lib/internal/util.js b/lib/internal/util.js
index c34682ed1b3809..ddb697410162db 100644
--- a/lib/internal/util.js
+++ b/lib/internal/util.js
@@ -5,6 +5,10 @@ const prefix = '(node) ';
 
 exports.getHiddenValue = binding.getHiddenValue;
 
+// The `buffer` module uses this. Defining it here instead of in the public
+// `util` module makes it accessible without having to `require('util')` there.
+exports.customInspectSymbol = Symbol('util.inspect.custom');
+
 // All the internal deprecations have to use this function only, as this will
 // prepend the prefix to the actual message.
 exports.deprecate = function(fn, msg) {
diff --git a/lib/util.js b/lib/util.js
index 8d9afe921f4292..d250edde6b9c3d 100644
--- a/lib/util.js
+++ b/lib/util.js
@@ -142,7 +142,6 @@ function inspect(obj, opts) {
   if (ctx.colors) ctx.stylize = stylizeWithColor;
   return formatValue(ctx, obj, ctx.depth);
 }
-exports.inspect = inspect;
 
 
 // http://en.wikipedia.org/wiki/ANSI_escape_code#graphics
@@ -176,6 +175,10 @@ inspect.styles = {
   'regexp': 'red'
 };
 
+const customInspectSymbol = internalUtil.customInspectSymbol;
+
+exports.inspect = inspect;
+exports.inspect.custom = customInspectSymbol;
 
 function stylizeWithColor(str, styleType) {
   var style = inspect.styles[styleType];
@@ -243,18 +246,20 @@ function inspectPromise(p) {
 function formatValue(ctx, value, recurseTimes) {
   // Provide a hook for user-specified inspect functions.
   // Check that value is an object with an inspect function on it
-  if (ctx.customInspect &&
-      value &&
-      typeof value.inspect === 'function' &&
-      // Filter out the util module, it's inspect function is special
-      value.inspect !== exports.inspect &&
-      // Also filter out any prototype objects using the circular check.
-      !(value.constructor && value.constructor.prototype === value)) {
-    var ret = value.inspect(recurseTimes, ctx);
-    if (typeof ret !== 'string') {
-      ret = formatValue(ctx, ret, recurseTimes);
+  if (ctx.customInspect && value) {
+    const maybeCustomInspect = value[customInspectSymbol] || value.inspect;
+
+    if (typeof maybeCustomInspect === 'function' &&
+        // Filter out the util module, its inspect function is special
+        maybeCustomInspect !== exports.inspect &&
+        // Also filter out any prototype objects using the circular check.
+        !(value.constructor && value.constructor.prototype === value)) {
+      let ret = maybeCustomInspect.call(value, recurseTimes, ctx);
+      if (typeof ret !== 'string') {
+        ret = formatValue(ctx, ret, recurseTimes);
+      }
+      return ret;
     }
-    return ret;
   }
 
   // Primitive types cannot have properties
diff --git a/test/parallel/test-util-inspect.js b/test/parallel/test-util-inspect.js
index 3c227d8a3fc407..eb0d128d5b26e7 100644
--- a/test/parallel/test-util-inspect.js
+++ b/test/parallel/test-util-inspect.js
@@ -279,19 +279,42 @@ assert.doesNotThrow(function() {
 
 // new API, accepts an "options" object
 {
-  let subject = { foo: 'bar', hello: 31, a: { b: { c: { d: 0 } } } };
+  const subject = { foo: 'bar', hello: 31, a: { b: { c: { d: 0 } } } };
   Object.defineProperty(subject, 'hidden', { enumerable: false, value: null });
 
-  assert(util.inspect(subject, { showHidden: false }).indexOf('hidden') === -1);
-  assert(util.inspect(subject, { showHidden: true }).indexOf('hidden') !== -1);
-  assert(util.inspect(subject, { colors: false }).indexOf('\u001b[32m') === -1);
-  assert(util.inspect(subject, { colors: true }).indexOf('\u001b[32m') !== -1);
-  assert(util.inspect(subject, { depth: 2 }).indexOf('c: [Object]') !== -1);
-  assert(util.inspect(subject, { depth: 0 }).indexOf('a: [Object]') !== -1);
-  assert(util.inspect(subject, { depth: null }).indexOf('{ d: 0 }') !== -1);
+  assert.strictEqual(
+    util.inspect(subject, { showHidden: false }).includes('hidden'),
+    false
+  );
+  assert.strictEqual(
+    util.inspect(subject, { showHidden: true }).includes('hidden'),
+    true
+  );
+  assert.strictEqual(
+    util.inspect(subject, { colors: false }).includes('\u001b[32m'),
+    false
+  );
+  assert.strictEqual(
+    util.inspect(subject, { colors: true }).includes('\u001b[32m'),
+    true
+  );
+  assert.strictEqual(
+    util.inspect(subject, { depth: 2 }).includes('c: [Object]'),
+    true
+  );
+  assert.strictEqual(
+    util.inspect(subject, { depth: 0 }).includes('a: [Object]'),
+    true
+  );
+  assert.strictEqual(
+    util.inspect(subject, { depth: null }).includes('{ d: 0 }'),
+    true
+  );
+}
 
+{
   // "customInspect" option can enable/disable calling inspect() on objects
-  subject = { inspect: function() { return 123; } };
+  const subject = { inspect: function() { return 123; } };
 
   assert(util.inspect(subject,
                       { customInspect: true }).indexOf('123') !== -1);
@@ -314,6 +337,56 @@ assert.doesNotThrow(function() {
   util.inspect(subject, { customInspectOptions: true });
 }
 
+{
+  // "customInspect" option can enable/disable calling [util.inspect.custom]()
+  const subject = { [util.inspect.custom]: function() { return 123; } };
+
+  assert.strictEqual(
+    util.inspect(subject, { customInspect: true }).includes('123'),
+    true
+  );
+  assert.strictEqual(
+    util.inspect(subject, { customInspect: false }).includes('123'),
+    false
+  );
+
+  // a custom [util.inspect.custom]() should be able to return other Objects
+  subject[util.inspect.custom] = function() { return { foo: 'bar' }; };
+
+  assert.strictEqual(util.inspect(subject), '{ foo: \'bar\' }');
+
+  subject[util.inspect.custom] = function(depth, opts) {
+    assert.strictEqual(opts.customInspectOptions, true);
+  };
+
+  util.inspect(subject, { customInspectOptions: true });
+}
+
+{
+  // [util.inspect.custom] takes precedence over inspect
+  const subject = {
+    [util.inspect.custom]() { return 123; },
+    inspect() { return 456; }
+  };
+
+  assert.strictEqual(
+    util.inspect(subject, { customInspect: true }).includes('123'),
+    true
+  );
+  assert.strictEqual(
+    util.inspect(subject, { customInspect: false }).includes('123'),
+    false
+  );
+  assert.strictEqual(
+    util.inspect(subject, { customInspect: true }).includes('456'),
+    false
+  );
+  assert.strictEqual(
+    util.inspect(subject, { customInspect: false }).includes('456'),
+    false
+  );
+}
+
 // util.inspect with "colors" option should produce as many lines as without it
 function test_lines(input) {
   var count_lines = function(str) {

From f17e7d28b17ce37258ffbf9b766de0161bd0172b Mon Sep 17 00:00:00 2001
From: Anna Henningsen <anna@addaleax.net>
Date: Fri, 19 Aug 2016 00:44:38 +0200
Subject: [PATCH 2/3] util: allow returning `this` from custom inspect
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

If a custom inspection function returned `this`, use that value
for further formatting instead of going into infinite recursion.

This is particularly useful when combined with `util.inspect.custom`
because returning `this` from such a method makes it easy to
have an `inspect()` function that is ignored by `util.inspect` without
actually having to provide an alternative for custom inspection.

PR-URL: https://github.com/nodejs/node/pull/8174
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michaël Zasso <mic.besace@gmail.com>
---
 lib/util.js                        | 11 ++++++++---
 test/parallel/test-util-inspect.js | 10 ++++++++++
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/lib/util.js b/lib/util.js
index d250edde6b9c3d..d425e7b36fecfc 100644
--- a/lib/util.js
+++ b/lib/util.js
@@ -255,10 +255,15 @@ function formatValue(ctx, value, recurseTimes) {
         // Also filter out any prototype objects using the circular check.
         !(value.constructor && value.constructor.prototype === value)) {
       let ret = maybeCustomInspect.call(value, recurseTimes, ctx);
-      if (typeof ret !== 'string') {
-        ret = formatValue(ctx, ret, recurseTimes);
+
+      // If the custom inspection method returned `this`, don't go into
+      // infinite recursion.
+      if (ret !== value) {
+        if (typeof ret !== 'string') {
+          ret = formatValue(ctx, ret, recurseTimes);
+        }
+        return ret;
       }
-      return ret;
     }
   }
 
diff --git a/test/parallel/test-util-inspect.js b/test/parallel/test-util-inspect.js
index eb0d128d5b26e7..85485f0309717b 100644
--- a/test/parallel/test-util-inspect.js
+++ b/test/parallel/test-util-inspect.js
@@ -387,6 +387,16 @@ assert.doesNotThrow(function() {
   );
 }
 
+{
+  // Returning `this` from a custom inspection function works.
+  assert.strictEqual(util.inspect({ a: 123, inspect() { return this; } }),
+                     '{ a: 123, inspect: [Function: inspect] }');
+
+  const subject = { a: 123, [util.inspect.custom]() { return this; } };
+  assert.strictEqual(util.inspect(subject),
+                     '{ a: 123 }');
+}
+
 // util.inspect with "colors" option should produce as many lines as without it
 function test_lines(input) {
   var count_lines = function(str) {

From 974f984bb48a1cf185aaa7c6ebc0cecc34c598aa Mon Sep 17 00:00:00 2001
From: Charmander <~@charmander.me>
Date: Tue, 25 Oct 2016 22:27:14 -0700
Subject: [PATCH 3/3] buffer: use correct name for custom inspect symbol

59714cb7b3918c9e4fcd94013b778078d3710705 introduced the
`util.inspect.custom` symbol, but it was exported as
`customInspectSymbol` by `internal/util.js` and referenced as
`inspectSymbol` by `buffer.js`.

PR-URL: https://github.com/nodejs/node/pull/9289
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
---
 lib/buffer.js                        | 4 ++--
 test/parallel/test-buffer-inspect.js | 3 +++
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/lib/buffer.js b/lib/buffer.js
index 94306f72034f2f..19c578cea76bd5 100644
--- a/lib/buffer.js
+++ b/lib/buffer.js
@@ -470,7 +470,7 @@ Buffer.prototype.equals = function equals(b) {
 
 
 // Override how buffers are presented by util.inspect().
-Buffer.prototype[internalUtil.inspectSymbol] = function inspect() {
+Buffer.prototype[internalUtil.customInspectSymbol] = function inspect() {
   var str = '';
   var max = exports.INSPECT_MAX_BYTES;
   if (this.length > 0) {
@@ -480,7 +480,7 @@ Buffer.prototype[internalUtil.inspectSymbol] = function inspect() {
   }
   return '<' + this.constructor.name + ' ' + str + '>';
 };
-Buffer.prototype.inspect = Buffer.prototype[internalUtil.inspectSymbol];
+Buffer.prototype.inspect = Buffer.prototype[internalUtil.customInspectSymbol];
 
 
 Buffer.prototype.compare = function compare(b) {
diff --git a/test/parallel/test-buffer-inspect.js b/test/parallel/test-buffer-inspect.js
index 6d44389de735a2..fcdfd3ef5e813e 100644
--- a/test/parallel/test-buffer-inspect.js
+++ b/test/parallel/test-buffer-inspect.js
@@ -36,3 +36,6 @@ assert.doesNotThrow(function() {
   assert.strictEqual(util.inspect(b), expected);
   assert.strictEqual(util.inspect(s), expected);
 });
+
+b.inspect = undefined;
+assert.strictEqual(util.inspect(b), expected);