util: support RawJSON exotic objects in inspector

doc/api/util.md

@@ -911,6 +911,9 @@ stream.write('With ES6');
 <!-- YAML
 added: v0.3.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/65225
+    description: The `RawJSON` exotic objects are recognized now.
   - version:
     - v25.0.0
     pr-url: https://github.com/nodejs/node/pull/59710

lib/internal/util/inspect.js

@@ -41,6 +41,8 @@ const {
   FunctionPrototypeCall,
   FunctionPrototypeSymbolHasInstance,
   FunctionPrototypeToString,
+  JSONIsRawJSON,
+  JSONParse,
   JSONStringify,
   Map,
   MapPrototype,
@@ -1404,6 +1406,8 @@ function formatRaw(ctx, value, recurseTimes, typedArray) {
       if (keys.length === 0 && protoProps === undefined) {
         return base;
       }
+    } else if (JSONIsRawJSON(value)) {
+      return formatRawJSON(ctx, value.rawJSON);
     } else {
       if (keys.length === 0 && protoProps === undefined) {
         if (isExternal(value)) {
@@ -2541,6 +2545,32 @@ function formatPromise(ctx, value, recurseTimes) {
   return output;
 }
 
+function formatRawJSON(ctx, rawJSON) {
+  // rawJSON is guaranteed to be a valid JSON string for a primitive value
+  const parsed = JSONParse(rawJSON);
+
+  let formattedValue;
+
+  if (parsed === null) {
+    formattedValue = ctx.stylize('null', 'null');
+  } else if (typeof parsed === 'boolean') {
+    formattedValue = ctx.stylize(`${parsed}`, 'boolean');
+  } else if (typeof parsed === 'string') {
+    formattedValue = formatPrimitive(ctx.stylize, parsed, ctx);
+  } else {
+    const asString = ObjectIs(parsed, -0) ? '-0' : `${parsed}`;
+    if (asString === rawJSON) {
+      formattedValue = formatNumber(ctx.stylize, parsed, ctx.numericSeparator);
+    } else {
+      // We do not apply formatNumber intentionally because it would strip
+      // exponent or trailing zeros. We use original spelling as-is.
+      formattedValue = ctx.stylize(rawJSON, 'number');
+    }
+  }
+
+  return `${ctx.stylize('RawJSON', 'special')} { ${formattedValue} }`;
+}
+
 function formatExtraProperties(ctx, value, recurseTimes, key, typedArray) {
   ctx.indentationLvl += 2;
   const str = formatValue(ctx, value[key], recurseTimes, typedArray);

test/parallel/test-util-inspect-rawjson.js

@@ -0,0 +1,71 @@
+'use strict';
+
+require('../common');
+const assert = require('assert');
+const util = require('util');
+
+const cases = [
+  [null, 'RawJSON { null }'],
+  ['null', 'RawJSON { null }'],
+  [true, 'RawJSON { true }'],
+  ['true', 'RawJSON { true }'],
+  [false, 'RawJSON { false }'],
+  ['false', 'RawJSON { false }'],
+  ['"blep"', "RawJSON { 'blep' }"],
+  ['""', "RawJSON { '' }"],
+  [42, 'RawJSON { 42 }'],
+  ['42', 'RawJSON { 42 }'],
+  [-0, 'RawJSON { 0 }'],
+  ['-0', 'RawJSON { -0 }'],
+  [1.25, 'RawJSON { 1.25 }'],
+  ['1.25', 'RawJSON { 1.25 }'],
+  [42.00, 'RawJSON { 42 }'],
+  ['42.00', 'RawJSON { 42.00 }'],
+  [1e3, 'RawJSON { 1000 }'],
+  ['1e3', 'RawJSON { 1e3 }'],
+  [12345678901234567890n, 'RawJSON { 12345678901234567890 }'],
+  ['12345678901234567890', 'RawJSON { 12345678901234567890 }'],
+];
+
+for (const [raw, expected] of cases) {
+  const value = JSON.rawJSON(raw);
+  assert.strictEqual(util.inspect(value), expected);
+  assert.strictEqual(util.inspect(value, { showHidden: true }), expected);
+}
+
+// When raw number differs from normalized number representation,
+// numeric formatting must be disabled
+assert.strictEqual(
+  util.inspect(JSON.rawJSON('42'), { numericSeparator: true }),
+  'RawJSON { 42 }',
+);
+assert.strictEqual(
+  util.inspect(JSON.rawJSON('-0'), { numericSeparator: true }),
+  'RawJSON { -0 }',
+);
+assert.strictEqual(
+  util.inspect(JSON.rawJSON('-0.00'), { numericSeparator: true }),
+  'RawJSON { -0.00 }',
+);
+assert.strictEqual(
+  util.inspect(JSON.rawJSON('1234567'), { numericSeparator: true }),
+  'RawJSON { 1_234_567 }',
+);
+assert.strictEqual(
+  util.inspect(JSON.rawJSON('1234567.00'), { numericSeparator: true }),
+  'RawJSON { 1234567.00 }',
+);
+assert.strictEqual(
+  util.inspect(JSON.rawJSON('1.234567e+6'), { numericSeparator: true }),
+  'RawJSON { 1.234567e+6 }',
+);
+assert.strictEqual(
+  util.inspect(JSON.rawJSON('12345678901234567890'), { numericSeparator: true }),
+  'RawJSON { 12345678901234567890 }',
+);
+
+// Test for false positive duck typing
+assert.strictEqual(
+  util.inspect({ __proto__: null, rawJSON: 'null' }),
+  "[Object: null prototype] { rawJSON: 'null' }",
+);