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.
PR-URL: #27685
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Anto Aravinth <anto.aravinth.cse@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>

Author: BridgeAR

doc/api/util.md

@@ -520,6 +520,24 @@ util.inspect(new Bar()); // 'Bar {}'
 util.inspect(baz); // '[foo] {}'
 ```
 
+Circular references are marked as `'[Circular]'`:
+
+```js
+const { inspect } =require('util');
+
+constobj= {};
+obj.a= [obj];
+obj.b= {};
+obj.b.inner=obj.b;
+obj.b.obj= obj;
+
+console.log(inspect(obj));
+// {
+// a: [ [Circular] ],
+// b: { inner: [Circular], obj: [Circular] }
+// }
+```
+
 The following example inspects all properties of the `util` object:
 
 ```js
@@ -543,8 +561,6 @@ const o = {
 };
 console.log(util.inspect(o, { compact:true, depth:5, breakLength:80 }));
 
-// This will print
-
 // { a:
 // [ 1,
 // 2,

lib/internal/util/inspect.js

@@ -574,8 +574,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))
+if(ctx.seen.includes(value)){
+letindex=1;
+if(ctx.circular===undefined){
+ctx.circular=newMap([[value,index]]);
+}else{
+index=ctx.circular.get(value);
+if(index===undefined){
+index=ctx.circular.size+1;
+ctx.circular.set(value,index);
+}
+}
 returnctx.stylize('[Circular]','special');
+}
 
 returnformatRaw(ctx,value,recurseTimes,typedArray);
 }
@@ -777,6 +788,17 @@ function formatRaw(ctx, value, recurseTimes, typedArray) {
 constconstructorName=getCtxStyle(value,constructor,tag).slice(0,-1);
 returnhandleMaxCallStackSize(ctx,err,constructorName,indentationLvl);
 }
+if(ctx.circular!==undefined){
+constindex=ctx.circular.get(value);
+if(index!==undefined){
+// Add reference always to the very beginning of the output.
+if(ctx.compact!==true){
+base=base==='' ? '' : `${base}`;
+}else{
+braces[0]=`${braces[0]}`;
+}
+}
+}
 ctx.seen.pop();
 
 if(ctx.sorted){

test/parallel/test-assert.js

@@ -342,7 +342,8 @@ testAssertionMessage(/abc/gim, '/abc/gim');
 testAssertionMessage({},'{}');
 testAssertionMessage([1,2,3],'[\n+ 1,\n+ 2,\n+ 3\n+ ]');
 testAssertionMessage(functionf(){},'[Function: f]');
-testAssertionMessage(circular,'{\n+ x: [Circular],\n+ y: 1\n+ }');
+testAssertionMessage(circular,
+'{\n+ x: [Circular],\n+ y: 1\n+ }');
 testAssertionMessage({a: undefined,b: null},
 '{\n+ a: undefined,\n+ b: null\n+ }');
 testAssertionMessage({a: NaN,b: Infinity,c: -Infinity},

test/parallel/test-util-inspect.js

@@ -1049,12 +1049,29 @@ if (typeof Symbol !== 'undefined') {
 {
 constmap=newMap();
 map.set(map,'map');
-assert.strictEqual(util.inspect(map),"Map { [Circular] => 'map' }");
+assert.strictEqual(inspect(map),"Map { [Circular] => 'map' }");
 map.set(map,map);
-assert.strictEqual(util.inspect(map),'Map { [Circular] => [Circular] }');
+assert.strictEqual(
+inspect(map),
+'Map { [Circular] => [Circular] }'
+);
 map.delete(map);
 map.set('map',map);
-assert.strictEqual(util.inspect(map),"Map { 'map' => [Circular] }");
+assert.strictEqual(inspect(map),"Map { 'map' => [Circular] }");
+}
+
+// Test multiple circular references.
+{
+constobj={};
+obj.a=[obj];
+obj.b={};
+obj.b.inner=obj.b;
+obj.b.obj=obj;
+
+assert.strictEqual(
+inspect(obj),
+'{ a: [ [Circular] ], b: { inner: [Circular], obj: [Circular] } }'
+);
 }
 
 // Test Promise.
@@ -1253,6 +1270,8 @@ if (typeof Symbol !== 'undefined') {
 assert.strictEqual(util.inspect(arr),'[ [ [ [Object] ] ] ]');
 arr[0][0][0]=arr;
 assert.strictEqual(util.inspect(arr),'[ [ [ [Circular] ] ] ]');
+arr[0][0][0]=arr[0][0];
+assert.strictEqual(util.inspect(arr),'[ [ [ [Circular] ] ] ]');
 }
 
 // Corner cases.