@ -18,7 +18,7 @@ This library compares two arrays or objects and returns a full diff of their dif
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. 👍
**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, has zero dependencies, and is super fast. Import. Enjoy. 👍
<hr/>
<hr/>
@ -40,64 +40,159 @@ I am grateful to the generous donors of **Superdiff**!
**Superdiff** exports 4 functions:
**Superdiff** exports 4 functions:
```ts
// Compares two objects and return a diff for each value and their potential subvalues
getObjectDiff(prevObject, nextObject)
// Compares two arrays and returns a diff for each value
getListDiff(prevList, nextList)
// Streams the diff of two object lists, ideal for large lists and maximum performance
granularity?: "basic" | "deep" // "basic" by default
}
}
```
- `prevData`: the original object
- `nextData`: the new object
- `options`
- `ignoreArrayOrder`: if set to `true`, `["hello", "world"]` and `["world", "hello"]` will be treated as `equal`, 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.
granularity?: "basic" | "deep" // "basic" by default
name: "joe",
- member: true,
- hobbies: ["golf", "football"],
age: 66,
},
},
{
id: 54,
user: {
name: "joe",
+ member: false,
+ hobbies: ["golf", "chess"],
age: 66,
},
}
}
}
);
```
```
- `ignoreArrayOrder`: if set to `true`, `["hello", "world"]` and `["world", "hello"]` will be treated as `equal`, because the two arrays have the same value, just not in the same order.
output
- `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"]`)
```diff
- `granularity`:
{
- `basic` returns only the main properties whose status matches your query.
type: "object",
- `deep` can return main properties if some of their subproperties' status match your request. The subproperties are filtered accordingly.
+ 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",
diff: [
{
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/>
### getListDiff()
### getListDiff()
@ -105,15 +200,31 @@ You can add a third `options` parameter to `getObjectDiff`.
import { getListDiff } from "@donedeal0/superdiff";
import { getListDiff } from "@donedeal0/superdiff";
```
```
Compares two arrays and returns a diff for each value:
Compares two arrays and returns a diff for each entry. Supports duplicate values, primitive values and objects.
- index change: `prevIndex`, `newIndex`, `indexDiff`
considerMoveAsUpdate?: boolean // false by default
}
```
- `prevList`: the original list
- `nextList`: the new list
- `options`
- `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 its `id`. This option has no effect on other datatypes.
- `ignoreArrayOrder`: if set to `true`, `["hello", "world"]` and `["world", "hello"]` will be treated as `equal`, because the two arrays have the same value, just not in the same order.
- `considerMoveAsUpdate`: if set to `true` the `moved` value will be considered as `updated`.
format:
output
```ts
```ts
type ListDiff = {
type ListDiff = {
@ -128,56 +239,7 @@ type ListDiff = {
}[];
}[];
};
};
```
```
**Usage**
**Options**
You can add a third `options` parameter to `getListDiff`.
- `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 its `id`. This option has no effect on other datatypes.
- `ignoreArrayOrder`: if set to `true`, `["hello", "world"]` and `["world", "hello"]` will be treated as `equal`, because the two arrays have the same value, just not in the same order.
### isEqual()
```js
import { isEqual } from "@donedeal0/superdiff";
```
Tests whether two values are equal.
**Options**
You can add a third `options` parameter to `isEqual`.
```ts
{
ignoreArrayOrder?: boolean // false by default,
}
```
- `ignoreArrayOrder`: if set to `true`, `["hello", "world"]` and `["world", "hello"]` will be treated as `equal`, because the two arrays have the same value, just not in the same order.
### isObject()
```js
import { isObject } from "@donedeal0/superdiff";
```
Tests whether a value is an object.
<hr/>
## EXAMPLES
### getListDiff()
input
input
@ -233,96 +295,146 @@ output
],
],
}
}
```
```
<hr/>
### getObjectDiff()
### streamListDiff()
```js
import { streamListDiff } from "@donedeal0/superdiff";
```
Streams the diff of two object lists, ideal for large lists and maximum performance.
**Format**
input
input
```diff
```ts
getObjectDiff(
prevList: T[],
{
nextList: T[],
id: 54,
referenceProperty: ReferenceProperty<T>,
user: {
options: {
name: "joe",
showOnly?: returns only the values whose status you are interested in. (e.g. `["added", "equal"]`), // [] by default
- member: true,
chunksSize?: number, // // 0 by default
- hobbies: ["golf", "football"],
considerMoveAsUpdate? boolean; // false by default
age: 66,
}
},
},
{
id: 54,
user: {
name: "joe",
+ member: false,
+ hobbies: ["golf", "chess"],
age: 66,
},
}
);
```
```
- `prevList`: the original object list.
- `nextList`: the new object list.
- `referenceProperty`: a common property in all the objects of your lists (e.g. `id`).
- `options`
- `chunksSize` the number of object diffs returned by each stream chunk. If set to `0`, each stream will return a single object diff. If set to `10` each stream will return 10 object diffs.
- `showOnly` gives you the option to return only the values whose status you are interested in (e.g. `["added", "equal"]`).
- `considerMoveAsUpdate`: if set to `true` the `moved` value will be considered as `updated`.
output
output
```ts
type StreamListDiff<TextendsRecord<string,unknown>> = {
diff.on("finish", () => console.log("The full diff is available"))
diff.on("error", (err)=> console.log(err))
```
```
<hr/>
### isEqual()
### isEqual()
```js
```js
import { isEqual } from "@donedeal0/superdiff";
```
Checks whether two values are equal.
**Options**
You can add a third `options` parameter to `isEqual`.
```ts
{
ignoreArrayOrder?: boolean // false by default,
}
```
- `ignoreArrayOrder`: if set to `true`, `["hello", "world"]` and `["world", "hello"]` will be treated as `equal`, because the two arrays have the same value, just not in the same order.
**Usage**
```ts
isEqual(
isEqual(
[
[
{ name: "joe", age: 99 },
{ name: "joe", age: 99 },
@ -337,25 +449,36 @@ isEqual(
output
output
```js
```ts
false;
false;
```
```
<hr/>
### isObject()
### isObject()
```js
import { isObject } from "@donedeal0/superdiff";
```
Tests whether a value is an object.
**Usage**
input
input
```js
```ts
isObject(["hello", "world"]);
isObject(["hello", "world"]);
```
```
output
output
```js
```ts
false;
false;
```
```
More examples are available in the source code tests.
<hr/>
### More examples are available in the source code tests.
<hr/>
<hr/>
@ -365,7 +488,7 @@ DoneDeal0
## SUPPORT
## SUPPORT
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
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`. Premium support is also available. https://github.com/sponsors/DoneDeal0
Antoine Lanoe
7 months ago