Object Comparison

@blazediff/object takes two JavaScript values and returns a flat list of what changed, with the path to each change. It handles nested objects, arrays, dates, regexes and circular references, and it is about 55% faster than microdiff  across the benchmark fixtures.

This is the one part of BlazeDiff that has nothing to do with images. It shares the name and the performance work, not the pipeline. Use it for audit logs, undo stacks, state-change assertions in tests, or anywhere you would otherwise JSON.stringify two objects and compare strings.

Installation

npm install @blazediff/object

pnpm add @blazediff/object

yarn add @blazediff/object

bun add @blazediff/object

What you get back

One entry per change, always the same shape, so V8 keeps a single hidden class for the whole array:

interface Difference {
  type: 0 | 1 | 2;            // CREATE | REMOVE | CHANGE
  path: (string | number)[];  // e.g. ["user", "settings", "theme"]
  value: unknown;             // the new value
  oldValue: unknown;          // the previous value
}

Types are numbers rather than strings on purpose: they get compared in the hot loop. 0 is CREATE, 1 is REMOVE, 2 is CHANGE.

Examples

{
  "a": 1,
  "b": 2,
  "c": 3
}

{
  "a": 1,
  "b": 20,
  "d": 4
}

import diff from "@blazediff/object";
 
const oldObj = { a: 1, b: 2, c: 3 };
const newObj = { a: 1, b: 20, d: 4 };
 
// b changed, c was removed, d was created. a is not reported.
const changes = diff(oldObj, newObj);

{
  "user": {
    "name": "John",
    "email": "john@old.com",
    "settings": {
      "theme": "dark",
      "notifications": true
    }
  }
}

{
  "user": {
    "name": "John Doe",
    "email": "john@new.com",
    "settings": {
      "theme": "light",
      "notifications": true,
      "language": "en"
    }
  }
}

import diff from "@blazediff/object";
 
const oldObj = {
  user: {
    name: "John",
    email: "john@old.com",
    settings: {
      theme: "dark",
      notifications: true
    }
  }
};
 
const newObj = {
  user: {
    name: "John Doe",
    email: "john@new.com",
    settings: {
      theme: "light",
      notifications: true,
      language: "en"
    }
  }
};
 
// Paths go all the way down, e.g. ["user", "settings", "theme"].
const changes = diff(oldObj, newObj);

{
  "items": [
    {
      "id": 1,
      "name": "Item 1",
      "value": 100
    },
    {
      "id": 2,
      "name": "Item 2",
      "value": 200
    }
  ],
  "total": 300
}

{
  "items": [
    {
      "id": 1,
      "name": "Item 1",
      "value": 150
    },
    {
      "id": 2,
      "name": "Item 2",
      "value": 200
    },
    {
      "id": 3,
      "name": "Item 3",
      "value": 50
    }
  ],
  "total": 400
}

import diff from "@blazediff/object";
 
const oldObj = {
  items: [
    { id: 1, name: "Item 1", value: 100 },
    { id: 2, name: "Item 2", value: 200 }
  ],
  total: 300
};
 
const newObj = {
  items: [
    { id: 1, name: "Item 1", value: 150 },
    { id: 2, name: "Item 2", value: 200 },
    { id: 3, name: "Item 3", value: 50 }
  ],
  total: 400
};
 
// Arrays are compared by index, so a prepend reports every element as changed.
const changes = diff(oldObj, newObj);

Things worth knowing

• Arrays are compared by index, not by identity. Inserting at the front reports every following element as a CHANGE. If you need move detection, key the array yourself before diffing.
• Cycles are handled, and the check costs something. If you know your input is a tree, pass { detectCycles: false }.
• Unchanged values are not reported. An empty array means the two inputs are structurally equal.

What it costs

Against microdiff, M1 Max, Node 22, 10,000 iterations:

About 55% faster on average, and ~97% faster when the two inputs are identical, which is the common case when you are diffing state on every update. Full table.

Next

• Every option and the full Difference type: @blazediff/object reference
• Comparing images instead: Introduction