feat: simplify output, clean readme (#25)

BREAKING CHANGE: subPropertiesDiff has been removed from the getObjectDiff output. There is now a single recursive diff key for more simplicity. The types have also been improved.

Author: DoneDeal0

.eslintcache

@@ -1,2 +1,3 @@
 /node_modules
-dist
+dist
+.eslintcache

.gitignore

@@ -1,20 +1,27 @@
 <img width="722" alt="superdiff-logo" src="https://user-images.githubusercontent.com/43271780/209532864-24d7449e-1185-4810-9423-be5df1fe877f.png">
 
-# SUPERDIFF
-
-This library compares two arrays or objects and returns a full diff of their differences.
 
 [![CI](https://github.com/DoneDeal0/superdiff/actions/workflows/ci.yml/badge.svg)](https://github.com/DoneDeal0/superdiff/actions/workflows/ci.yml)
 [![CD](https://github.com/DoneDeal0/superdiff/actions/workflows/cd.yml/badge.svg)](https://github.com/DoneDeal0/superdiff/actions/workflows/cd.yml)
 ![NPM Downloads](https://img.shields.io/npm/dy/%40donedeal0%2Fsuperdiff?logo=npm)
 ![GitHub Tag](https://img.shields.io/github/v/tag/DoneDeal0/superdiff?label=latest%20release)
 
+<hr/>
+
+# WHAT IS IT?
+
+This library compares two arrays or objects and returns a full diff of their differences.
+
+<hr/>
+
 ## WHY YOU SHOULD USE THIS LIBRARY
 
-All other existing solutions return a strange diff format that often requires additional parsing. They are also limited to object comparison. 👎
+All other existing solutions return a strange diff format that often requires additional parsing. They are also limited to object comparison.
 
 **Superdiff** gives you a complete diff for both array <u>and</u> objects in a very readable format. Last but not least, it's battle-tested and super fast. Import. Enjoy. 👍
 
+<hr/>
+
 ## DONORS
 
 I am grateful to the generous donors of **Superdiff**!
@@ -27,111 +34,7 @@ I am grateful to the generous donors of **Superdiff**!
 
  </div>
 
-## DIFF FORMAT COMPARISON
-
-Let's compare the diff format of **Superdiff** and **Deep-diff**, the most popular diff lib on npm:
-
-input:
-
-```diff
-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,
-        },
-  }
-```
-
-**Deep-Diff** output:
-
-```js
-[
-  {
-    kind: "E",
-    path: ["user", "member"],
-    lhs: true,
-    rhs: false,
-  },
-  {
-    kind: "E",
-    path: ["user", "hobbies", 1],
-    lhs: "football",
-    rhs: "chess",
-  },
-];
-```
-
-**SuperDiff** 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: [
-            {
-              property: "name",
-              previousValue: "joe",
-              currentValue: "joe",
-              status: "equal",
-            },
-+           {
-+             property: "member",
-+             previousValue: true,
-+             currentValue: false,
-+             status: "updated",
-+           },
-+           {
-+             property: "hobbies",
-+             previousValue: ["golf", "football"],
-+             currentValue: ["golf", "chess"],
-+             status: "updated",
-+           },
-            {
-              property: "age",
-              previousValue: 66,
-              currentValue: 66,
-              status: "equal",
-            },
-          ],
-        },
-      ],
-    }
-```
+ <hr/>
 
 ## FEATURES
 
@@ -158,17 +61,17 @@ type ObjectDiff = {
   status: "added" | "deleted" | "equal" | "updated";
   diff: {
     property: string;
-    previousValue: any;
-    currentValue: any;
+    previousValue: unknown;
+    currentValue: unknow;
     status: "added" | "deleted" | "equal" | "updated";
     // only appears if some subproperties have been added/deleted/updated
-    subPropertiesDiff?: {
+    diff?: {
       property: string;
-      previousValue: any;
-      currentValue: any;
+      previousValue: unknown;
+      currentValue: unknown;
       status: "added" | "deleted" | "equal" | "updated";
-      // subDiff is a recursive diff in case of nested subproperties
-      subDiff?: SubProperties[];
+      // recursive diff in case of subproperties
+      diff?: SubDiff[];
     }[];
   }[];
 };
@@ -217,7 +120,7 @@ type ListDiff = {
   type: "list";
   status: "added" | "deleted" | "equal" | "moved" | "updated";
   diff: {
-    value: any;
+    value: unknown;
     prevIndex: number | null;
     newIndex: number | null;
     indexDiff: number | null;
@@ -270,6 +173,8 @@ import { isObject } from "@donedeal0/superdiff";
 
 Tests whether a value is an object.
 
+<hr/>
+
 ## EXAMPLES
 
 ### getListDiff()
@@ -384,7 +289,7 @@ output
             age: 66,
           },
 +         status: "updated",
-          subPropertiesDiff: [
+          diff: [
             {
               property: "name",
               previousValue: "joe",

README.md

@@ -7,10 +7,4 @@ export default [
   { settings: { react: { version: "detect" } } },
   pluginJs.configs.recommended,
   ...tseslint.configs.recommended,
-  {
-    rules: {
-      "@typescript-eslint/no-explicit-any": "off",
-      "@typescript-eslint/ban-ts-comment": "off"
-    },
-  },
 ];

eslint.config.mjs

@@ -1,6 +1,6 @@
 {
   "name": "@donedeal0/superdiff",
-  "version": "1.1.3",
+  "version": "2.0.0",
   "description": "SuperDiff checks the changes between two objects or arrays. It returns a complete diff with relevant information for each property or piece of data",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package.json

@@ -1,4 +1,5 @@
 export { getObjectDiff } from "./object-diff";
 export { getListDiff } from "./list-diff";
 export { isEqual, isObject } from "./utils";
-export * from "./model";
+export * from "./models/list";
+export * from "./models/object";

src/index.ts

@@ -1,17 +1,22 @@
-import { LIST_STATUS, ListDiff, ListDiffStatus, ListOptions } from "./model";
+import {
+  DEFAULT_LIST_DIFF_OPTIONS,
+  LIST_STATUS,
+  ListDiff,
+  ListDiffOptions,
+} from "./models/list";
 import { isEqual, isObject } from "./utils";
 
 function getLeanDiff(
   diff: ListDiff["diff"],
-  showOnly = [] as ListOptions["showOnly"],
+  showOnly = [] as ListDiffOptions["showOnly"],
 ): ListDiff["diff"] {
   return diff.filter((value) => showOnly?.includes(value.status));
 }
 
 function formatSingleListDiff<T>(
   listData: T[],
-  status: ListDiffStatus,
-  options: ListOptions = { showOnly: [] },
+  status: LIST_STATUS,
+  options: ListDiffOptions = { showOnly: [] },
 ): ListDiff {
   const diff = listData.map((data, i) => ({
     value: data,
@@ -34,16 +39,16 @@ function formatSingleListDiff<T>(
   };
 }
 
-function getListStatus(listDiff: ListDiff["diff"]): ListDiffStatus {
+function getListStatus(listDiff: ListDiff["diff"]): LIST_STATUS {
   return listDiff.some((value) => value.status !== LIST_STATUS.EQUAL)
     ? LIST_STATUS.UPDATED
     : LIST_STATUS.EQUAL;
 }
 
 function isReferencedObject(
-  value: any,
-  referenceProperty: ListOptions["referenceProperty"],
-): value is Record<string, any> {
+  value: unknown,
+  referenceProperty: ListDiffOptions["referenceProperty"],
+): value is Record<string, unknown> {
   if (isObject(value) && !!referenceProperty) {
     return Object.hasOwn(value, referenceProperty);
   }
@@ -62,12 +67,7 @@ function isReferencedObject(
 export const getListDiff = <T>(
   prevList: T[] | undefined | null,
   nextList: T[] | undefined | null,
-  options: ListOptions = {
-    showOnly: [],
-    referenceProperty: undefined,
-    considerMoveAsUpdate: false,
-    ignoreArrayOrder: false,
-  },
+  options: ListDiffOptions = DEFAULT_LIST_DIFF_OPTIONS,
 ): ListDiff => {
   if (!prevList && !nextList) {
     return {