From 68eaa8789a32cb73c31fab7d7c1d0ab7ab7ea729 Mon Sep 17 00:00:00 2001
From: Ruben Bridgewater <ruben@bridgewater.de>
Date: Mon, 10 Sep 2018 08:55:00 +0200
Subject: [PATCH] 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.

Backport-PR-URL: https://github.com/nodejs/node/pull/23039
PR-URL: https://github.com/nodejs/node/pull/22788
Refs: https://github.com/nodejs/node/issues/22763
Reviewed-By: John-David Dalton <john.david.dalton@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
---
 doc/api/util.md                    | 38 +++++++++++++++++++++++++++++-
 lib/util.js                        | 19 ++++++++++++---
 test/parallel/test-util-inspect.js | 30 +++++++++++++++++++++++
 3 files changed, 83 insertions(+), 4 deletions(-)

diff --git a/doc/api/util.md b/doc/api/util.md
index 8dfbfd874c762a..592e39bb442183 100644
--- 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/22788
+    description: The `sorted` option is supported now.
   - version: v10.6.0
     pr-url: https://github.com/nodejs/node/pull/20725
     description: Inspecting linked lists and similar objects is now possible
@@ -420,7 +423,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 set to `true` or a function, all properties
+    of an object and Set and Map entries will be sorted in the returned string.
+    If set to `true` the [default sort][] is going to be used. If set to a
+    function, it is used as a [compare function][].
 * Returns: {string} The representation of passed object
 
 The `util.inspect()` method returns a string representation of `object` that is
@@ -534,6 +540,34 @@ console.log(inspect(weakSet, { showHidden: true }));
 // WeakSet { { a: 1 }, { b: 2 } }
 ```
 
+The `sorted` option makes sure the output is identical, no matter of the
+properties insertion order:
+
+```js
+const { inspect } = require('util');
+const assert = require('assert');
+
+const o1 = {
+  b: [2, 3, 1],
+  a: '`a` comes before `b`',
+  c: new Set([2, 3, 1])
+};
+console.log(inspect(o1, { sorted: true }));
+// { a: '`a` comes before `b`', b: [ 2, 3, 1 ], c: Set { 1, 2, 3 } }
+console.log(inspect(o1, { sorted: (a, b) => a < b }));
+// { c: Set { 3, 2, 1 }, b: [ 2, 3, 1 ], a: '`a` comes before `b`' }
+
+const o2 = {
+  c: new Set([2, 1, 3]),
+  a: '`a` comes before `b`',
+  b: [2, 3, 1]
+};
+assert.strict.equal(
+  inspect(o1, { sorted: true }),
+  inspect(o2, { sorted: true })
+);
+```
+
 Please note that `util.inspect()` is a synchronous method that is mainly
 intended as a debugging tool. Some input values can have a significant
 performance overhead that can block the event loop. Use this function
@@ -2150,7 +2184,9 @@ 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#Parameters
 [constructor]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/constructor
+[default sort]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort
 [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
 [semantically incompatible]: https://github.com/nodejs/node/issues/4179
diff --git a/lib/util.js b/lib/util.js
index cfced8d9942d68..17cf314ee96626 100644
--- 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;
@@ -344,6 +345,8 @@ function debuglog(set) {
 function inspect(value, opts) {
   // Default options
   const ctx = {
+    budget: {},
+    indentationLvl: 0,
     seen: [],
     stylize: stylizeNoColor,
     showHidden: inspectDefaultOptions.showHidden,
@@ -355,8 +358,8 @@ function inspect(value, opts) {
     // `maxEntries`.
     maxArrayLength: inspectDefaultOptions.maxArrayLength,
     breakLength: inspectDefaultOptions.breakLength,
-    indentationLvl: 0,
-    compact: inspectDefaultOptions.compact
+    compact: inspectDefaultOptions.compact,
+    sorted: inspectDefaultOptions.sorted
   };
   // Legacy...
   if (arguments.length > 2) {
@@ -846,6 +849,16 @@ function formatRaw(ctx, value, recurseTimes) {
   }
   ctx.seen.pop();
 
+  if (ctx.sorted) {
+    const comparator = ctx.sorted === true ? undefined : ctx.sorted;
+    if (extrasType === kObjectType) {
+      output = output.sort(comparator);
+    } else if (keys.length > 1) {
+      const sorted = output.slice(output.length - keys.length).sort(comparator);
+      output.splice(output.length - keys.length, keys.length, ...sorted);
+    }
+  }
+
   return reduceToSingleString(ctx, output, base, braces);
 }
 
diff --git a/test/parallel/test-util-inspect.js b/test/parallel/test-util-inspect.js
index 70084759f83546..de7ae79b44edbb 100644
--- a/test/parallel/test-util-inspect.js
+++ b/test/parallel/test-util-inspect.js
@@ -1718,3 +1718,33 @@ assert.strictEqual(inspect(Object(13n)), '[BigInt: 13n]');
   );
   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 }'
+);
+
+// Non-indices array properties are sorted as well.
+{
+  const arr = [3, 2, 1];
+  arr.b = 2;
+  arr.c = 3;
+  arr.a = 1;
+  arr[Symbol('b')] = true;
+  arr[Symbol('a')] = false;
+  assert.strictEqual(
+    inspect(arr, { sorted: true }),
+    '[ 3, 2, 1, [Symbol(a)]: false, [Symbol(b)]: true, a: 1, b: 2, c: 3 ]'
+  );
+}