util: expose diff function used by the assertion errors

fix: #51740

Author: puskin

doc/api/util.md

@@ -325,6 +325,60 @@ 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` {any}
+* `expected` {any}
+* Returns: {string | null} A string or `null` if there is difference
+  between `actual` and `expected`
+
+[`util.diff()`][] is a utility function that compares two values and returns a
+string that represents the difference between them. It is useful for debugging
+and testing.
+The output is exactly the same as the one used by all the assertion errors, therefore
+it is internally using the Myer's diff algorithm to compute the differences.
+
+```js
+const { diff } = require('node:util');
+
+console.log(diff({ a: 1, b: 2 }, { a: 1, b: 3 }));
+// above will log:
+/*
++ actual - expected
+
+  {
+    a: 1,
++   b: 2
+-   b: 3
+  }
+*/
+
+// if the sum of the strings length is less than 12 characters, a short diff will be returned
+console.log(diff('foo', 'bar'));
+// above will log:
+/*
+'foo' !== 'bar'
+*/
+
+// if the string comparison is too long and the first difference is after the second character
+// the diff will also indicate with the ^ character where the difference is.
+// this is only happening when the terminal you are using does not support colors;
+// if the terminal supports colors, the diff will be colored and the ^ character will not be used.
+console.log(diff('123456789ABCDEFGHI', '12!!5!7!9!BC!!!GHI'));
+// above will log:
+/*
++ actual - expected
+
++ '123456789ABCDEFGHI'
+- '12!!5!7!9!BC!!!GHI'
+     ^
+*/
+```
+
 ## `util.format(format[, ...args])`
 
 <!-- YAML
@@ -3622,6 +3676,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

@@ -3,43 +3,29 @@
 const {
   ArrayPrototypeJoin,
   ArrayPrototypePop,
-  ArrayPrototypeSlice,
   Error,
   ErrorCaptureStackTrace,
   ObjectAssign,
   ObjectDefineProperty,
   ObjectGetPrototypeOf,
   ObjectPrototypeHasOwnProperty,
   String,
-  StringPrototypeRepeat,
   StringPrototypeSlice,
   StringPrototypeSplit,
 } = primordials;
 
 const { isError } = require('internal/util');
+const { diff } = require('util');
 
 const { inspect } = require('internal/util/inspect');
 const colors = require('internal/util/colors');
+const {
+  inspectValue,
+} = require('internal/util/diff');
 const { validateObject } = require('internal/validators');
 const { isErrorStackTraceLimitWritable } = require('internal/errors');
-const { myersDiff, printMyersDiff, printSimpleMyersDiff } = require('internal/assert/myers_diff');
-
-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:',
-};
+const { kReadableOperator } = require('internal/assert/consts');
 
-const kMaxShortStringLength = 12;
 const kMaxLongStringLength = 512;
 
 const kMethodsWithCustomMessageDiff = ['deepStrictEqual', 'strictEqual', 'partialDeepStrictEqual'];
@@ -65,28 +51,6 @@ function copyError(source) {
   return target;
 }
 
-function inspectValue(val) {
-  // The util.inspect default values could be changed. This makes sure the
-  // error messages contain the necessary information nevertheless.
-  return inspect(val, {
-    compact: false,
-    customInspect: false,
-    depth: 1000,
-    maxArrayLength: Infinity,
-    // Assert compares only enumerable properties (with a few exceptions).
-    showHidden: false,
-    // Assert does not detect proxies currently.
-    showProxy: false,
-    sorted: true,
-    // Inspect getters as we also check them when comparing entries.
-    getters: true,
-  });
-}
-
-function getErrorMessage(operator, message) {
-  return message || kReadableOperator[operator];
-}
-
 function checkOperator(actual, expected, operator) {
   // In case both values are objects or functions explicitly mark them as not
   // reference equal for the `strictEqual` operator.
@@ -104,131 +68,10 @@ function checkOperator(actual, expected, operator) {
   return operator;
 }
 
-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, ''));
-  let message = printSimpleMyersDiff(diff);
-
-  if (skipped) {
-    message += '...';
-  }
-
-  return { message, header, skipped };
-}
-
-function getStackedDiff(actual, expected) {
-  const isStringComparison = typeof actual === 'string' && typeof expected === 'string';
-
-  let message = `\n${colors.green}+${colors.white} ${actual}\n${colors.red}- ${colors.white}${expected}`;
-  const stringsLen = actual.length + expected.length;
-  const maxTerminalLength = process.stderr.isTTY ? process.stderr.columns : 80;
-  const showIndicator = isStringComparison && (stringsLen <= maxTerminalLength);
-
-  if (showIndicator) {
-    let indicatorIdx = -1;
-
-    for (let i = 0; i < actual.length; i++) {
-      if (actual[i] !== expected[i]) {
-        // Skip the indicator for the first 2 characters because the diff is immediately apparent
-        // It is 3 instead of 2 to account for the quotes
-        if (i >= 3) {
-          indicatorIdx = i;
-        }
-        break;
-      }
-    }
-
-    if (indicatorIdx !== -1) {
-      message += `\n${StringPrototypeRepeat(' ', indicatorIdx + 2)}^`;
-    }
-  }
-
-  return { message };
-}
-
-function getSimpleDiff(originalActual, actual, originalExpected, expected) {
-  let stringsLen = actual.length + expected.length;
-  // Accounting for the quotes wrapping strings
-  if (typeof originalActual === 'string') {
-    stringsLen -= 2;
-  }
-  if (typeof originalExpected === 'string') {
-    stringsLen -= 2;
-  }
-  if (stringsLen <= kMaxShortStringLength && (originalActual !== 0 || originalExpected !== 0)) {
-    return { message: `${actual} !== ${expected}`, header: '' };
-  }
-
-  const isStringComparison = typeof originalActual === 'string' && typeof originalExpected === 'string';
-  // colored myers diff
-  if (isStringComparison && colors.hasColors) {
-    return getColoredMyersDiff(actual, expected);
-  }
-
-  return getStackedDiff(actual, expected);
-}
-
-function isSimpleDiff(actual, inspectedActual, expected, inspectedExpected) {
-  if (inspectedActual.length > 1 || inspectedExpected.length > 1) {
-    return false;
-  }
-
-  return typeof actual !== 'object' || actual === null || typeof expected !== 'object' || expected === null;
-}
-
 function createErrDiff(actual, expected, operator, customMessage) {
   operator = checkOperator(actual, expected, operator);
 
-  let skipped = false;
-  let message = '';
-  const inspectedActual = inspectValue(actual);
-  const inspectedExpected = inspectValue(expected);
-  const inspectedSplitActual = StringPrototypeSplit(inspectedActual, '\n');
-  const inspectedSplitExpected = StringPrototypeSplit(inspectedExpected, '\n');
-  const showSimpleDiff = isSimpleDiff(actual, inspectedSplitActual, expected, inspectedSplitExpected);
-  let header = `${colors.green}+ actual${colors.white} ${colors.red}- expected${colors.white}`;
-
-  if (showSimpleDiff) {
-    const simpleDiff = getSimpleDiff(actual, inspectedSplitActual[0], expected, inspectedSplitExpected[0]);
-    message = simpleDiff.message;
-    if (typeof simpleDiff.header !== 'undefined') {
-      header = simpleDiff.header;
-    }
-    if (simpleDiff.skipped) {
-      skipped = true;
-    }
-  } else if (inspectedActual === inspectedExpected) {
-    // Handles the case where the objects are structurally the same but different references
-    operator = 'notIdentical';
-    if (inspectedSplitActual.length > 50) {
-      message = `${ArrayPrototypeJoin(ArrayPrototypeSlice(inspectedSplitActual, 0, 50), '\n')}\n...}`;
-      skipped = true;
-    } else {
-      message = ArrayPrototypeJoin(inspectedSplitActual, '\n');
-    }
-    header = '';
-  } else {
-    const checkCommaDisparity = actual != null && typeof actual === 'object';
-    const diff = myersDiff(inspectedSplitActual, inspectedSplitExpected, checkCommaDisparity);
-
-    const myersDiffMessage = printMyersDiff(diff, operator);
-    message = myersDiffMessage.message;
-
-    if (operator === 'partialDeepStrictEqual') {
-      header = `${colors.gray}${colors.hasColors ? '' : '+ '}actual${colors.white} ${colors.red}- expected${colors.white}`;
-    }
-
-    if (myersDiffMessage.skipped) {
-      skipped = true;
-    }
-  }
-
-  const headerMessage = `${getErrorMessage(operator, customMessage)}\n${header}`;
-  const skippedMessage = skipped ? '\n... Skipped lines' : '';
-
-  return `${headerMessage}${skippedMessage}\n${message}\n`;
+  return diff(actual, expected, operator, customMessage);
 }
 
 function addEllipsis(string) {

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,
+};