tessl/npm-jsondiffpatch

JSON diff & patch library with support for objects, arrays, text diffs, and multiple output formats

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Core Operations

Name: tessl/npm-jsondiffpatch
Author: tessl

Primary diff and patch functions for generating and applying changes between JavaScript values. These functions use a default DiffPatcher instance internally.

Capabilities

Diff Function

Generates a delta representing the differences between two values.

/**
 * Generate diff between two values
 * @param left - Original value
 * @param right - Target value  
 * @returns Delta representing changes needed to transform left into right
 */
function diff(left: unknown, right: unknown): Delta;

Usage Examples:

import { diff } from "jsondiffpatch";

// Object diff
const delta1 = diff(
  { name: "Alice", age: 25 },
  { name: "Alice", age: 26, role: "admin" }
);
// Result: { age: [25, 26], role: ["admin"] }

// Array diff
const delta2 = diff([1, 2, 3], [1, 3, 4, 5]);
// Result: { _t: "a", 1: [2, 0, 0], 2: [3, 4], 3: [5] }

// Primitive diff
const delta3 = diff("hello", "world");
// Result: ["hello", "world"]

Patch Function

Applies a delta to a value to produce the target value.

/**
 * Apply patch to transform a value
 * @param left - Original value to patch
 * @param delta - Delta to apply
 * @returns Transformed value
 */
function patch(left: unknown, delta: Delta): unknown;

Usage Examples:

import { patch } from "jsondiffpatch";

// Apply object patch
const result1 = patch(
  { name: "Alice", age: 25 },
  { age: [25, 26], role: ["admin"] }
);
// Result: { name: "Alice", age: 26, role: "admin" }

// Apply array patch
const result2 = patch([1, 2, 3], { _t: "a", 1: [2, 0, 0], 2: [3, 4], 3: [5] });
// Result: [1, 4, 5]

// Apply primitive patch
const result3 = patch("hello", ["hello", "world"]);
// Result: "world"

Unpatch Function

Applies the reverse of a delta to revert changes.

/**
 * Apply reverse patch to revert changes
 * @param right - Target value to unpatch
 * @param delta - Original delta to reverse
 * @returns Original value before patch was applied
 */
function unpatch(right: unknown, delta: Delta): unknown;

Usage Examples:

import { unpatch } from "jsondiffpatch";

// Revert object changes
const original1 = unpatch(
  { name: "Alice", age: 26, role: "admin" },
  { age: [25, 26], role: ["admin"] }
);
// Result: { name: "Alice", age: 25 }

// Revert array changes
const original2 = unpatch([1, 4, 5], { _t: "a", 1: [2, 0, 0], 2: [3, 4], 3: [5] });
// Result: [1, 2, 3]

Reverse Function

Creates a reversed delta that can undo the original delta's changes.

/**
 * Reverse a delta to create undo operation
 * @param delta - Delta to reverse
 * @returns Reversed delta
 */
function reverse(delta: Delta): Delta;

Usage Examples:

import { reverse, patch } from "jsondiffpatch";

const originalDelta = { age: [25, 26], role: ["admin"] };
const reversedDelta = reverse(originalDelta);
// Result: { age: [26, 25], role: [undefined, 0, 0] }

// Use reversed delta to undo changes
const target = { name: "Alice", age: 26, role: "admin" };
const restored = patch(target, reversedDelta);
// Result: { name: "Alice", age: 25 }

Clone Function

Creates a deep clone of any value.

/**
 * Create deep clone of a value
 * @param value - Value to clone
 * @returns Deep cloned copy
 */
function clone(value: unknown): unknown;

Usage Examples:

import { clone } from "jsondiffpatch";

const original = { user: { name: "Alice", tags: ["admin", "user"] } };
const cloned = clone(original);

// Modify clone without affecting original
cloned.user.name = "Bob";
cloned.user.tags.push("editor");

console.log(original.user.name); // "Alice"
console.log(original.user.tags); // ["admin", "user"]

Create Function

Creates a new DiffPatcher instance with custom options.

/**
 * Create DiffPatcher instance with custom options
 * @param options - Configuration options
 * @returns New DiffPatcher instance
 */
function create(options?: Options): DiffPatcher;

Usage Examples:

import { create } from "jsondiffpatch";

// Create instance with custom array handling
const patcher = create({
  arrays: {
    detectMove: false,
    includeValueOnMove: true
  },
  objectHash: (obj) => obj.id || obj.name
});

const delta = patcher.diff([{id: 1, name: "A"}, {id: 2, name: "B"}], 
                          [{id: 2, name: "B"}, {id: 1, name: "A"}]);

// Create instance for text diffing
const textPatcher = create({
  textDiff: {
    minLength: 60
  }
});

With Text Diffs Module

The /with-text-diffs export provides the same API with automatic text diffing support:

import { create, diff, patch, unpatch, reverse, clone } from "jsondiffpatch/with-text-diffs";

// All functions have identical signatures but include text diff capabilities
function create(options?: Omit<Options, "textDiff"> & {
  textDiff?: Omit<Options["textDiff"], "diffMatchPatch">;
}): DiffPatcher;

Usage Examples:

import { diff } from "jsondiffpatch/with-text-diffs";

// Automatically detects and creates text diffs for long strings
const textDelta = diff(
  "The quick brown fox jumps over the lazy dog.",
  "The quick brown fox jumped over the lazy cat."
);
// Result: [textDiffString, 0, 2] where textDiffString contains diff-match-patch format