diffpatch

0.6.0 verified Fri May 01 auth: no javascript

A JavaScript library for diffing and patching plain objects and arrays, including nested structures. Current stable version is 0.6.0, released as an ES module with TypeScript type definitions. It uses LCS (Longest Common Subsequence) for smart array diffing, supports reverse deltas, unpatching, and optional output formatters. Optionally leverages google-diff-match-patch for long text diffs. Compared to similar libraries, diffpatch focuses on pure JSON delta format and low footprint (~16KB min+gzipped), and requires an objectHash function for object identity matching in arrays.

Common errors

error Cannot find module 'diffpatch' ↓

cause Package not installed or import path incorrect.

fix

Run 'npm install diffpatch' and ensure import path is 'diffpatch' (not 'diffpatch-master' or similar).

error Uncaught SyntaxError: The requested module 'diffpatch' does not provide an export named 'default' ↓

cause Using default import but diffpatch only exports named exports since v0.5.0.

fix

Replace 'import DiffPatcher from "diffpatch"' with 'import { DiffPatcher } from "diffpatch"'.

error DiffPatcher is not a constructor ↓

cause Using createPatcher (deprecated/removed) or incorrect import.

fix

Ensure you have imported { DiffPatcher } and use 'new DiffPatcher()'.

error TypeError: Cannot read properties of undefined (reading 'diff') ↓

cause DiffPatcher instance not created correctly or variable is undefined.

fix

Verify you created an instance: const dp = new DiffPatcher();

Warnings

breaking In diffpatch v0.5.0, the library switched from CommonJS to ES modules. If you use require('diffpatch'), you must update to dynamic import or use a bundler that supports ESM. ↓

fix Replace const { DiffPatcher } = require('diffpatch') with import { DiffPatcher } from 'diffpatch'.

breaking In diffpatch v0.5.0, the default export was removed. Previously, you could import DiffPatcher as default; now it is a named export only. ↓

fix Use import { DiffPatcher } from 'diffpatch' instead of import DiffPatcher from 'diffpatch'.

deprecated The createPatcher function was deprecated in v0.4.0 and removed entirely in v0.5.0. Use the new DiffPatcher() constructor. ↓

fix Use new DiffPatcher() instead of createPatcher().

gotcha When diffing arrays of objects, the default object matching is by position. To match objects by identity, you must provide an objectHash function in the DiffPatcher options. Otherwise, diffs may misinterpret insertions/deletions. ↓

fix const dp = new DiffPatcher({ objectHash: obj => obj.id })

gotcha The delta format is not backwards compatible with other diff libraries. Do not mix diffpatch deltas with libraries like jsondiffpatch. ↓

fix Use diffpatch both for producing and consuming deltas.

gotcha When using in Node.js < 8, the library will not work because Node 8+ is required (engines.node >= 8). ↓

fix Upgrade to Node.js >= 8.

Install

npm install diffpatch

yarn add diffpatch

pnpm add diffpatch

Imports

DiffPatcher
wrong
```
import DiffPatcher from 'diffpatch'
```
correct
```
import { DiffPatcher } from 'diffpatch'
```
Named export only; no default export. Since v0.5.0, ESM is used.
dateReviver
wrong
```
const { dateReviver } = require('diffpatch')
```
correct
```
import { dateReviver } from 'diffpatch'
```
Named export for JSON.parse reviver support for Date objects. Works in CommonJS as well.
formatters
wrong
```
import { html, annotated } from 'diffpatch'
```
correct
```
import { formatters } from 'diffpatch'
```
formatters is an object containing html, annotated, etc. Access via formatters.html, etc. ESM-only exports.

createPatcher (deprecated)

wrong

import { createPatcher } from 'diffpatch'

correct

import { DiffPatcher } from 'diffpatch'; const patcher = new DiffPatcher()

createPatcher was removed in v0.5.0. Use new DiffPatcher() instead.

Quickstart

Basic diff, patch, and unpatch operations with primitive and array values using DiffPatcher.

import { DiffPatcher } from 'diffpatch';

const dp = new DiffPatcher();

const obj1 = { name: 'Alice', age: 30, items: [1, 2, 3] };
const obj2 = { name: 'Bob', age: 30, items: [1, 2, 4] };

const delta = dp.diff(obj1, obj2);
console.log('Delta:', JSON.stringify(delta, null, 2));
// {
//   "name": ["Alice", "Bob"],
//   "items": {
//     "_t": "a",
//     "2": [3, 4]
//   }
// }

// Patch obj1 to become obj2
dp.patch(obj1, delta);
console.log('Patched obj1:', obj1);

// Unpatch to revert
dp.unpatch(obj1, delta);
console.log('Unpatched obj1:', obj1);