From 59adf42ae859dab36f785f1762781a8878ae1242 Mon Sep 17 00:00:00 2001
From: Ruben Bridgewater <ruben@bridgewater.de>
Date: Tue, 14 May 2019 02:53:22 +0200
Subject: [PATCH] util: include reference anchor for circular structures

This adds a reference anchor to circular structures when using
`util.inspect`. That way it's possible to identify with what object
the circular reference corresponds too.
---
 doc/api/util.md                    | 23 +++++++++++++--
 lib/internal/util/inspect.js       | 27 ++++++++++++++++--
 test/parallel/test-assert.js       |  3 +-
 test/parallel/test-util-format.js  | 24 ++++++++--------
 test/parallel/test-util-inspect.js | 46 ++++++++++++++++++++++--------
 5 files changed, 94 insertions(+), 29 deletions(-)

diff --git a/doc/api/util.md b/doc/api/util.md
index c0b909d438d15f..28554d5373e2aa 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -390,6 +390,9 @@ stream.write('With ES6');
 <!-- YAML
 added: v0.3.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/REPLACEME
+    description: Circular references now include a marker to the reference.
   - version: v12.0.0
     pr-url: https://github.com/nodejs/node/pull/27109
     description: The `compact` options default is changed to `3` and the
@@ -512,6 +515,24 @@ util.inspect(new Bar()); // 'Bar {}'
 util.inspect(baz);       // '[foo] {}'
 ```
 
+Circular references point to their anchor by using a reference index:
+
+```js
+const { inspect } = require('util');
+
+const obj = {};
+obj.a = [obj];
+obj.b = {};
+obj.b.inner = obj.b;
+obj.b.obj = obj;
+
+console.log(inspect(obj));
+// <ref *1> {
+//   a: [ [Circular *1] ],
+//   b: <ref *2> { inner: [Circular *2], obj: [Circular *1] }
+// }
+```
+
 The following example inspects all properties of the `util` object:
 
 ```js
@@ -535,8 +556,6 @@ const o = {
 };
 console.log(util.inspect(o, { compact: true, depth: 5, breakLength: 80 }));
 
-// This will print
-
 // { a:
 //   [ 1,
 //     2,
diff --git a/lib/internal/util/inspect.js b/lib/internal/util/inspect.js
index 1e7277ef38bfad..6e6e4e8070da16 100644
--- a/lib/internal/util/inspect.js
+++ b/lib/internal/util/inspect.js
@@ -557,8 +557,19 @@ function formatValue(ctx, value, recurseTimes, typedArray) {
 
   // Using an array here is actually better for the average case than using
   // a Set. `seen` will only check for the depth and will never grow too large.
-  if (ctx.seen.includes(value))
-    return ctx.stylize('[Circular]', 'special');
+  if (ctx.seen.includes(value)) {
+    let index = 1;
+    if (ctx.circular === undefined) {
+      ctx.circular = new Map([[value, index]]);
+    } else {
+      index = ctx.circular.get(value);
+      if (index === undefined) {
+        index = ctx.circular.size + 1;
+        ctx.circular.set(value, index);
+      }
+    }
+    return ctx.stylize(`[Circular *${index}]`, 'special');
+  }
 
   return formatRaw(ctx, value, recurseTimes, typedArray);
 }
@@ -755,6 +766,18 @@ function formatRaw(ctx, value, recurseTimes, typedArray) {
   } catch (err) {
     return handleMaxCallStackSize(ctx, err, constructor, tag, indentationLvl);
   }
+  if (ctx.circular !== undefined) {
+    const index = ctx.circular.get(value);
+    if (index !== undefined) {
+      const reference = ctx.stylize(`<ref *${index}>`, 'special');
+      // Add reference always to the very beginning of the output.
+      if (ctx.compact !== true) {
+        base = base === '' ? reference : `${reference} ${base}`;
+      } else {
+        braces[0] = `${reference} ${braces[0]}`;
+      }
+    }
+  }
   ctx.seen.pop();
 
   if (ctx.sorted) {
diff --git a/test/parallel/test-assert.js b/test/parallel/test-assert.js
index b7d81f549547ed..a9c50b565bed95 100644
--- a/test/parallel/test-assert.js
+++ b/test/parallel/test-assert.js
@@ -298,7 +298,8 @@ testAssertionMessage({}, '{}');
 testAssertionMessage([1, 2, 3], '[\n+   1,\n+   2,\n+   3\n+ ]');
 testAssertionMessage(function f() {}, '[Function: f]');
 testAssertionMessage(function() {}, '[Function (anonymous)]');
-testAssertionMessage(circular, '{\n+   x: [Circular],\n+   y: 1\n+ }');
+testAssertionMessage(circular,
+                     '<ref *1> {\n+   x: [Circular *1],\n+   y: 1\n+ }');
 testAssertionMessage({ a: undefined, b: null },
                      '{\n+   a: undefined,\n+   b: null\n+ }');
 testAssertionMessage({ a: NaN, b: Infinity, c: -Infinity },
diff --git a/test/parallel/test-util-format.js b/test/parallel/test-util-format.js
index fa0f66ecfc3fa1..726dd2270865ab 100644
--- a/test/parallel/test-util-format.js
+++ b/test/parallel/test-util-format.js
@@ -173,10 +173,10 @@ assert.strictEqual(
   '{\n' +
   '  foo: \'bar\',\n' +
   '  foobar: 1,\n' +
-  '  func: [Function: func] {\n' +
+  '  func: <ref *1> [Function: func] {\n' +
   '    [length]: 0,\n' +
   '    [name]: \'func\',\n' +
-  '    [prototype]: func { [constructor]: [Circular] }\n' +
+  '    [prototype]: func { [constructor]: [Circular *1] }\n' +
   '  }\n' +
   '}');
 assert.strictEqual(
@@ -186,10 +186,10 @@ assert.strictEqual(
   '  foobar: 1,\n' +
   '  func: [\n' +
   '    {\n' +
-  '      a: [Function: a] {\n' +
+  '      a: <ref *1> [Function: a] {\n' +
   '        [length]: 0,\n' +
   '        [name]: \'a\',\n' +
-  '        [prototype]: a { [constructor]: [Circular] }\n' +
+  '        [prototype]: a { [constructor]: [Circular *1] }\n' +
   '      }\n' +
   '    },\n' +
   '    [length]: 1\n' +
@@ -201,10 +201,10 @@ assert.strictEqual(
   '  foo: \'bar\',\n' +
   '  foobar: {\n' +
   '    foo: \'bar\',\n' +
-  '    func: [Function: func] {\n' +
+  '    func: <ref *1> [Function: func] {\n' +
   '      [length]: 0,\n' +
   '      [name]: \'func\',\n' +
-  '      [prototype]: func { [constructor]: [Circular] }\n' +
+  '      [prototype]: func { [constructor]: [Circular *1] }\n' +
   '    }\n' +
   '  }\n' +
   '}');
@@ -213,18 +213,18 @@ assert.strictEqual(
   '{\n' +
   '  foo: \'bar\',\n' +
   '  foobar: 1,\n' +
-  '  func: [Function: func] {\n' +
+  '  func: <ref *1> [Function: func] {\n' +
   '    [length]: 0,\n' +
   '    [name]: \'func\',\n' +
-  '    [prototype]: func { [constructor]: [Circular] }\n' +
+  '    [prototype]: func { [constructor]: [Circular *1] }\n' +
   '  }\n' +
   '} {\n' +
   '  foo: \'bar\',\n' +
   '  foobar: 1,\n' +
-  '  func: [Function: func] {\n' +
+  '  func: <ref *1> [Function: func] {\n' +
   '    [length]: 0,\n' +
   '    [name]: \'func\',\n' +
-  '    [prototype]: func { [constructor]: [Circular] }\n' +
+  '    [prototype]: func { [constructor]: [Circular *1] }\n' +
   '  }\n' +
   '}');
 assert.strictEqual(
@@ -232,10 +232,10 @@ assert.strictEqual(
   '{\n' +
   '  foo: \'bar\',\n' +
   '  foobar: 1,\n' +
-  '  func: [Function: func] {\n' +
+  '  func: <ref *1> [Function: func] {\n' +
   '    [length]: 0,\n' +
   '    [name]: \'func\',\n' +
-  '    [prototype]: func { [constructor]: [Circular] }\n' +
+  '    [prototype]: func { [constructor]: [Circular *1] }\n' +
   '  }\n' +
   '} %o');
 
diff --git a/test/parallel/test-util-inspect.js b/test/parallel/test-util-inspect.js
index fc69f41ef4274a..ea73633e9d1dbb 100644
--- a/test/parallel/test-util-inspect.js
+++ b/test/parallel/test-util-inspect.js
@@ -338,7 +338,7 @@ assert.strictEqual(
 
   const value = {};
   value.a = value;
-  assert.strictEqual(util.inspect(value), '{ a: [Circular] }');
+  assert.strictEqual(util.inspect(value), '<ref *1> { a: [Circular *1] }');
 }
 
 // Array with dynamic properties.
@@ -993,7 +993,7 @@ if (typeof Symbol !== 'undefined') {
 {
   const set = new Set();
   set.add(set);
-  assert.strictEqual(util.inspect(set), 'Set { [Circular] }');
+  assert.strictEqual(util.inspect(set), '<ref *1> Set { [Circular *1] }');
 }
 
 // Test Map.
@@ -1011,12 +1011,32 @@ if (typeof Symbol !== 'undefined') {
 {
   const map = new Map();
   map.set(map, 'map');
-  assert.strictEqual(util.inspect(map), "Map { [Circular] => 'map' }");
+  assert.strictEqual(inspect(map), "<ref *1> Map { [Circular *1] => 'map' }");
   map.set(map, map);
-  assert.strictEqual(util.inspect(map), 'Map { [Circular] => [Circular] }');
+  assert.strictEqual(
+    inspect(map),
+    '<ref *1> Map { [Circular *1] => [Circular *1] }'
+  );
   map.delete(map);
   map.set('map', map);
-  assert.strictEqual(util.inspect(map), "Map { 'map' => [Circular] }");
+  assert.strictEqual(inspect(map), "<ref *1> Map { 'map' => [Circular *1] }");
+}
+
+// Test multiple circular references.
+{
+  const obj = {};
+  obj.a = [obj];
+  obj.b = {};
+  obj.b.inner = obj.b;
+  obj.b.obj = obj;
+
+  assert.strictEqual(
+    inspect(obj),
+    '<ref *1> {\n' +
+    '  a: [ [Circular *1] ],\n' +
+    '  b: <ref *2> { inner: [Circular *2], obj: [Circular *1] }\n' +
+    '}'
+  );
 }
 
 // Test Promise.
@@ -1169,7 +1189,9 @@ if (typeof Symbol !== 'undefined') {
   arr[0][0][0] = { a: 2 };
   assert.strictEqual(util.inspect(arr), '[ [ [ [Object] ] ] ]');
   arr[0][0][0] = arr;
-  assert.strictEqual(util.inspect(arr), '[ [ [ [Circular] ] ] ]');
+  assert.strictEqual(util.inspect(arr), '<ref *1> [ [ [ [Circular *1] ] ] ]');
+  arr[0][0][0] = arr[0][0];
+  assert.strictEqual(util.inspect(arr), '[ [ <ref *1> [ [Circular *1] ] ] ]');
 }
 
 // Corner cases.
@@ -1563,7 +1585,7 @@ util.inspect(process);
     '      2,',
     '      [length]: 2',
     '    ]',
-    '  } => [Map Iterator] {',
+    '  } => <ref *1> [Map Iterator] {',
     '    Uint8Array [',
     '      [BYTES_PER_ELEMENT]: 1,',
     '      [length]: 0,',
@@ -1574,7 +1596,7 @@ util.inspect(process);
     '        foo: true',
     '      }',
     '    ],',
-    '    [Circular]',
+    '    [Circular *1]',
     '  },',
     '  [size]: 2',
     '}'
@@ -1602,7 +1624,7 @@ util.inspect(process);
     '    [byteOffset]: 0,',
     '    [buffer]: ArrayBuffer { byteLength: 0, foo: true }',
     '  ],',
-    '  [Set Iterator] { [ 1, 2, [length]: 2 ] } => [Map Iterator] {',
+    '  [Set Iterator] { [ 1, 2, [length]: 2 ] } => <ref *1> [Map Iterator] {',
     '    Uint8Array [',
     '      [BYTES_PER_ELEMENT]: 1,',
     '      [length]: 0,',
@@ -1610,7 +1632,7 @@ util.inspect(process);
     '      [byteOffset]: 0,',
     '      [buffer]: ArrayBuffer { byteLength: 0, foo: true }',
     '    ],',
-    '    [Circular]',
+    '    [Circular *1]',
     '  },',
     '  [size]: 2',
     '}'
@@ -1642,7 +1664,7 @@ util.inspect(process);
     '  [Set Iterator] {',
     '    [ 1,',
     '      2,',
-    '      [length]: 2 ] } => [Map Iterator] {',
+    '      [length]: 2 ] } => <ref *1> [Map Iterator] {',
     '    Uint8Array [',
     '      [BYTES_PER_ELEMENT]: 1,',
     '      [length]: 0,',
@@ -1651,7 +1673,7 @@ util.inspect(process);
     '      [buffer]: ArrayBuffer {',
     '        byteLength: 0,',
     '        foo: true } ],',
-    '    [Circular] },',
+    '    [Circular *1] },',
     '  [size]: 2 }'
   ].join('\n');