diffpatch

library0.6.0jsnpmunverified

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.

serialization data

npm install diffpatch

github ↗package ↗

INSTALL

IMPORT

SIG · DIFFPATCH

diffpatch

serializationjavascriptv0.6.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

DiffPatcher

✓ import { DiffPatcher } from 'diffpatch'

✗ import DiffPatcher from 'diffpatch'

Named export only; no default export. Since v0.5.0, ESM is used.

dateReviver

✓ import { dateReviver } from 'diffpatch'

✗ const { dateReviver } = require('diffpatch')

Named export for JSON.parse reviver support for Date objects. Works in CommonJS as well.

formatters

✓ import { formatters } from 'diffpatch'

✗ import { html, annotated } from 'diffpatch'

formatters is an object containing html, annotated, etc. Access via formatters.html, etc. ESM-only exports.

createPatcher (deprecated)

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

✗ import { createPatcher } from 'diffpatch'

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

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);

Debug

Known issues

breakingIn 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'.

affects: >=0.5.0

breakingIn 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'.

affects: >=0.5.0

deprecatedThe 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().

affects: >=0.5.0

gotchaWhen 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 })

affects: *

gotchaThe 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.

affects: *

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

fix

Upgrade to Node.js >= 8.

affects: *

Errors

Common errors & fixes

Cannot find module 'diffpatch'

Package not installed or import path incorrect.

fix

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

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

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

fix

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

DiffPatcher is not a constructor

Using createPatcher (deprecated/removed) or incorrect import.

fix

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

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

DiffPatcher instance not created correctly or variable is undefined.

fix

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

Upgrade

Version history

0.6.0latest on npm

Audit

Dependencies

diff-match-patchoptionaloptional dependency for long text diffing at character level

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bpmn-io/diffpatch ↗

packagehttps://www.npmjs.com/package/diffpatch ↗