[New] customInspect: add symbol option, to mimic modern util.inspect behavior

Author: ljharb

index.js

@@ -49,8 +49,8 @@ module.exports = function inspect_(obj, options, depth, seen) {
         throw new TypeError('option "maxStringLength", if provided, must be a positive integer, Infinity, or `null`');
     }
     var customInspect = has(opts, 'customInspect') ? opts.customInspect : true;
-    if (typeof customInspect !== 'boolean') {
-        throw new TypeError('option "customInspect", if provided, must be `true` or `false`');
+    if (typeof customInspect !== 'boolean' && customInspect !== 'symbol') {
+        throw new TypeError('option "customInspect", if provided, must be `true`, `false`, or `\'symbol\'`');
     }
 
     if (
@@ -152,7 +152,7 @@ module.exports = function inspect_(obj, options, depth, seen) {
     if (typeof obj === 'object' && customInspect) {
         if (inspectSymbol && typeof obj[inspectSymbol] === 'function') {
             return obj[inspectSymbol]();
-        } else if (typeof obj.inspect === 'function') {
+        } else if (customInspect !== 'symbol' && typeof obj.inspect === 'function') {
             return obj.inspect();
         }
     }

readme.markdown

@@ -53,7 +53,7 @@ Return a string `s` with the string representation of `obj` up to a depth of `op
 Additional options:
   - `quoteStyle`: must be "single" or "double", if present. Default `'single'` for strings, `'double'` for HTML elements.
   - `maxStringLength`: must be `0`, a positive integer, `Infinity`, or `null`, if present. Default `Infinity`.
-  - `customInspect`: When `true`, a custom inspect method function will be invoked. Default `true`.
+  - `customInspect`: When `true`, a custom inspect method function will be invoked (either undere the `util.inspect.custom` symbol, or the `inspect` property). When the string `'symbol'`, only the symbol method will be invoked. Default `true`.
   - `indent`: must be "\t", `null`, or a positive integer. Default `null`.
 
 # install

test/inspect.js

@@ -6,30 +6,40 @@ var repeat = require('string.prototype.repeat');
 var inspect = require('..');
 
 test('inspect', function (t) {
-    t.plan(4);
+    t.plan(5);
+
     var obj = [{ inspect: function xyzInspect() { return '!XYZ¡'; } }, []];
-    t.equal(inspect(obj), '[ !XYZ¡, [] ]');
-    t.equal(inspect(obj, { customInspect: true }), '[ !XYZ¡, [] ]');
-    t.equal(inspect(obj, { customInspect: false }), '[ { inspect: [Function: xyzInspect] }, [] ]');
+    var stringResult = '[ !XYZ¡, [] ]';
+    var falseResult = '[ { inspect: [Function: xyzInspect] }, [] ]';
+
+    t.equal(inspect(obj), stringResult);
+    t.equal(inspect(obj, { customInspect: true }), stringResult);
+    t.equal(inspect(obj, { customInspect: 'symbol' }), falseResult);
+    t.equal(inspect(obj, { customInspect: false }), falseResult);
     t['throws'](
-        function () { inspect(obj, { customInspect: 'not a boolean' }); },
+        function () { inspect(obj, { customInspect: 'not a boolean or "symbol"' }); },
         TypeError,
-        '`customInspect` must be a boolean'
+        '`customInspect` must be a boolean or the string "symbol"'
     );
 });
 
 test('inspect custom symbol', { skip: !hasSymbols || !utilInspect || !utilInspect.custom }, function (t) {
-    t.plan(3);
+    t.plan(4);
 
     var obj = { inspect: function stringInspect() { return 'string'; } };
     obj[utilInspect.custom] = function custom() { return 'symbol'; };
 
-    t.equal(inspect([obj, []]), '[ ' + (utilInspect.custom ? 'symbol' : 'string') + ', [] ]');
-    t.equal(inspect([obj, []], { customInspect: true }), '[ ' + (utilInspect.custom ? 'symbol' : 'string') + ', [] ]');
-    t.equal(
-        inspect([obj, []], { customInspect: false }),
-        '[ { inspect: [Function: stringInspect]' + (utilInspect.custom ? ', [' + inspect(utilInspect.custom) + ']: [Function: custom]' : '') + ' }, [] ]'
-    );
+    var symbolResult = '[ symbol, [] ]';
+    var stringResult = '[ string, [] ]';
+    var falseResult = '[ { inspect: [Function: stringInspect]' + (utilInspect.custom ? ', [' + inspect(utilInspect.custom) + ']: [Function: custom]' : '') + ' }, [] ]';
+
+    var symbolStringFallback = utilInspect.custom ? symbolResult : stringResult;
+    var symbolFalseFallback = utilInspect.custom ? symbolResult : falseResult;
+
+    t.equal(inspect([obj, []]), symbolStringFallback);
+    t.equal(inspect([obj, []], { customInspect: true }), symbolStringFallback);
+    t.equal(inspect([obj, []], { customInspect: 'symbol' }), symbolFalseFallback);
+    t.equal(inspect([obj, []], { customInspect: false }), falseResult);
 });
 
 test('symbols', { skip: !hasSymbols }, function (t) {