deep-obj-compare

deep-obj-compare

A lightweight TypeScript utility for deep comparison of JavaScript objects with detailed error reporting and path tracking.

Installation

npm install deep-obj-compare

Features

• 🔍 Deep comparison of nested objects and arrays
• 📍 Precise path tracking for mismatches
• 📅 Date and RegExp support
• 🔢 Proper NaN handling
• 💬 Customizable object naming in error reports
• 📦 Zero dependencies
• 🎯 Full TypeScript support

Quick Start

import { compareObjects } from 'deep-obj-compare';

const expected = { name: 'Alice', age: 30, address: { city: 'NYC' } };
const actual = { name: 'Alice', age: 30, address: { city: 'LA' } };

const errors = compareObjects(expected, actual);
// Returns:
// [
//   { path: 'address.city', type: 'Value Mismatch', expected: 'NYC', actual: 'LA' , message: 'Value Mismatch'}
// ]

API

compareObjects(objA, objB, config?)

Compares two objects and returns an array of differences.

Parameter	Type	Description
objA	any	First object to compare
objB	any	Second object to compare
config	ComparisonConfig	Optional configuration

Config Options

interface ComparisonConfig {
  nameA?: string; // Display name for first object (default: 'expected')
  nameB?: string; // Display name for second object (default: 'actual')
}

Examples

Array Comparison

const expected = { items: [1, 2, 3] };
const actual = { items: [1, 2, 4] };

compareObjects(expected, actual);
// [{ path: 'items[2]', type: 'Value Mismatch', expected: 3, actual: 4 ,message:'Value Mismatch'}]

Custom Naming

const source = { status: 'active' };
const target = { status: 'pending' };

compareObjects(source, target, { nameA: 'source', nameB: 'target' });
// [{ path: 'status', type: 'Value Mismatch', source: 'active', target: 'pending',message:'Value Mismatch' }]

Missing Keys Detection

const expected = { x: 1, y: 2 };
const actual = { x: 1 };

compareObjects(expected, actual);
// [
//   { path: '(root)', type: 'Key Length Mismatch' ,expected:2, actual:1 ,message: 'Key count mismatch'},
//   { path: 'y', type: 'Missing Key', expected: 2, actual: undefined, message: 'Property "y" is missing in actual.y but exists in expected.y' },
// ]

Date Comparison

const expected = { created: new Date('2024-01-01') };
const actual = { created: new Date('2024-06-01') };

compareObjects(expected, actual);
// [{ path: 'created', type: 'Date Mismatch', expected: '2024-01-01T00:00:00.000Z', actual: '2024-06-01T00:00:00.000Z',message: 'Dates do not match' }]

Error Types

Type	Description
Type Mismatch	Different types (e.g., string vs number)
Value Mismatch	Same type but different values
Null Mismatch	One is null, the other is not
Array Length Mismatch	Arrays have different lengths
Key Length Mismatch	Objects have different number of keys
Missing Key	Key exists in one object but not the other
Date Mismatch	Date values differ
RegExp Mismatch	Regular expressions differ
NaN Mismatch	One is NaN, the other is not

License

MIT © bennyh960