util: add order option to .inspect()

The order option can be used to sort the inspected values in case they do not rely on their order as arrays. That way the output is stable no matter of the object property inspection order.
nodejs · BridgeAR · Sep 10, 2018 · Sep 17, 2018 · Sep 10, 2018 · Sep 18, 2018
commit 28ffb3b03faa80f529004ba93a0ff2f833979d67
diff --git a/doc/api/util.md b/doc/api/util.md
@@ -360,6 +360,9 @@ stream.write('With ES6');
 <!-- YAML
 added: v0.3.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/REPLACEME
+    description: The `sorted` option is supported now.
   - version: REPLACEME
     pr-url: https://github.com/nodejs/node/pull/22756
     description: The inspection output is now limited to about 128 MB. Data
@@ -426,6 +429,10 @@ changes:
     objects the same as arrays. Note that no text will be reduced below 16
     characters, no matter the `breakLength` size. For more information, see the
     example below. **Default:** `true`.
+  * `sorted` {boolean|Function} If specified, the output for all object types
+    besides arrays and typed arrays is going to be stable. If set to `true` the
+    default sort is going to be used. If set to a function, it is used as
+    [compare function][].
 * Returns: {string} The representation of passed object
 
 The `util.inspect()` method returns a string representation of `object` that is
@@ -2150,6 +2157,7 @@ Deprecated predecessor of `console.log`.
 [WHATWG Encoding Standard]: https://encoding.spec.whatwg.org/
 [Common System Errors]: errors.html#errors_common_system_errors
 [async function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function
+[compare function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort
 [constructor]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/constructor
 [global symbol registry]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/for
 [list of deprecated APIS]: deprecations.html#deprecations_list_of_deprecated_apis

diff --git a/lib/util.js b/lib/util.js
@@ -99,7 +99,8 @@ const inspectDefaultOptions = Object.seal({
   showProxy: false,
   maxArrayLength: 100,
   breakLength: 60,
-  compact: true
+  compact: true,
+  sorted: false
 });
 
 const kObjectType = 0;
@@ -394,6 +395,8 @@ function debuglog(set) {
 function inspect(value, opts) {
   // Default options
   const ctx = {
+    budget: {},
+    indentationLvl: 0,
     seen: [],
     stylize: stylizeNoColor,
     showHidden: inspectDefaultOptions.showHidden,
@@ -405,9 +408,8 @@ function inspect(value, opts) {
     // `maxEntries`.
     maxArrayLength: inspectDefaultOptions.maxArrayLength,
     breakLength: inspectDefaultOptions.breakLength,
-    indentationLvl: 0,
     compact: inspectDefaultOptions.compact,
-    budget: {}
+    sorted: inspectDefaultOptions.sorted
   };
   if (arguments.length > 1) {
     // Legacy...
@@ -894,6 +896,11 @@ function formatRaw(ctx, value, recurseTimes) {
   }
   ctx.seen.pop();
 
+  if (ctx.sorted && extrasType === kObjectType) {
+    const comparator = ctx.sorted === true ? undefined : ctx.sorted;
+    output = output.sort(comparator);
+  }
+
   const res = reduceToSingleString(ctx, output, base, braces);
   const budget = ctx.budget[ctx.indentationLvl] || 0;
   const newLength = budget + res.length;

diff --git a/test/parallel/test-util-inspect.js b/test/parallel/test-util-inspect.js
@@ -1675,3 +1675,19 @@ assert.strictEqual(inspect(new BigUint64Array([0n])), 'BigUint64Array [ 0n ]');
   );
   rejection.catch(() => {});
 }
+
+assert.strictEqual(
+  inspect([1, 3, 2], { sorted: true }),
+  inspect([1, 3, 2])
+);
+assert.strictEqual(
+  inspect({ c: 3, a: 1, b: 2 }, { sorted: true }),
+  '{ a: 1, b: 2, c: 3 }'
+);
+assert.strictEqual(
+  inspect(
+    { a200: 4, a100: 1, a102: 3, a101: 2 },
+    { sorted(a, b) { return a < b; } }
+  ),
+  '{ a200: 4, a102: 3, a101: 2, a100: 1 }'
+);