@sandboxed/diff

A zero dependency, high-performance, security-conscious JavaScript diffing library for comparing complex data structures with ease.

Features

• ⚡️ Zero dependencies – lightweight and no external libraries required
• 📝 Detects additions, deletions, and modifications
• 💡 Supports Primitives, Objects, Arrays, Maps, and Sets
• 🔄 Handles circular references safely
• 🛠️ Highly configurable to fit different use cases
• 🚨 Built with security in mind to prevent prototype pollution and other risks
• 💻 Works in both Node.js and browser environments

Installation

npm install @sandboxed/diff

yarn add @sandboxed/diff

Supports esm and cjs

Works with both ESM (import) and CJS (require). Use the syntax that matches your environment:

// ESM
import diff, { ChangeType } from '@sandboxed/diff';

// CJS option 1
const diff = require('@sandboxed/diff').default;
const { ChangeType } = require('@sandboxed/diff');

// CJS option 2
const { default: diff, ChangeType } = require('@sandboxed/diff');

Usage

diff(lhs: any, rhs: any, config?: DiffConfig): Diff

import diff, { ChangeType } from '@sandboxed/diff';

const a = { name: "Alice", age: 25 };
const b = { name: "Alice", age: 26, city: "New York" };

const result = diff(a, b);

console.log(result);
console.log(result.toDiffString());
console.log(result.equal); // false

Output:

[
  { type: 'noop', str: '{', depth: 0, path: [] },
  {
    type: 'noop',
    str: '"name": "Alice",',
    depth: 1,
    path: [ 'name', { deleted: false, value: 'Alice' } ]
  },
  {
    type: 'remove',
    str: '"age": 25,',
    depth: 1,
    path: [ 'age', { deleted: true, value: 25 } ]
  },
  {
    type: 'update',
    str: '"age": 26,',
    depth: 1,
    path: [ 'age', { deleted: false, value: 26 } ]
  },
  {
    type: 'add',
    str: '"city": "New York",',
    depth: 1,
    path: [ 'city', { deleted: false, value: 'New York' } ]
  },
  { type: 'noop', str: '}', depth: 0, path: [] }
]

// ---

{
   "name": "Alice",
-  "age": 25,
!  "age": 26,
+  "city": "New York",
}

Config

| option | Description | |-|-| |config.include| Include only these change types from the diff result. Can be combined with exclude. | |config.exclude| Excludes the change types from the diff result. Can be combined with include. | |config.strict| Performs loose type check if disabled. | |config.showUpdatedOnly| @sandboxed/diff creates a ChangeType.REMOVE entry for every ChangeType.UPDATE. This flags prevents this behavior. | |config.pathHints| Hashmap of map and set path hints. These strings will be used in the path array to provide a hit about the object's type. | |config.redactKeys| List of keys that should be redacted from the output. Works with string based keys and serialized Symbol. | |config.maxDepth| Max depth that the diffing function can traverse. | |config.maxKeys| Max keys the diffing function can traverse. | |config.timeout| Milliseconds before throwing a timeout error. |

Utils

| util | Description | |-|-| |toDiffString| Generates the diff string representation of the diff result. | |equal| Determines whether the inputs are structurally equal based on the diff result. |

Motivation

Many diffing libraries are optimized for either structured output or human-readable text, but rarely both. @sandboxed/diff is designed to provide a structured diff result along with a utility to generate a string representation, making it easy to use in both programmatic logic and UI rendering.

Trade-off: It may be slower than other libraries, but if you prioritize structured diffs with a built-in string representation, @sandboxed/diff is a great fit.

LICENSE

MIT