spotdiff

Compare two JS objects, find what changed, patch back, humanize the diff.

Install

npm install spotdiff

Usage

import { spotdiff, patch, humanize } from 'spotdiff'

const v1 = { user: { name: 'Juan', age: 30, tags: ['a', 'b'] } }
const v2 = { user: { name: 'Juan', age: 31, tags: ['a', 'c', 'd'] } }

const changes = spotdiff(v1, v2)
// [
//   { path: 'user.age',     op: 'changed', from: 30,        to: 31  },
//   { path: 'user.tags[1]', op: 'changed', from: 'b',       to: 'c' },
//   { path: 'user.tags[2]', op: 'added',   from: undefined, to: 'd' },
// ]

patch(v1, changes)        // → v2
patch(v2, changes, true)  // → v1

humanize(changes)
// [
//   "user.age changed from 30 to 31",
//   "user.tags[1] changed from b to c",
//   "user.tags[2] was added with value d"
// ]

humanize(changes, { lang: 'es' })
// [
//   "user.age cambió de 30 a 31",
//   "user.tags[1] cambió de b a c",
//   "user.tags[2] fue agregado con valor d"
// ]

API

spotdiff(a, b, options?): Change[]

| Option | Type | Default | Description | |--------|------|---------|-------------| | maxDepth | number | Infinity | Stop recursion at this depth | | ignoreKeys | string[] | [] | Skip these keys everywhere | | arrays | 'index' \| 'smart' | 'index' | Array comparison strategy |

patch(obj, changes, reverse?): unknown

Apply changes forward or backward (reverse=true).

humanize(changes, options?): string[]

| Option | Type | Default | |--------|------|---------| | lang | 'en' \| 'es' | 'en' |

Change shape

interface Change {
  path: string    // "user.address.city" or "tags[2]"
  op: 'added' | 'removed' | 'changed'
  from: unknown   // undefined if op is 'added'
  to: unknown     // undefined if op is 'removed'
}

Notes

• Zero production dependencies
• Dual package ESM + CJS
• TypeScript strict mode
• Never mutates inputs
• Handles null, undefined, Date, Map, Set
• Throws on circular references with a descriptive message