feat: start referenceProperty for object comparison in lists

Author: DoneDeal0

README.md

@@ -10,7 +10,7 @@ This library compares two arrays or objects and return a complete diff of their
 
 All other existing solutions return a weird diff format which often require an additional parsing. They are also limited to object comparison. 👎
 
-**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 and super fast. Import. Enjoy. 👍
+**Superdiff** gives you a complete diff for both array <u>and</u> objects with a very readable format. Last but not least, it's battle tested and super fast. Import. Enjoy. 👍
 
 ## DIFF FORMAT COMPARISON
 

dist/index.d.mts

@@ -0,0 +1,93 @@
+declare const GRANULARITY: Record<string, "basic" | "deep">;
+type ListDiffStatus = "added" | "equal" | "moved" | "deleted" | "updated";
+type ObjectDiffStatus = "added" | "equal" | "deleted" | "updated";
+type ObjectData = Record<string, any> | undefined | null;
+type ListData = any;
+type ObjectStatusTuple = readonly [
+    "added",
+    "equal",
+    "deleted",
+    "updated"
+];
+type ListStatusTuple = readonly [
+    "added",
+    "equal",
+    "deleted",
+    "moved",
+    "updated"
+];
+type isEqualOptions = {
+    ignoreArrayOrder?: boolean;
+};
+type ObjectOptions = {
+    ignoreArrayOrder?: boolean;
+    showOnly?: {
+        statuses: Array<ObjectStatusTuple[number]>;
+        granularity?: (typeof GRANULARITY)[keyof typeof GRANULARITY];
+    };
+};
+type ListOptions = {
+    showOnly?: Array<ListStatusTuple[number]>;
+    referenceProperty?: string;
+};
+type ListDiff = {
+    type: "list";
+    status: ListDiffStatus;
+    diff: {
+        value: ListData;
+        prevIndex: number | null;
+        newIndex: number | null;
+        indexDiff: number | null;
+        status: ListDiffStatus;
+    }[];
+};
+type SubProperties = {
+    property: string;
+    previousValue: any;
+    currentValue: any;
+    status: ObjectDiffStatus;
+    subPropertiesDiff?: SubProperties[];
+};
+type ObjectDiff = {
+    type: "object";
+    status: ObjectDiffStatus;
+    diff: {
+        property: string;
+        previousValue: any;
+        currentValue: any;
+        status: ObjectDiffStatus;
+        subPropertiesDiff?: SubProperties[];
+    }[];
+};
+
+/**
+ * Returns the diff between two objects
+ * @param {Record<string, any>} prevData - The original object.
+ * @param {Record<string, any>} nextData - The new object.
+ * @returns ObjectDiff
+ */
+declare function getObjectDiff(prevData: ObjectData, nextData: ObjectData, options?: ObjectOptions): ObjectDiff;
+
+/**
+ * Returns the diff between two arrays
+ * @param {Array<T>} prevList - The original array.
+ * @param {Array<T>} nextList - The new array.
+ * @returns ListDiff
+ */
+declare const getListDiff: <T>(prevList: T[] | null | undefined, nextList: T[] | null | undefined, options?: ListOptions) => ListDiff;
+
+/**
+ * Returns true if two data are equal
+ * @param {any} a - The original data.
+ * @param {any} b- The data to compare.
+ * @returns boolean
+ */
+declare function isEqual(a: any, b: any, options?: isEqualOptions): boolean;
+/**
+ * Returns true if the provided value is an object
+ * @param {any} value - The data to check.
+ * @returns value is Record<string, any>
+ */
+declare function isObject(value: any): value is Record<string, any>;
+
+export { getListDiff, getObjectDiff, isEqual, isObject };

dist/index.d.ts

@@ -23,11 +23,12 @@ type ObjectOptions = {
     ignoreArrayOrder?: boolean;
     showOnly?: {
         statuses: Array<ObjectStatusTuple[number]>;
-        granularity?: typeof GRANULARITY[keyof typeof GRANULARITY];
+        granularity?: (typeof GRANULARITY)[keyof typeof GRANULARITY];
     };
 };
 type ListOptions = {
     showOnly?: Array<ListStatusTuple[number]>;
+    referenceProperty?: string;
 };
 type ListDiff = {
     type: "list";
@@ -59,11 +60,34 @@ type ObjectDiff = {
     }[];
 };
 
+/**
+ * Returns the diff between two objects
+ * @param {Record<string, any>} prevData - The original object.
+ * @param {Record<string, any>} nextData - The new object.
+ * @returns ObjectDiff
+ */
 declare function getObjectDiff(prevData: ObjectData, nextData: ObjectData, options?: ObjectOptions): ObjectDiff;
 
-declare const getListDiff: (prevList: ListData[] | undefined | null, nextList: ListData[] | undefined | null, options?: ListOptions) => ListDiff;
+/**
+ * Returns the diff between two arrays
+ * @param {Array<T>} prevList - The original array.
+ * @param {Array<T>} nextList - The new array.
+ * @returns ListDiff
+ */
+declare const getListDiff: <T>(prevList: T[] | null | undefined, nextList: T[] | null | undefined, options?: ListOptions) => ListDiff;
 
+/**
+ * Returns true if two data are equal
+ * @param {any} a - The original data.
+ * @param {any} b- The data to compare.
+ * @returns boolean
+ */
 declare function isEqual(a: any, b: any, options?: isEqualOptions): boolean;
+/**
+ * Returns true if the provided value is an object
+ * @param {any} value - The data to check.
+ * @returns value is Record<string, any>
+ */
 declare function isObject(value: any): value is Record<string, any>;
 
 export { getListDiff, getObjectDiff, isEqual, isObject };