@sanity/diff

What is @sanity/diff?

@sanity/diff is a JavaScript library designed to compute and represent differences between two JSON documents. It is particularly useful for applications that need to track changes in data structures, such as content management systems or collaborative editing tools.

What are @sanity/diff's main functionalities?

Compute Differences

This feature allows you to compute the differences between two JSON documents. The `diff` function takes two objects and returns an object representing the changes.

const { diff } = require('@sanity/diff');

const oldDoc = { name: 'Alice', age: 30 };
const newDoc = { name: 'Alice', age: 31 };

const differences = diff(oldDoc, newDoc);
console.log(differences);

Patch Application

This feature allows you to apply a patch to a JSON document. The `applyPatch` function takes an original object and a patch object, and returns the updated object.

const { applyPatch } = require('@sanity/diff');

const oldDoc = { name: 'Alice', age: 30 };
const patch = { age: 31 };

const newDoc = applyPatch(oldDoc, patch);
console.log(newDoc);

Visual Representation

This feature allows you to get a visual representation of the differences between two JSON documents. The `formatDiff` function takes the differences object and returns a human-readable string.

const { diff, formatDiff } = require('@sanity/diff');

const oldDoc = { name: 'Alice', age: 30 };
const newDoc = { name: 'Alice', age: 31 };

const differences = diff(oldDoc, newDoc);
const formattedDiff = formatDiff(differences);
console.log(formattedDiff);

Other packages similar to @sanity/diff

diff

The `diff` package is a popular library for computing differences between two strings or objects. It provides a variety of diff algorithms and can be used for text, JSON, and other data structures. Compared to @sanity/diff, it offers more flexibility in terms of diff algorithms but may require more configuration.

deep-diff

The `deep-diff` package is another library for comparing the differences between two JavaScript objects. It provides a simple API for finding differences and applying patches. While it is similar to @sanity/diff in functionality, it may not offer the same level of integration with Sanity's ecosystem.

jsondiffpatch

The `jsondiffpatch` package is designed specifically for comparing JSON documents and applying patches. It offers a rich set of features, including visual diffing and patching. Compared to @sanity/diff, it provides more advanced features for JSON-specific use cases but may be more complex to use.

README

@sanity/diff: Tools for diffing data structures

@sanity/diff is a library for calculating and presenting diffs of content.

Concepts and architecture

• The main data structure is Diff which represents a difference between two versions. This is a nested data structure so if it's an ObjectDiff, then its children will have Diff as well.

  The Diff is built on top of the unchanged, added and removed primitives. This means that it will contain both versions at the same time and it's always trivial to recreate the old/new version (by ignoring the added/removed parts of the diff).

  Note that for arrays and objects, unchanged/added/removed only have a "shallow" meaning. An ObjectDiff will have a unchanged field if the field was present in both the old and new version - regardless of whether there's any internal changes.

• Diff also supports annotations. These contain information about when a change was introduced and who was responsible for it.

• To construct a Diff you need to represent the versions as Input types and use diffInput(from,to) to create the diff. The primary reason for a separate Input type is to support passing along annotations. In addition, this allows us to optimize based on the object equality of the inputs.

• There are multiple ways of presenting a diff: Sometimes you want to only show the fields that has changed, and other times you want to show the full new (or old!) document interspersed with the changes.

  This library does not contain any UI components, but instead provides various presentation-related helper functions.