fix: readme

README.md

@@ -1,37 +1,65 @@
-# DATA DIFF
+# SUPERDIFF
 
 This library compares two arrays or objects and return a complete diff of their differences.
 
-## Object exemple:
+## WHY YOU SHOULD USE THIS LIB
 
-`getObjectDiff()` checks base properties but also provides a complete diff of nested properties.
+All other existing solutions return a weird diff format which often require an additionnal parsing. They are also limited to object comparison. Some even have CPU spikes issues. 👎
 
-Input
+**Superdiff** gives you a complete diff for both array <u>and</u> objects with a very readable format. Last but not least, it's battled tested. Import. Enjoy. 👍
+
+## DIFF FORMAT COMPARISON
+
+Let's compare the diff format of **Superdiff** and **Deep-diff**, the most popular diff lib on npm:
+
+input:
 
 ```diff
-getObjectDiff(
-  {
-    id: 54,
-    user: {
-      name: "joe",
--     member: true,
--     hobbies: ["golf", "football"],
-      age: 66,
-    },
-  },
-  {
-    id: 54,
-    user: {
-      name: "joe",
-+     member: false,
-+     hobbies: ["golf", "chess"],
-      age: 66,
-    },
+const objectA = {
+          id: 54,
+          user: {
+            name: "joe",
+-           member: true,
+-           hobbies: ["golf", "football"],
+            age: 66,
+         },
+  }
+
+const objectB = {
+        id: 54,
+        user: {
+            name: "joe",
++           member: false,
++           hobbies: ["golf", "chess"],
+            age: 66,
+        },
   }
-);
 ```
 
-Output
+**Deep-Diff**
+
+````js
+**Deep-Diff** output:
+
+```js
+[
+ DiffEdit {
+   kind: 'E',
+   path: [ 'user', 'member' ],
+   lhs: true,
+   rhs: false
+ },
+ DiffEdit {
+   kind: 'E',
+   path: [ 'user', 'hobbies', 1 ],
+   lhs: 'football',
+   rhs: 'chess'
+ }
+]
+
+````
+
+**SuperDiff** output:
 
 ```diff
 {
@@ -90,12 +118,81 @@ Output
     }
 ```
 
-## List exemple:
+## FEATURES
+
+**Superdiff** exports 4 functions:
+
+### getObjectDiff()
+
+compare two objects and return a diff for each value and their potential subvalues:
+
+- property name
+- status: added, deleted, equal, updated
+- previous value, current value
+- supports deeply nested objects with any kind of values
+
+format:
+
+```
+type ObjectDiff = {
+  type: "object";
+   status: "added" | "deleted" | "equal" | "moved" | "updated";
+  diff: {
+    property: string;
+    previousValue: any;
+    currentValue: any;
+     status: "added" | "deleted" | "equal" | "moved" | "updated";
+    subPropertiesDiff?: {
+        name: string;
+        previousValue: any;
+        currentValue: any;
+        status: "added" | "deleted" | "equal" | "moved" | "updated";
+        // subDiff is a recursive diff in case of nested subproperties
+        subDiff?: Subproperties[];
+      }[];
+  }[];
+}
+```
+
+### getListDiff()
+
+compare two arrays and return a diff for each value:
+
+- index change: previous index, current index, index difference
+- status: added, deleted, equal, moved, updated
+- previous value, current value
+- supports array of primitive values and objects
+- ⚠️ doesn't support yet duplicated values comparison (but will soon)
+
+format:
+
+```
+type ListDiff = {
+  type: "list";
+  status: "added" | "deleted" | "equal" | "moved" | "updated";
+  diff: {
+    value: any;
+    prevIndex: number | null;
+    newIndex: number | null;
+    indexDiff: number | null;
+    status: "added" | "deleted" | "equal" | "moved" | "updated";
+  }[];
+};
+```
 
-`getListDiff()` works with arrays of string, number and objects.
-It doesn't work yet with duplicated values.
+### isEqual()
 
-Input
+check if two values are equal.
+
+### isObject()
+
+check if a value is an object.
+
+## EXAMPLES
+
+### getListDiff()
+
+input
 
 ```diff
 getListDiff(
@@ -104,7 +201,7 @@ getListDiff(
 );
 ```
 
-Output
+output
 
 ```diff
 {
@@ -150,4 +247,129 @@ Output
     }
 ```
 
-See tests for more visual examples.
+### getObjectDiff()
+
+input
+
+```diff
+getObjectDiff(
+  {
+    id: 54,
+    user: {
+      name: "joe",
+-     member: true,
+-     hobbies: ["golf", "football"],
+      age: 66,
+    },
+  },
+  {
+    id: 54,
+    user: {
+      name: "joe",
++     member: false,
++     hobbies: ["golf", "chess"],
+      age: 66,
+    },
+  }
+);
+```
+
+output
+
+```diff
+{
+      type: "object",
++     status: "updated",
+      diff: [
+        {
+          property: "id",
+          previousValue: 54,
+          currentValue: 54,
+          status: "equal",
+        },
+        {
+          property: "user",
+          previousValue: {
+            name: "joe",
+            member: true,
+            hobbies: ["golf", "football"],
+            age: 66,
+          },
+          currentValue: {
+            name: "joe",
+            member: false,
+            hobbies: ["golf", "chess"],
+            age: 66,
+          },
++         status: "updated",
+          subPropertiesDiff: [
+            {
+              name: "name",
+              previousValue: "joe",
+              currentValue: "joe",
+              status: "equal",
+            },
++           {
++             name: "member",
++             previousValue: true,
++             currentValue: false,
++             status: "updated",
++           },
++           {
++             name: "hobbies",
++             previousValue: ["golf", "football"],
++             currentValue: ["golf", "chess"],
++             status: "updated",
++           },
+            {
+              name: "age",
+              previousValue: 66,
+              currentValue: 66,
+              status: "equal",
+            },
+          ],
+        },
+      ],
+    }
+```
+
+### isEqual()
+
+```js
+isEqual(
+  [
+    { name: "joe", age: 99 },
+    { name: "nina", age: 23 },
+  ],
+  [
+    { name: "joe", age: 98 },
+    { name: "nina", age: 23 },
+  ]
+);
+```
+
+output
+
+```js
+false;
+```
+
+### isObject()
+
+input
+
+```js
+isObject(["hello", "world"]);
+```
+
+output
+
+```js
+false;
+```
+
+More examples are availble in the tests of the source code.
+
+##CREDITS
+
+DoneDeal0