Fix diffAtom nested identity path notation (#392) (#401)

* Fix diffAtom nested identity path using bracket instead of dot notation (#392)

walkChanges was not passing embeddedKeyIsPath to buildCanonicalFilterPath,
so function-based identity keys returning nested paths like positionNumber.value
produced @['positionNumber.value'] instead of @.positionNumber.value.

* Address review: fix findElementByKey for nested paths, fix null fallback

- findElementByKey now resolves nested paths via resolveNestedKey helper
- Use undefined-only check instead of ?? to preserve null identity values

* Fix null identity matching, string-based nested keys, add comprehensive tests

- indexOfItemInArray/applyArrayChange: use !== undefined instead of != null
  so null identity values can match (null is a valid filter value)
- compareArray/convertArrayToObj: support string-based nested identity keys
  (e.g. embeddedObjKeys: { items: 'positionNumber.value' }) by checking
  whether data has literal property or needs nested resolution
- Add 8 new tests: full round-trip (diffAtom→applyAtom→revertAtom), string
  key, 3-level nesting, numeric/boolean/null identity values, toAtom bridge

* Sync package-lock.json version to 5.0.0-alpha.8

* Guard in operator against primitives, fix comment accuracy

Author: ltwlf

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "json-diff-ts",
-  "version": "5.0.0-alpha.7",
+  "version": "5.0.0-alpha.8",
   "description": "Modern TypeScript JSON diff library - Zero dependencies, high performance, ESM + CommonJS support. Calculate and apply differences between JSON objects with advanced features like key-based array diffing, JSONPath support, and atomic changesets.",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

package.json

@@ -220,7 +220,8 @@ function walkChanges(
             childChange.key,
             childOld,
             childNew,
-            childChange
+            childChange,
+            change.embeddedKeyIsPath
           );
 
           if (childChange.changes) {
@@ -283,7 +284,8 @@ function buildCanonicalFilterPath(
   changeKey: string,
   oldArr: any[],
   newArr: any[],
-  change: IChange
+  change: IChange,
+  embeddedKeyIsPath?: boolean
 ): string {
   if (embeddedKey === '$index') {
     return `${basePath}[${changeKey}]`;
@@ -309,9 +311,11 @@ function buildCanonicalFilterPath(
   }
 
   // Named string key
-  const element = findElementByKey(oldArr, newArr, embeddedKey, changeKey, change.type);
-  const typedVal = element ? element[embeddedKey] : changeKey;
-  const memberAccess = SIMPLE_PROPERTY_RE.test(embeddedKey) ? `.${embeddedKey}` : `['${embeddedKey.replace(/'/g, "''")}']`;
+  const isNestedPath = embeddedKeyIsPath && NESTED_PATH_RE.test(embeddedKey);
+  const element = findElementByKey(oldArr, newArr, embeddedKey, changeKey, change.type, isNestedPath);
+  const resolved = element !== undefined ? resolveNestedKey(element, embeddedKey, !!isNestedPath) : undefined;
+  const typedVal = resolved !== undefined ? resolved : changeKey;
+  const memberAccess = SIMPLE_PROPERTY_RE.test(embeddedKey) || isNestedPath ? `.${embeddedKey}` : `['${embeddedKey.replace(/'/g, "''")}']`;
   return `${basePath}[?(@${memberAccess}==${formatFilterLiteral(typedVal)})]`;
 }
 
@@ -360,20 +364,29 @@ function findElement(arr: any[], embeddedKey: string | FunctionKey, changeKey: s
   return arr.find((item) => item && String(item[embeddedKey]) === changeKey);
 }
 
+function resolveNestedKey(item: any, key: string, isPath: boolean): any {
+  if (isPath) {
+    return key.split('.').reduce((c: any, s: string) => c?.[s], item);
+  }
+  return item?.[key];
+}
+
 function findElementByKey(
   oldArr: any[],
   newArr: any[],
   embeddedKey: string,
   changeKey: string,
-  opType: Operation
+  opType: Operation,
+  isPath?: boolean
 ): any {
+  const match = (item: any) => item && String(resolveNestedKey(item, embeddedKey, !!isPath)) === changeKey;
   // For REMOVE ops, element is in old array. For ADD, in new. For UPDATE, prefer old.
   if (opType === Operation.REMOVE || opType === Operation.UPDATE) {
-    const el = oldArr?.find((item) => item && String(item[embeddedKey]) === changeKey);
+    const el = oldArr?.find(match);
     if (el) return el;
   }
   if (opType === Operation.ADD || opType === Operation.UPDATE) {
-    const el = newArr?.find((item) => item && String(item[embeddedKey]) === changeKey);
+    const el = newArr?.find(match);
     if (el) return el;
   }
   return undefined;

src/jsonAtom.ts

@@ -576,12 +576,18 @@ const compareArray = (oldObj: any, newObj: any, path: any, keyPath: any, options
   const isFunctionKey = typeof uniqKey === 'function' && uniqKey.length === 2;
   if (diffs.length) {
     const resolvedKey = isFunctionKey ? uniqKey(newObj[0] ?? oldObj[0], true) : uniqKey;
+    // Nested path when resolvedKey contains '.' and matches NESTED_PATH_RE.
+    // Function keys qualify directly; string keys qualify only if the sample
+    // element does not expose resolvedKey as a literal property.
+    const sampleEl = newObj[0] ?? oldObj[0];
+    const isNestedPath = typeof resolvedKey === 'string' && resolvedKey.includes('.') && NESTED_PATH_RE.test(resolvedKey)
+      && (isFunctionKey || !(sampleEl != null && typeof sampleEl === 'object' && resolvedKey in sampleEl));
     return [
       {
         type: Operation.UPDATE,
         key: getKey(path),
         embeddedKey: resolvedKey,
-        ...(isFunctionKey && typeof resolvedKey === 'string' && NESTED_PATH_RE.test(resolvedKey) && resolvedKey.includes('.') ? { embeddedKeyIsPath: true } : {}),
+        ...(isNestedPath ? { embeddedKeyIsPath: true } : {}),
         changes: diffs
       }
     ];
@@ -626,8 +632,12 @@ const convertArrayToObj = (arr: any[], uniqKey: any) => {
       obj[i] = value;
     }
   } else {
-    // Convert string keys to functions for compatibility with es-toolkit keyBy
-    const keyFunction = typeof uniqKey === 'string' ? (item: any) => item[uniqKey] : uniqKey;
+    const maybeNestedPath = typeof uniqKey === 'string' && uniqKey.includes('.') && NESTED_PATH_RE.test(uniqKey);
+    const keyFunction = typeof uniqKey === 'string'
+      ? (maybeNestedPath
+          ? (item: any) => (item != null && typeof item === 'object' && uniqKey in item) ? item[uniqKey] : resolveProperty(item, uniqKey, true)
+          : (item: any) => item[uniqKey])
+      : uniqKey;
     obj = keyBy(arr, keyFunction);
   }
   return obj;
@@ -680,7 +690,7 @@ const indexOfItemInArray = (arr: any[], key: any, value: any, isPath?: boolean)
     const item = arr[i];
     if (item == null) continue;
     const resolved = resolveProperty(item, key, isPath);
-    if (resolved != null && String(resolved) === String(value)) {
+    if (resolved !== undefined && String(resolved) === String(value)) {
       return i;
     }
   }
@@ -755,7 +765,7 @@ const applyArrayChange = (arr: any[], change: any) => {
       } else {
         element = arr.find((el) => {
           const resolved = resolveProperty(el, change.embeddedKey, change.embeddedKeyIsPath);
-          return resolved != null && String(resolved) === String(subchange.key);
+          return resolved !== undefined && String(resolved) === String(subchange.key);
         });
       }
       if (element) {
@@ -845,7 +855,7 @@ const revertArrayChange = (arr: any[], change: any) => {
       } else {
         element = arr.find((el) => {
           const resolved = resolveProperty(el, change.embeddedKey, change.embeddedKeyIsPath);
-          return resolved != null && String(resolved) === String(subchange.key);
+          return resolved !== undefined && String(resolved) === String(subchange.key);
         });
       }
       if (element) {