diff-leven

Git-like diff between two strings or objects, powered by the Levenshtein distance algorithm

Try now: link

✨ Features

• Advanced Diff Generation: Uses the Levenshtein distance algorithm for meaningful diffs

• Multiple Data Type Support:

  • Objects (including nested structures)
  • Arrays (positional comparison; no reordering/LCS)
  • Strings (character-level differences)
  • Numbers, Booleans, and any serializable value

• Rich Output Options:

  • Git-style colorized output diff format with clear additions/removals

• Flexible Configuration:

  • color: Toggle color output (default: true)
  • keysOnly: Compare only object structure/keys (default: false)
  • full: Output the entire object tree, not just differences (default: false)
  • outputKeys: Always include specified keys in output for objects with differences
  • ignoreKeys: Skip specified keys when comparing objects
  • ignoreValues: Ignore value differences, focus on structure

🚀 Quick Start

1. Install

npm install diff-leven

2. Usage

const { diff } = require('diff-leven');

console.log(diff({ foo: 'bar' }, { foo: 'baz' }));
// Output:
//  {
// -  foo: "bar"
// +  foo: "baz"
//  }

🛠️ API Reference

diff(a, b, options?)

Compare two values (strings, objects, arrays, etc.) and return a formatted diff string.

Note on arrays: comparison is positional only (index-by-index). Reordered elements are treated as removals/additions rather than matched by similarity.

Parameters

• a, b: Anything serializable (object, array, string, number, etc.)
• options (optional object):
  • color (boolean): Use colors in output (default: true)
  • keysOnly (boolean): Only compare object keys (default: false)
  • full (boolean): Output the entire JSON tree (default: false)
  • outputKeys (string[]): Always include these keys in output (default: [])
  • ignoreKeys (string[]): Ignore these keys when comparing (default: [])
  • ignoreValues (boolean): Ignore value differences (default: false)

Returns

• A string representing the diff between a and b.

diffRaw(a, b, options?)

Compare two values (strings, objects, arrays, etc.) and return a structured diff result object.

Parameters

• a, b: Anything serializable (object, array, string, number, etc.)
• options (optional object):
  • color (boolean): Use colors in output (default: true)
  • keysOnly (boolean): Only compare object keys (default: false)
  • full (boolean): Output the entire JSON tree (default: false)
  • outputKeys (string[]): Always include these keys in output (default: [])
  • ignoreKeys (string[]): Ignore these keys when comparing (default: [])
  • ignoreValues (boolean): Ignore value differences (default: false)

Returns

• A structured object representing the diff between a and b.

isDiff(a, b, options?)

Check if two values (strings, objects, arrays, etc.) are different and return a boolean result.

Parameters

• a, b: Anything serializable (object, array, string, number, etc.)
• options (optional object):
  • keysOnly (boolean): Only compare object keys (default: false)
  • ignoreKeys (string[]): Ignore these keys when comparing (default: [])
  • ignoreValues (boolean): Ignore value differences (default: false)

Returns

• A boolean indicating if the values are different (true = different, false = identical).

Examples

const { diff, diffRaw, isDiff } = require('diff-leven');

// Basic diff (string output)
console.log(diff({ foo: 'bar' }, { foo: 'baz' }));
// Output:
//  {
// -  foo: "bar"
// +  foo: "baz"
//  }

// Raw diff object
const rawDiff = diffRaw({ foo: 'bar' }, { foo: 'baz' });
console.log(JSON.stringify(rawDiff, null, 2));
// Output:
// {
//   "type": "changed",
//   "path": [],
//   "oldValue": { "foo": "bar" },
//   "newValue": { "foo": "baz" },
//   "children": [
//     {
//       "type": "changed",
//       "path": ["foo"],
//       "oldValue": "bar",
//       "newValue": "baz"
//     }
//   ]
// }

// Boolean diff check
console.log(isDiff({ foo: 'bar' }, { foo: 'baz' }));
// Output: true

console.log(isDiff({ foo: 'bar' }, { foo: 'bar' }));
// Output: false

// With options
console.log(
  isDiff(
    { foo: 'bar', timestamp: 123 },
    { foo: 'bar', timestamp: 456 },
    { ignoreKeys: ['timestamp'] },
  ),
);
// Output: false (identical when ignoring timestamp)

// No colors
console.log(diff({ foo: 'bar' }, { foo: 'baz' }, { color: false }));
// Output:
//  {
// -  foo: "bar"
// +  foo: "baz"
//  }

// Full output
console.log(diff({ foo: 'bar', b: 3 }, { foo: 'baz', b: 3 }, { full: true }));
// Output:
//  {
// -  foo: "bar"
// +  foo: "baz"
//    b: 3
//  }

// Ignore keys
console.log(
  diff({ foo: 'bar', b: 3 }, { foo: 'baz', b: 3 }, { ignoreKeys: ['b'] }),
);
// Output:
//  {
// -  foo: "bar"
// +  foo: "baz"
//  }

// Ignore values
console.log(
  diff({ foo: 'bar', b: 3 }, { foo: 'baz', b: 3 }, { ignoreValues: true }),
);
// Output showing structural differences only

// Show similarity info for string changes
console.log(
  diff('hello world', 'hello there', { color: true, withSimilarity: true }),
);
// Output:
// - 'hello world'
// + 'hello there' (73% similar)

// Output specific keys
console.log(
  diff({ foo: 'bar', b: 3 }, { foo: 'baz', b: 3 }, { outputKeys: ['foo'] }),
);
// Output:
//  {
// -  foo: "bar"
// +  foo: "baz"
//  }

// Combine options
console.log(
  diff(
    { foo: 'bar', b: 3 },
    { foo: 'baz', b: 3 },
    {
      keysOnly: true,
      ignoreKeys: ['b'],
      ignoreValues: true,
      outputKeys: ['foo'],
      full: true,
      color: false,
    },
  ),
);

⚙️ Options Matrix

| Option | Type | Default | Description | | ---------------- | -------- | ------- | -------------------------------------------- | | color | boolean | true | Use colorized output | | keysOnly | boolean | false | Only compare object keys | | full | boolean | false | Output the entire object tree | | outputKeys | string[] | [] | Always include these keys in output | | ignoreKeys | string[] | [] | Ignore these keys when comparing | | ignoreValues | boolean | false | Ignore value differences, focus on structure | | withSimilarity | boolean | false | Show similarity info for string changes |

📦 Examples

See examples/basic.js for more usage patterns.

🤝 Contributing

1. Fork the repo
2. Create your feature branch (git checkout -b feature/YourFeature)
3. Commit your changes (git commit -am 'Add new feature')
4. Push to the branch (git push origin feature/YourFeature)
5. Open a pull request

📄 License

MIT © kushalshit27