Support custom inspect through 'nodejs.util.inspect.custom' symbol

Fixes #1599
See https://nodejs.org/api/util.html#util_custom_inspection_functions_on_objects

Author: IvanGoncharov

src/jsutils/__tests__/inspect-test.js

@@ -10,6 +10,8 @@
 import { expect } from 'chai';
 import { describe, it } from 'mocha';
 import inspect from '../inspect';
+import invariant from '../invariant';
+import nodejsCustomInspectSymbol from '../nodejsCustomInspectSymbol';
 
 describe('inspect', () => {
   it('undefined', () => {
@@ -75,4 +77,19 @@ describe('inspect', () => {
 
     expect(inspect(object)).to.equal('<custom inspect>');
   });
+
+  it('custom inspect', () => {
+    invariant(nodejsCustomInspectSymbol);
+
+    const object = {
+      inspect() {
+        return '<custom inspect>';
+      },
+      [String(nodejsCustomInspectSymbol)]() {
+        return '<custom symbol inspect>';
+      },
+    };
+
+    expect(inspect(object)).to.equal('<custom symbol inspect>');
+  });
 });

src/jsutils/defineToJSON.js

@@ -7,11 +7,20 @@
  * @flow strict
  */
 
+import nodejsCustomInspectSymbol from './nodejsCustomInspectSymbol';
+
 /**
  * The `defineToJSON()` function defines toJSON() and inspect() prototype
- * methods which are aliases for toString().
+ * methods, if no function provided they become aliases for toString().
  */
-export default function defineToJSON(classObject: Class<any>): void {
-  classObject.prototype.toJSON = classObject.prototype.inspect =
-    classObject.prototype.toString;
+export default function defineToJSON(
+  // eslint-disable-next-line flowtype/no-weak-types
+  classObject: Class<any> | Function,
+  fn?: () => any = classObject.prototype.toString,
+): void {
+  classObject.prototype.toJSON = fn;
+  classObject.prototype.inspect = fn;
+  if (nodejsCustomInspectSymbol) {
+    classObject.prototype[nodejsCustomInspectSymbol] = fn;
+  }
 }

src/jsutils/inspect.js

@@ -7,6 +7,8 @@
  * @flow strict
  */
 
+import nodejsCustomInspectSymbol from './nodejsCustomInspectSymbol';
+
 /**
  * Used to print values in error messages.
  */
@@ -18,7 +20,10 @@ export default function inspect(value: mixed): string {
       return value.name ? `[function ${value.name}]` : '[function]';
     case 'object':
       if (value) {
-        if (typeof value.inspect === 'function') {
+        const customInspectFn = value[String(nodejsCustomInspectSymbol)];
+        if (typeof customInspectFn === 'function') {
+          return customInspectFn();
+        } else if (typeof value.inspect === 'function') {
           return value.inspect();
         } else if (Array.isArray(value)) {
           return '[' + value.map(inspect).join(', ') + ']';

src/jsutils/nodejsCustomInspectSymbol.js

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2018-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ */
+
+const nodejsCustomInspectSymbol =
+  typeof Symbol === 'function'
+    ? Symbol.for('nodejs.util.inspect.custom')
+    : undefined;
+
+export default nodejsCustomInspectSymbol;

src/language/lexer.js

@@ -7,6 +7,7 @@
  * @flow strict
  */
 
+import defineToJSON from '../jsutils/defineToJSON';
 import type { Token } from './ast';
 import type { Source } from './source';
 import { syntaxError } from '../error';
@@ -162,14 +163,14 @@ function Tok(
 }
 
 // Print a simplified form when appearing in JSON/util.inspect.
-Tok.prototype.toJSON = Tok.prototype.inspect = function toJSON() {
+defineToJSON(Tok, function() {
   return {
     kind: this.kind,
     value: this.value,
     line: this.line,
     column: this.column,
   };
-};
+});
 
 function printCharCode(code) {
   return (

src/language/parser.js

@@ -8,6 +8,7 @@
  */
 
 import inspect from '../jsutils/inspect';
+import defineToJSON from '../jsutils/defineToJSON';
 import { Source } from './source';
 import { syntaxError } from '../error';
 import type { GraphQLError } from '../error';
@@ -1444,9 +1445,9 @@ function Loc(startToken: Token, endToken: Token, source: Source) {
 }
 
 // Print a simplified form when appearing in JSON/util.inspect.
-Loc.prototype.toJSON = Loc.prototype.inspect = function toJSON() {
+defineToJSON(Loc, function() {
   return { start: this.start, end: this.end };
-};
+});
 
 /**
  * Determines if the next token is of a given kind