feat(compare): ignore paths using a path matcher when comparing documents

README.md

@@ -258,17 +258,18 @@ Destroys the observer set up on `document`.
 
 Any remaining changes are delivered synchronously (as in `jsonpatch.generate`). Note: this is different that ES6/7 `Object.unobserve`, which delivers remaining changes asynchronously.
 
-#### `jsonpatch.compare(document1, document2, invertible)`
+#### `jsonpatch.compare(document1, document2, invertible, ignorePath)`
 
 ```typescript
-jsonpatch.compare(document1: Jsonable, document2: Jsonable, invertible = false): Operation[]
+jsonpatch.compare(document1: Jsonable, document2: Jsonable, invertible = false, ignorePath?: PathMatcher): Operation[]
 
 type JsonableObj = { [key:string]: Jsonable };
 type JsonableArr = Jsonable[];
 type Jsonable = JsonableArr | JsonableObj | string | number | boolean | null;
+type PathMatcher = string | RegExp | ((path: string) => boolean);
 ```
 
-Compares object trees `document1` and `document2` and returns the difference relative to `document1` as a patches array.  If `invertible` is true, then each change will be preceded by a test operation of the value in `document1`.
+Compares object trees `document1` and `document2` and returns the difference relative to `document1` as a patches array.  If `invertible` is true, then each change will be preceded by a test operation of the value in `document1`. The `ignorePath` param can be provided to ignore comparisons along certain paths in `document1`. If `ignorePath` is provided as a function, it should return `true` to ignore the given path.
 
 If there are no differences, returns an empty array (length 0).
 

commonjs/duplex.js

@@ -114,7 +114,7 @@ function generate(observer, invertible) {
 }
 exports.generate = generate;
 // Dirty check if obj is different from mirror, generate patches and update mirror
-function _generate(mirror, obj, patches, path, invertible) {
+function _generate(mirror, obj, patches, path, invertible, ignorePath) {
     if (obj === mirror) {
         return;
     }
@@ -129,10 +129,13 @@ function _generate(mirror, obj, patches, path, invertible) {
     for (var t = oldKeys.length - 1; t >= 0; t--) {
         var key = oldKeys[t];
         var oldVal = mirror[key];
+        if (ignorePath != null && _applyPathMatcher(ignorePath, path + "/" + helpers_js_1.escapePathComponent(key))) {
+            continue;
+        }
         if (helpers_js_1.hasOwnProperty(obj, key) && !(obj[key] === undefined && oldVal !== undefined && Array.isArray(obj) === false)) {
             var newVal = obj[key];
             if (typeof oldVal == "object" && oldVal != null && typeof newVal == "object" && newVal != null && Array.isArray(oldVal) === Array.isArray(newVal)) {
-                _generate(oldVal, newVal, patches, path + "/" + helpers_js_1.escapePathComponent(key), invertible);
+                _generate(oldVal, newVal, patches, path + "/" + helpers_js_1.escapePathComponent(key), invertible, ignorePath);
             }
             else {
                 if (oldVal !== newVal) {
@@ -169,13 +172,25 @@ function _generate(mirror, obj, patches, path, invertible) {
         }
     }
 }
+// applies path matcher to path and returns result
+function _applyPathMatcher(pathMatcher, path) {
+    if (typeof pathMatcher === "string") {
+        return pathMatcher === path;
+    }
+    else if (typeof pathMatcher === 'object') {
+        return pathMatcher.test(path);
+    }
+    else {
+        return pathMatcher(path);
+    }
+}
 /**
  * Create an array of patches from the differences in two objects
  */
-function compare(tree1, tree2, invertible) {
+function compare(tree1, tree2, invertible, ignorePath) {
     if (invertible === void 0) { invertible = false; }
     var patches = [];
-    _generate(tree1, tree2, patches, '', invertible);
+    _generate(tree1, tree2, patches, '', invertible, ignorePath);
     return patches;
 }
 exports.compare = compare;

module/duplex.d.ts

@@ -5,6 +5,7 @@ export interface Observer<T> {
     unobserve: () => void;
     callback: (patches: Operation[]) => void;
 }
+export declare type PathMatcher = string | RegExp | ((path: string) => boolean);
 /**
  * Detach an observer from an object
  */
@@ -20,4 +21,4 @@ export declare function generate<T>(observer: Observer<Object>, invertible?: boo
 /**
  * Create an array of patches from the differences in two objects
  */
-export declare function compare(tree1: Object | Array<any>, tree2: Object | Array<any>, invertible?: boolean): Operation[];
+export declare function compare(tree1: Object | Array<any>, tree2: Object | Array<any>, invertible?: boolean, ignorePath?: PathMatcher): Operation[];

module/duplex.mjs

@@ -110,7 +110,7 @@ export function generate(observer, invertible) {
     return temp;
 }
 // Dirty check if obj is different from mirror, generate patches and update mirror
-function _generate(mirror, obj, patches, path, invertible) {
+function _generate(mirror, obj, patches, path, invertible, ignorePath) {
     if (obj === mirror) {
         return;
     }
@@ -125,10 +125,13 @@ function _generate(mirror, obj, patches, path, invertible) {
     for (var t = oldKeys.length - 1; t >= 0; t--) {
         var key = oldKeys[t];
         var oldVal = mirror[key];
+        if (ignorePath != null && _applyPathMatcher(ignorePath, path + "/" + escapePathComponent(key))) {
+            continue;
+        }
         if (hasOwnProperty(obj, key) && !(obj[key] === undefined && oldVal !== undefined && Array.isArray(obj) === false)) {
             var newVal = obj[key];
             if (typeof oldVal == "object" && oldVal != null && typeof newVal == "object" && newVal != null && Array.isArray(oldVal) === Array.isArray(newVal)) {
-                _generate(oldVal, newVal, patches, path + "/" + escapePathComponent(key), invertible);
+                _generate(oldVal, newVal, patches, path + "/" + escapePathComponent(key), invertible, ignorePath);
             }
             else {
                 if (oldVal !== newVal) {
@@ -165,12 +168,24 @@ function _generate(mirror, obj, patches, path, invertible) {
         }
     }
 }
+// applies path matcher to path and returns result
+function _applyPathMatcher(pathMatcher, path) {
+    if (typeof pathMatcher === "string") {
+        return pathMatcher === path;
+    }
+    else if (typeof pathMatcher === 'object') {
+        return pathMatcher.test(path);
+    }
+    else {
+        return pathMatcher(path);
+    }
+}
 /**
  * Create an array of patches from the differences in two objects
  */
-export function compare(tree1, tree2, invertible) {
+export function compare(tree1, tree2, invertible, ignorePath) {
     if (invertible === void 0) { invertible = false; }
     var patches = [];
-    _generate(tree1, tree2, patches, '', invertible);
+    _generate(tree1, tree2, patches, '', invertible, ignorePath);
     return patches;
 }