@@ -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);