fet: add compare-key method for array diffing (#50)

* feat: compare by matching sent key

* fix: compare array of non object elements correction in compare by key method

* fix: array bracket utils created to prevent code duplication

* fix: improved recursive comparison on compare key method

---------

Co-authored-by: utku.akyuz <utku.akyuz@ekinokssoftware.com>

Author: utkuakyuz

playground/docs.tsx

@@ -26,6 +26,7 @@ const Docs: React.FC<PropTypes> = props => {
   const [ignoreCase, setIgnoreCase] = React.useState(false);
   const [recursiveEqual, setRecursiveEqual] = React.useState(true);
   const [preserveKeyOrder, setPreserveKeyOrder] = React.useState<DifferOptions['preserveKeyOrder']>(undefined);
+  const [compareKey, setCompareKey] = React.useState<string>('');
 
   // viewer props
   const [indent, setIndent] = React.useState(4);
@@ -44,6 +45,7 @@ const Docs: React.FC<PropTypes> = props => {
     ignoreCase,
     recursiveEqual,
     preserveKeyOrder,
+    compareKey
   }), [
     detectCircular,
     maxDepth,
@@ -52,6 +54,7 @@ const Docs: React.FC<PropTypes> = props => {
     ignoreCase,
     recursiveEqual,
     preserveKeyOrder,
+    compareKey,
   ]);
   const differ = React.useMemo(() => new Differ(differOptions), [differOptions]);
 
@@ -231,9 +234,10 @@ const Docs: React.FC<PropTypes> = props => {
               <option value="lcs">lcs</option>
               <option value="unorder-normal">unorder-normal</option>
               <option value="unorder-lcs">unorder-lcs</option>
+              <option value="compare-key">compare-key</option>
             </select>
           </label>
-          <blockquote>The way to diff arrays, default is <code>"normal"</code>, using <code>"lcs"</code> may get a better result but much slower. <code>"unorder-normal"</code> and <code>"unorder-lcs"</code> are for unordered arrays (the order of elements in the array doesn't matter).</blockquote>
+          <blockquote>The way to diff arrays, default is <code>"normal"</code>, using <code>"lcs"</code> may get a better result but much slower. <code>"unorder-normal"</code> and <code>"unorder-lcs"</code> are for unordered arrays (the order of elements in the array doesn't matter). <code>"compare-key"</code> matches objects by a specific key property.</blockquote>
           <label htmlFor="ignore-case">
             Ignore case:
             <input

playground/playground.tsx

@@ -28,6 +28,7 @@ const Playground: React.FC<PlaygroundProps> = props => {
   const [ignoreCaseForKey, setIgnoreCaseForKey] = React.useState(false);
   const [recursiveEqual, setRecursiveEqual] = React.useState(true);
   const [preserveKeyOrder, setPreserveKeyOrder] = React.useState<DifferOptions['preserveKeyOrder']>(undefined);
+  const [compareKey, setCompareKey] = React.useState<string>('');
 
   // viewer props
   const [indent, setIndent] = React.useState(4);
@@ -47,6 +48,7 @@ const Playground: React.FC<PlaygroundProps> = props => {
     ignoreCaseForKey,
     recursiveEqual,
     preserveKeyOrder,
+    compareKey: compareKey || undefined,
   }), [
     detectCircular,
     maxDepth,
@@ -56,6 +58,7 @@ const Playground: React.FC<PlaygroundProps> = props => {
     ignoreCaseForKey,
     recursiveEqual,
     preserveKeyOrder,
+    compareKey,
   ]);
   const differ = React.useMemo(() => new Differ(differOptions), [differOptions]);
   const [diff, setDiff] = React.useState(differ.diff('', ''));
@@ -251,7 +254,7 @@ return (
                 title="Array diff method"
                 tip={
                   <>
-                    The way to diff arrays, default is <code>"normal"</code>, using <code>"lcs"</code> may get a better result but much slower. <code>"unorder-normal"</code> and <code>"unorder-lcs"</code> are for unordered arrays (the order of elements in the array doesn't matter).
+                    The way to diff arrays, default is <code>"normal"</code>, using <code>"lcs"</code> may get a better result but much slower. <code>"unorder-normal"</code> and <code>"unorder-lcs"</code> are for unordered arrays (the order of elements in the array doesn't matter). <code>"compare-key"</code> matches objects by a specific key property.
                   </>
                 }
               />
@@ -264,8 +267,24 @@ return (
                 <option value="lcs">lcs</option>
                 <option value="unorder-normal">unorder-normal</option>
                 <option value="unorder-lcs">unorder-lcs</option>
+                <option value="compare-key">compare-key</option>
               </select>
             </label>
+            {arrayDiffMethod === 'compare-key' && (
+              <label htmlFor="compare-key">
+                <Label
+                  title="Compare key"
+                  tip="The key to use for matching objects in arrays. Objects with the same value for this key will be matched and compared, regardless of their position in the array."
+                />
+                <input
+                  type="text"
+                  id="compare-key"
+                  value={compareKey}
+                  onChange={e => setCompareKey(e.target.value)}
+                  placeholder="e.g., oid, userId, id"
+                />
+              </label>
+            )}
             <label htmlFor="ignore-case">
               <Label
                 title="Ignore case"

src/differ.ts

@@ -3,6 +3,7 @@ import concat from './utils/concat';
 import detectCircular from './utils/detect-circular';
 import diffArrayLCS from './utils/diff-array-lcs';
 import diffArrayNormal from './utils/diff-array-normal';
+import diffArrayCompareKey from './utils/diff-array-compare-key';
 import diffObject from './utils/diff-object';
 import getType from './utils/get-type';
 import sortInnerArrays from './utils/sort-inner-arrays';
@@ -81,8 +82,26 @@ export interface DifferOptions {
    *   3 3
    * +   4
    * ```
+   *
+   * When using `compare-key`, the differ will match objects in arrays by a specific key
+   * property (specified by `compareKey` option). This is useful when comparing arrays of
+   * objects where the order doesn't matter but you want to match related objects.
+   * The output will be:
+   *
+   * ```diff
+   *   a b
+   *   1 1
+   * - 2
+   * +   3
+   *   4 4
+   * ```
    */
-  arrayDiffMethod?: 'normal' | 'lcs' | 'unorder-normal' | 'unorder-lcs';
+  arrayDiffMethod?:
+    | 'normal'
+    | 'lcs'
+    | 'unorder-normal'
+    | 'unorder-lcs'
+    | 'compare-key';
   /**
    * Whether to ignore the case when comparing strings, default `false`.
    */
@@ -116,6 +135,12 @@ export interface DifferOptions {
    * ("before" or "after"). Otherwise, differ will sort the keys of results.
    */
   preserveKeyOrder?: 'before' | 'after';
+  /**
+   * The key to use for matching objects in arrays when using `compare-key` array diff method.
+   * Objects with the same value for this key will be matched and compared, regardless of their
+   * position in the array.
+   */
+  compareKey?: string;
   /**
    * The behavior when encountering values that are not part of the JSON spec, e.g. `undefined`, `NaN`, `Infinity`, `123n`, `() => alert(1)`, `Symbol.iterator`.
    *
@@ -169,6 +194,7 @@ class Differ {
     ignoreCaseForKey = false,
     recursiveEqual = false,
     preserveKeyOrder,
+    compareKey,
     undefinedBehavior = UndefinedBehavior.stringify,
   }: DifferOptions = {}) {
     this.options = {
@@ -180,11 +206,17 @@ class Differ {
       ignoreCaseForKey,
       recursiveEqual,
       preserveKeyOrder,
+      compareKey,
       undefinedBehavior,
     };
-    this.arrayDiffFunc = arrayDiffMethod === 'lcs' || arrayDiffMethod === 'unorder-lcs'
-      ? diffArrayLCS
-      : diffArrayNormal;
+
+    if (arrayDiffMethod === 'compare-key') {
+      this.arrayDiffFunc = diffArrayCompareKey;
+    } else if (arrayDiffMethod === 'lcs' || arrayDiffMethod === 'unorder-lcs') {
+      this.arrayDiffFunc = diffArrayLCS;
+    } else {
+      this.arrayDiffFunc = diffArrayNormal;
+    }
   }
 
   private detectCircular(source: any) {

src/utils/array-bracket-utils.ts

@@ -0,0 +1,36 @@
+import type { DiffResult } from '../differ';
+
+// Shared utility for array diff
+export const addArrayOpeningBrackets = (
+  linesLeft: DiffResult[],
+  linesRight: DiffResult[],
+  keyLeft: string,
+  keyRight: string,
+  level: number
+) => {
+  if (keyLeft && keyRight) {
+    linesLeft.push({ level, type: 'equal', text: `"${keyLeft}": [` });
+    linesRight.push({ level, type: 'equal', text: `"${keyRight}": [` });
+  } else {
+    linesLeft.push({ level, type: 'equal', text: '[' });
+    linesRight.push({ level, type: 'equal', text: '[' });
+  }
+};
+
+export const addArrayClosingBrackets = (
+  linesLeft: DiffResult[],
+  linesRight: DiffResult[],
+  level: number
+) => {
+  linesLeft.push({ level, type: 'equal', text: ']' });
+  linesRight.push({ level, type: 'equal', text: ']' });
+};
+
+export const addMaxDepthPlaceholder = (
+  linesLeft: DiffResult[],
+  linesRight: DiffResult[],
+  level: number
+) => {
+  linesLeft.push({ level: level + 1, type: 'equal', text: '...' });
+  linesRight.push({ level: level + 1, type: 'equal', text: '...' });
+};