This library compares two arrays or objects and returns a full diff of their differences.
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 and objects in a very readable format. Last but not least, it's battle-tested and super fast. Import. Enjoy. 👍
I am grateful to the generous donors of Superdiff!
Let's compare the diff format of Superdiff and Deep-diff, the most popular diff lib on npm:
input:
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:
[
{
kind: "E",
path: ["user", "member"],
lhs: true,
rhs: false,
},
{
kind: "E",
path: ["user", "hobbies", 1],
lhs: "football",
rhs: "chess",
},
];
SuperDiff output:
{
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",
},
],
},
],
}
Superdiff exports 4 functions:
import { getObjectDiff } from "@donedeal0/superdiff";
Compares 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" | "updated";
diff: {
property: string;
previousValue: any;
currentValue: any;
status: "added" | "deleted" | "equal" | "updated";
// only appears if some subproperties have been added/deleted/updated
subPropertiesDiff?: {
property: string;
previousValue: any;
currentValue: any;
status: "added" | "deleted" | "equal" | "updated";
// subDiff is a recursive diff in case of nested subproperties
subDiff?: SubProperties[];
}[];
}[];
};
Options
You can add a third options
parameter to getObjectDiff
.
{
ignoreArrayOrder?: boolean // false by default,
showOnly?: {
statuses: ("added" | "deleted" | "updated" | "equal")[], // [] by default
granularity?: "basic" | "deep" // "basic" by default
}
}
-
ignoreArrayOrder
: if set totrue
,["hello", "world"]
and["world", "hello"]
will be treated asequal
, because the two arrays have the same value, just not in the same order. -
showOnly
: returns only the values whose status you are interested in. It takes two parameters:statuses
: status you want to see in the output (e.g.["added", "equal"]
)granularity
:basic
returns only the main properties whose status matches your query.deep
can return main properties if some of their subproperties' status match your request. The subproperties are filtered accordingly.
import { getListDiff } from "@donedeal0/superdiff";
Compares two arrays and returns a diff for each value:
- index change:
prevIndex
,newIndex
,indexDiff
- status:
added
,deleted
,equal
,moved
,updated
- value
- supports arrays of primitive values and objects
- supports arrays with duplicate values
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";
}[];
};
Options
You can add a third options
parameter to getListDiff
.
{
showOnly?: ("added" | "deleted" | "moved" | "updated" | "equal")[], // [] by default
referenceProperty?: string; // "" by default
}
showOnly
gives you the option to return only the values whose status you are interested in (e.g.["added", "equal"]
).referenceProperty
will consider an object to be updated instead of added or deleted if one of its properties remains stable, such as itsid
. This option has no effect on other datatypes.
import { isEqual } from "@donedeal0/superdiff";
Tests whether two values are equal.
Options
You can add a third options
parameter to isEqual
.
{
ignoreArrayOrder?: boolean // false by default,
}
ignoreArrayOrder
: if set totrue
,["hello", "world"]
and["world", "hello"]
will be treated asequal
, because the two arrays have the same value, just not in the same order.
import { isObject } from "@donedeal0/superdiff";
Tests whether a value is an object.
input
getListDiff(
- ["mbappe", "mendes", "verratti", "ruiz"],
+ ["mbappe", "messi", "ruiz"]
);
output
{
type: "list",
+ status: "updated",
diff: [
{
value: "mbappe",
prevIndex: 0,
newIndex: 0,
indexDiff: 0,
status: "equal",
},
- {
- value: "mendes",
- prevIndex: 1,
- newIndex: null,
- indexDiff: null,
- status: "deleted",
- },
- {
- value: "verratti",
- prevIndex: 2,
- newIndex: null,
- indexDiff: null,
- status: "deleted",
- },
+ {
+ value: "messi",
+ prevIndex: null,
+ newIndex: 1,
+ indexDiff: null,
+ status: "added",
+ },
+ {
+ value: "ruiz",
+ prevIndex: 3,
+ newIndex: 2,
+ indexDiff: -1,
+ status: "moved",
},
],
}
input
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
{
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",
},
],
},
],
}
isEqual(
[
{ name: "joe", age: 99 },
{ name: "nina", age: 23 },
],
[
{ name: "joe", age: 98 },
{ name: "nina", age: 23 },
]
);
output
false;
input
isObject(["hello", "world"]);
output
false;
More examples are available in the source code tests.
DoneDeal0
If you or your company uses Superdiff, please show your support by becoming a sponsor! Your name and company logo will be displayed on the README.md
. https://github.com/sponsors/DoneDeal0
![sponsor](https://private-user-images.githubusercontent.com/43271780/318413537-21deb4f3-fee3-4bf9-a945-ed0b77c6f82f.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjQ3MDczNTYsIm5iZiI6MTcyNDcwNzA1NiwicGF0aCI6Ii80MzI3MTc4MC8zMTg0MTM1MzctMjFkZWI0ZjMtZmVlMy00YmY5LWE5NDUtZWQwYjc3YzZmODJmLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNDA4MjYlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjQwODI2VDIxMTczNlomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPWZkOTM5MmY3MDIwZDAyZTRiODBlOWIxZTkxNmUzMTAwODhlZjY3MTgwNDE1NDQ5NmFkN2U5OTEwYmQ0NWI3ZjEmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JmFjdG9yX2lkPTAma2V5X2lkPTAmcmVwb19pZD0wIn0.0oMRkGwPvYRSpGZ5pcUqonitRIl3ZXeZ1Mp0P0rjHZQ)
Pull requests are welcome!