Diff Reference

Coverage License NPM Version Open Issues

↔️ Deep diffing utility.

Usage

📦 Node

Install @lou.codes/diff as a dependency:

1
pnpm add @lou.codes/diff
2
# or
3
npm install @lou.codes/diff
4
# or
5
yarn add @lou.codes/diff

Import it and use it:

1
import { compare } from "@lou.codes/diff";
2

3
compare({ left: "Lou", right: "Nope" }); // [{ kind: 4, left: "Lou", right: "Nope", path: [] }]

🦕 Deno

Import @lou.codes/diff using the npm: prefix, and use it directly:

1
import { compare } from "npm:@lou.codes/diff";
2

3
compare({ left: "Lou", right: "Nope" }); // [{ kind: 4, left: "Lou", right: "Nope", path: [] }]

🌎 Browser

Import @lou.codes/diff using esm.sh, and use it directly:

1
<script type="module">
2
	import { compare } from "https://esm.sh/@lou.codes/diff";
3

4
	compare({ left: "Lou", right: "Nope" }); // [{ kind: 4, left: "Lou", right: "Nope", path: [] }]
5
</script>

Useful links

📝 Documentation: TypeDoc generated documentation.
⏳ Changelog: List of changes between versions.
✅ Tests Coverage: Coveralls page with tests coverage.

Difference

CreateDifference<Right>

1
type CreateDifference<Right>: Difference<typeof CREATE> & object;

Object that represents a creation difference (a new value or property).

Example

1
const createDifference: CreateDifference<string> = {
2
	kind: 1,
3
	path: ["foo", "bar"],
4
	right: "Lou",
5
};

Type declaration

Member	Type	Description
`right`	`Right`	New value.

Type parameters

Type parameter	Value	Description
`Right`	`unknown`	Type of the new value.

View source

DeleteDifference<Left>

1
type DeleteDifference<Left>: Difference<typeof DELETE> & object;

Object that represents a deletion difference (a value or property was removed).

Example

1
const deleteDifference: DeleteDifference<string> = {
2
	kind: 2,
3
	path: ["foo", "bar"],
4
	left: "Lou",
5
};

Type declaration

Member	Type	Description
`left`	`Left`	Original value.

Type parameters

Type parameter	Value	Description
`Left`	`unknown`	Type of the removed value.

View source

Difference<Kind>

1
type Difference<Kind>: object;

Object that represents a difference between two values.

Example

1
const difference: Difference<"CREATE"> = {
2
	kind: "CREATE",
3
	path: ["foo", "bar"],
4
};

Type parameters

Type parameter	Description
`Kind` extends `DifferenceKind`	Type of diff.

Type declaration

Member	Type	Description
`kind`	`Kind`	Type of diff.
`path`	`ReadOnlyArray`<`PropertyKey`>	Path of diff property.

View source

DifferenceKind

1
type DifferenceKind: typeof CREATE | typeof DELETE | typeof UPDATE;

Kinds of differences (create, delete or update).

Example

1
const create: DifferenceKind = 1;
2
const delete: DifferenceKind = 2;
3
const update: DifferenceKind = 4;

View source

UpdateDifference<Left, Right>

1
type UpdateDifference<Left, Right>: Difference<typeof UPDATE> & object;

Object that represents an update difference (a value or property changed).

Example

1
const updateDifference: UpdateDifference<string, number> = {
2
	kind: 4,
3
	path: ["foo", "bar"],
4
	left: "Lou",
5
	right: 42,
6
};

Type declaration

Member	Type	Description
`left`	`Left`	Original value.
`right`	`Right`	New value.

Type parameters

Type parameter	Value	Description
`Left`	`unknown`	Type of the new value.
`Right`	`unknown`	Type of the original value.

View source

compare()

1
function compare(
2
	values: object,
3
): Generator<CreateDifference | DeleteDifference | UpdateDifference, any, any>;

Function to compare a left and a right value.

Parameters

Parameter	Type	Description
`values`	`object`	Values to compare.
`values.left`?	`unknown`	Left value to compare.
`values.right`?	`unknown`	Right value to compare.

Returns

Generator<CreateDifference | DeleteDifference | UpdateDifference, any, any>

Remarks

This does a deep comparison and yields the differences found with a descriptive object.

Example

1
compare({ left: "🟢", right: "🟢" }); // []
2
compare({ left: "🟢", right: "❌" }); // [{ kind: UPDATE, left: "🟢", right: "❌", path: [] }]
3
compare({ left: { foo: "🟢" }, right: { foo: "❌" } }); // [{ kind: UPDATE, left: "🟢", right: "❌", path: ["foo"] }]

View source

Other

CREATE

1
const CREATE: 1 = 1;

Create difference kind.

View source

DELETE

1
const DELETE: 2 = 2;

Delete difference kind.

View source

UPDATE

1
const UPDATE: 4 = 4;

Update difference kind.

View source