util: expose diff function used by the assertion errors

fix: #51740

Author: puskin

doc/api/util.md

@@ -325,6 +325,56 @@ The `--throw-deprecation` command-line flag and `process.throwDeprecation`
 property take precedence over `--trace-deprecation` and
 `process.traceDeprecation`.
 
+## `util.diff(actual, expected)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `actual` {Array|string} The first value to compare
+* `expected` {Array|string} The second value to compare
+* Returns: {Array} An array of difference objects. Each object has properties:
+  * `type` {string} One of 'insert', 'delete', or 'nop' (no operation/unchanged)
+  * `value` {any} The value that was inserted, deleted, or unchanged
+* Algorithm complexity: O(N\*D), where:
+* N is the total length of the two sequences combined (N = actual.length + expected.length)
+* D is the edit distance (the minimum number of operations required to transform one sequence into the other).
+
+[`util.diff()`][] compares two values and returns an array of objects representing
+the differences between them. It uses the Myers diff algorithm to compute minimal
+differences, which is the same algorithm used internally by assertion error messages.
+
+The array elements appear in reverse order compared to the differences in the original values.
+If the values are equal according to `isDeepStrictEqual()`, an empty array is returned.
+
+```js
+const { diff } = require('node:util');
+
+// Comparing arrays
+const result = diff([1, 2, 3], [1, 2, 4]);
+console.log(result);
+// [
+//   { type: 'delete', value: 4 },
+//   { type: 'insert', value: 3 },
+//   { type: 'nop', value: 2 },
+//   { type: 'nop', value: 1 }
+// ]
+
+// Comparing strings
+const strDiff = diff('abc', 'abd');
+console.log(strDiff);
+// [
+//   { type: 'delete', value: 'd' },
+//   { type: 'insert', value: 'c' },
+//   { type: 'nop', value: 'b' },
+//   { type: 'nop', value: 'a' }
+// ]
+
+// Equal values return empty array
+console.log(diff('same', 'same'));
+// []
+```
+
 ## `util.format(format[, ...args])`
 
 <!-- YAML
@@ -3622,6 +3672,7 @@ util.isArray({});
 [`napi_create_external()`]: n-api.md#napi_create_external
 [`target` and `handler`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy#Terminology
 [`tty.hasColors()`]: tty.md#writestreamhascolorscount-env
+[`util.diff()`]: #utildiffactual-expected
 [`util.format()`]: #utilformatformat-args
 [`util.inspect()`]: #utilinspectobject-options
 [`util.promisify()`]: #utilpromisifyoriginal

lib/internal/assert/assertion_error.js

@@ -108,7 +108,7 @@ function getColoredMyersDiff(actual, expected) {
   const header = `${colors.green}actual${colors.white} ${colors.red}expected${colors.white}`;
   const skipped = false;
 
-  const diff = myersDiff(StringPrototypeSplit(actual, ''), StringPrototypeSplit(expected, ''));
+  const diff = myersDiff(StringPrototypeSplit(actual, ''), StringPrototypeSplit(expected, ''), true);
   let message = printSimpleMyersDiff(diff);
 
   if (skipped) {

lib/internal/assert/consts.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const kReadableOperator = {
+  deepStrictEqual: 'Expected values to be strictly deep-equal:',
+  partialDeepStrictEqual: 'Expected values to be partially and strictly deep-equal:',
+  strictEqual: 'Expected values to be strictly equal:',
+  strictEqualObject: 'Expected "actual" to be reference-equal to "expected":',
+  deepEqual: 'Expected values to be loosely deep-equal:',
+  notDeepStrictEqual: 'Expected "actual" not to be strictly deep-equal to:',
+  notStrictEqual: 'Expected "actual" to be strictly unequal to:',
+  notStrictEqualObject:
+    'Expected "actual" not to be reference-equal to "expected":',
+  notDeepEqual: 'Expected "actual" not to be loosely deep-equal to:',
+  notIdentical: 'Values have same structure but are not reference-equal:',
+  notDeepEqualUnequal: 'Expected values not to be loosely deep-equal:',
+};
+
+module.exports = {
+  kReadableOperator,
+};

lib/internal/assert/myers_diff.js

@@ -20,7 +20,7 @@ function areLinesEqual(actual, expected, checkCommaDisparity) {
   return false;
 }
 
-function myersDiff(actual, expected, checkCommaDisparity = false) {
+function myersDiff(actual, expected, checkCommaDisparity = false, useNullPrototypes = true) {
   const actualLength = actual.length;
   const expectedLength = expected.length;
   const max = actualLength + expectedLength;
@@ -51,13 +51,13 @@ function myersDiff(actual, expected, checkCommaDisparity = false) {
       v[offset] = x;
 
       if (x >= actualLength && y >= expectedLength) {
-        return backtrack(trace, actual, expected, checkCommaDisparity);
+        return backtrack(trace, actual, expected, checkCommaDisparity, useNullPrototypes);
       }
     }
   }
 }
 
-function backtrack(trace, actual, expected, checkCommaDisparity) {
+function backtrack(trace, actual, expected, checkCommaDisparity, useNullPrototypes) {
   const actualLength = actual.length;
   const expectedLength = expected.length;
   const max = actualLength + expectedLength;
@@ -87,16 +87,22 @@ function backtrack(trace, actual, expected, checkCommaDisparity) {
     while (x > prevX && y > prevY) {
       const actualItem = actual[x - 1];
       const value = checkCommaDisparity && !StringPrototypeEndsWith(actualItem, ',') ? expected[y - 1] : actualItem;
-      ArrayPrototypePush(result, { __proto__: null, type: 'nop', value });
+      ArrayPrototypePush(result, useNullPrototypes ?
+        { __proto__: null, type: 'nop', value } :
+        { type: 'nop', value });
       x--;
       y--;
     }
 
     if (diffLevel > 0) {
       if (x > prevX) {
-        ArrayPrototypePush(result, { __proto__: null, type: 'insert', value: actual[--x] });
+        ArrayPrototypePush(result, useNullPrototypes ?
+          { __proto__: null, type: 'insert', value: actual[--x] } :
+          { type: 'insert', value: actual[--x] });
       } else {
-        ArrayPrototypePush(result, { __proto__: null, type: 'delete', value: expected[--y] });
+        ArrayPrototypePush(result, useNullPrototypes ?
+          { __proto__: null, type: 'delete', value: expected[--y] } :
+          { type: 'delete', value: expected[--y] });
       }
     }
   }

lib/internal/util/diff.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const { isDeepStrictEqual } = require('util');
+const { myersDiff } = require('internal/assert/myers_diff');
+
+/**
+ * Generate a difference report between two values
+ * @param {Array | string} actual - The first value to compare
+ * @param {Array | string} expected - The second value to compare
+ * @returns {Array} - An array of differences between the two values.
+ * The order of the elements in the array is reversed from the order in which
+ * the differences occurred.
+ * The array contains objects with the following properties:
+ * - type: 'delete', 'insert', or 'nop'
+ * - value: The value that was deleted, inserted, or unchanged
+ */
+function diff(actual, expected) {
+  if (isDeepStrictEqual(actual, expected)) {
+    return [];
+  }
+
+  return myersDiff(actual, expected, false, false);
+}
+
+module.exports = {
+  diff,
+};

lib/util.js

@@ -479,3 +479,9 @@ defineLazyProperties(
   'internal/mime',
   ['MIMEType', 'MIMEParams'],
 );
+
+defineLazyProperties(
+  module.exports,
+  'internal/util/diff',
+  ['diff'],
+);

test/parallel/test-diff.js

@@ -0,0 +1,99 @@
+'use strict';
+require('../common');
+
+const { describe, it } = require('node:test');
+const { deepStrictEqual } = require('node:assert');
+
+const { diff } = require('util');
+
+describe('diff', () => {
+  it('returns an empty array because actual and expected are the same', () => {
+    const actual = 'foo';
+    const expected = 'foo';
+
+    const result = diff(actual, expected);
+    deepStrictEqual(result, []);
+  });
+
+  it('returns the diff for strings', () => {
+    const actual = '12345678';
+    const expected = '12!!5!7!';
+    const result = diff(actual, expected);
+
+    deepStrictEqual(result, [
+      {
+        type: 'delete',
+        value: '!'
+      },
+      {
+        type: 'insert',
+        value: '8'
+      },
+      {
+        type: 'nop',
+        value: '7'
+      },
+      {
+        type: 'delete',
+        value: '!'
+      },
+      {
+        type: 'insert',
+        value: '6'
+      },
+      {
+        type: 'nop',
+        value: '5'
+      },
+      {
+        type: 'delete',
+        value: '!'
+      },
+      {
+        type: 'delete',
+        value: '!'
+      },
+      {
+        type: 'insert',
+        value: '4'
+      },
+      {
+        type: 'insert',
+        value: '3'
+      },
+      {
+        type: 'nop',
+        value: '2'
+      },
+      {
+        type: 'nop',
+        value: '1'
+      }]
+    );
+  });
+
+  it('returns the diff for arrays', () => {
+    const actual = [1, 2, 3];
+    const expected = [1, 3, 4];
+    const result = diff(actual, expected);
+
+    deepStrictEqual(result, [
+      {
+        type: 'delete',
+        value: 4
+      },
+      {
+        type: 'nop',
+        value: 3
+      },
+      {
+        type: 'insert',
+        value: 2
+      },
+      {
+        type: 'nop',
+        value: 1
+      }]
+    );
+  });
+});