BonneVoyager
diff --git a/‎README.md
Lines changed: 115 additions & 23 deletions b/‎README.md
Lines changed: 115 additions & 23 deletions
@@ -1,8 +1,8 @@
 # nested-objects-util
 
-A module to work with huge nested objects having circular references.
+A module to filter and diff huge nested objects having circular references.
 
-It was implemented to filter out some values from huge nested objects with circular references.
+It was implemented to filter out some values from huge nested objects with circular references and then diff them.
 
 It's designed to work both on nodejs and browser.
 
@@ -18,30 +18,44 @@ npm install --save nested-objects-util
 const nestedObjectsUtil = require('nested-objects-util');
 ```
 
-#### nestedObjectsUtil.flatten(Object: object): Object
+#### nestedObjectsUtil.flatten(Object: object, Boolean: sortKeysFlag = false): Object
 
 Flatten object by keys composed from own nested properties.
 
 ```
 nestedObjectsUtil.flatten({
   keyA: {
+    keyE: [ 'value3', 'value4' ],
+    keyF: null,
+    keyD: 'value2',
     keyB: {
       keyC: 'value'
-    },
-    keyD: 'value2'
-  },
-  keyE: [ 'value3', 'value4' ]
-})
+    }
+  }
+});
 ```
 
 returns:
 
+```js
+{
+  "keyA.keyE.0": "value3",
+  "keyA.keyE.1": "value4",
+  "keyA.keyF": null,
+  "keyA.keyD": "value2",
+  "keyA.keyB.keyC": "value"
+}
+```
+
+with sortKeys=true it would return:
+
 ```js
 {
   "keyA.keyB.keyC": "value",
   "keyA.keyD": "value2",
   "keyA.keyE.0": "value3",
-  "keyA.keyE.1": "value4"
+  "keyA.keyE.1": "value4",
+  "keyA.keyF": null
 }
 ```
 
@@ -74,7 +88,7 @@ returns:
 Access object's nested property.
 
 ```
-var nestedObject = {
+const nestedObject = {
   keyA: {
     keyB: {
       keyC: 'value'
@@ -90,12 +104,12 @@ returns:
 "value"
 ```
 
-#### nestedObjectsUtil.discardCircular(Object: object): Object
+#### nestedObjectsUtil.discardCircular(Object: object, Boolean: stringifyFlag = false): Object | String
 
 Discard circular references (to avoid "Converting circular structure to JSON" error).
 
 ```
-var a = {
+const a = {
   b: 1
 };
 a.c = a;
@@ -111,12 +125,12 @@ returns:
 }
 ```
 
-#### nestedObjectsUtil.filterValue(Object: object, Various: query, Boolean: flattenFlag = false): Object
+#### nestedObjectsUtil.filterValue(Object: object, Various | Array: query, Boolean: flattenFlag = false): Object
 
-Filter a nested object by value (with strict comparison performed).
+Filter a nested object by value or values (if array passed). Strict comparison is performed.
 
 ```
-var a = {
+const a = {
   b: {
     c: 'str',
     d: 'str2'
@@ -128,9 +142,10 @@ var a = {
       i: 'str3'
     },
     j: 'str4'
-  }
+  },
+  k: [ 'str', 'str5' ]
 };
-a.k = a.b;
+a.l = a.b;
 nestedObjectsUtil.filterValue(a, 'str');
 ```
 
@@ -146,11 +161,12 @@ returns:
     "g": {
       "h": "str"
     }
-  }
+  },
+  "k": [ "str" ]
 }
 ```
 
-or
+or with flattenFlag = true
 
 ```js
 nestedObjectsUtil.filterValue(a, 'str', true);
@@ -162,7 +178,8 @@ returns:
 {
   "b.c": "str",
   "e": "str",
-  "f.g.h": "str"
+  "f.g.h": "str",
+  "k.0": "str"
 }
 ```
 
@@ -173,7 +190,7 @@ On browser with HTML5 download API: stringify, format and download the object.
 Else: return stringified text. 
 
 ```
-var a = {
+const a = {
   b: 1,
   c: {
     d: 2,
@@ -182,7 +199,7 @@ var a = {
 };
 a.f = a;
 a.g = a.f;
-var obj = nestedObjectsUtil.discardCircular(a);
+const obj = nestedObjectsUtil.discardCircular(a);
 nestedObjectsUtil.downloadStringified(obj);
 ```
 
@@ -200,9 +217,84 @@ returns:
 }
 ```
 
+#### nestedObjectsUtil.areObjectsEqual(Object: objectA, Object: objectB): Boolean
+
+Compare two objects against each other (by JSON.stringify) after discarding circular references, flattening and ordering keys.
+
+```
+const objectA = {
+  keyA: {
+    keyB: {
+      keyC: 'value'
+    },
+    keyD: 'value2',
+    keyE: [ 'value3', 'value4' ]
+  }
+};
+objectA.circular = objectA;
+const objectB = {
+  keyA: {
+    keyE: [ 'value3', 'value4' ],
+    keyD: 'value2',
+    keyB: {
+      keyC: 'value'
+    }
+  }
+};
+objectB.circular = objectB;
+nestedObjectsUtil.areObjectsEqual(objectA, objectB);
+```
+
+returns:
+
+```js
+true
+```
+
+#### nestedObjectsUtil.getObjectsDiff(Object: objectA, Object: objectB, Boolean: sortKeysFlag = false, Boolean: flattenFlag = false): Object
+
+Get the properties which differ between object A and object B and return those from object B.
+
+```
+const objectA = {
+  keyA: {
+    keyB: {
+      keyC: 'value'
+    },
+    keyD: 'value2',
+    keyE: [ 'value3' ]
+  }
+};
+objectA.circular = objectA;
+const objectB = {
+  keyA: {
+    keyB: {
+      keyC: 'value'
+    },
+    keyD: 'value2_CHANGED',
+    keyE: [ 'value3_CHANGED' ]
+  }
+};
+objectB.circular = objectB;
+nestedObjectsUtil.getObjectsDiff(objectA, objectB);
+```
+
+returns:
+
+```js
+{
+  "keyA": {
+    "keyD": "value2_CHANGED",
+    "keyE": [ "value3_CHANGED" ]
+  }
+}
+```
+
 ## Example browser usage
 
-Filter out 'abcd' value from the flattened object and download stringified json via HTML5 API with:
+In the browser, NestedObjectsUtil object should be exposed to either window or with AMD.
+
+Filter out 'abcd' value from the flattened object and download stringified JSON via HTML5 API with:
 
 ```js
 const object = NestedObjectsUtil.filterValue(App.SomeHugeObject, 'abcd', true);