https://github.com/amirfarzamnia/deep-compare-objects
Deeply compare objects and identify their differences.
https://github.com/amirfarzamnia/deep-compare-objects
arrays compare datatype deep differences json objects
Last synced: 5 months ago
JSON representation
Deeply compare objects and identify their differences.
- Host: GitHub
- URL: https://github.com/amirfarzamnia/deep-compare-objects
- Owner: amirfarzamnia
- License: mit
- Created: 2024-06-22T06:51:03.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-12-16T09:22:29.000Z (6 months ago)
- Last Synced: 2025-12-17T00:33:36.482Z (6 months ago)
- Topics: arrays, compare, datatype, deep, differences, json, objects
- Language: TypeScript
- Homepage: https://amirfarzamnia.github.io/deep-compare-objects/
- Size: 212 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Deep Compare Objects
A TypeScript utility for deeply comparing objects and arrays, identifying their differences with precision.
[](https://badge.fury.io/js/deep-compare-objects)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
## Features
- Deep comparison of objects and arrays
- Handles nested structures
- TypeScript support
- Safe JSON stringification
- Returns only the differences between objects
## Installation
```bash
# Using npm
npm install deep-compare-objects
# Using yarn
yarn add deep-compare-objects
# Using pnpm
pnpm add deep-compare-objects
```
## Usage
```typescript
import deepCompareObjects from "deep-compare-objects";
// Basic object comparison
const obj1 = { name: "John", age: 30 };
const obj2 = { name: "John", age: 31 };
const differences = deepCompareObjects(obj1, obj2);
// Result: { age: 31 }
// Nested object comparison
const nested1 = { user: { name: "John", address: { city: "New York" } } };
const nested2 = { user: { name: "John", address: { city: "Los Angeles" } } };
const nestedDifferences = deepCompareObjects(nested1, nested2);
// Result: { user: { address: { city: 'Los Angeles' } } }
// Array comparison
const arr1 = [1, 2, { name: "John" }];
const arr2 = [1, 2, { name: "Jane" }];
const arrayDifferences = deepCompareObjects(arr1, arr2);
// Result: { 2: { name: 'Jane' } }
```
## API
### `deepCompareObjects(a: Record, b: Record): Record | undefined`
Compares two objects and returns their differences.
#### Parameters
- `a` (optional): The first object to compare. Defaults to an empty object.
- `b` (optional): The second object to compare. Defaults to an empty object.
#### Returns
- An object containing only the differences between `a` and `b`
- `undefined` if `b` is null or undefined
#### Behavior
- For primitive values, returns the new value if different
- For objects, recursively compares and returns only the changed properties
- For arrays, compares each element and returns only the changed elements
- Handles circular references safely using `json-stringify-safe`
## Examples
### Comparing Simple Objects
```typescript
const obj1 = { name: "John", age: 30 };
const obj2 = { name: "John", age: 31, city: "New York" };
const result = deepCompareObjects(obj1, obj2);
// Result: { age: 31, city: 'New York' }
```
### Comparing Nested Objects
```typescript
const obj1 = {
user: {
name: "John",
preferences: {
theme: "dark",
notifications: true,
},
},
};
const obj2 = {
user: {
name: "John",
preferences: {
theme: "light",
notifications: true,
},
},
};
const result = deepCompareObjects(obj1, obj2);
// Result: { user: { preferences: { theme: 'light' } } }
```
### Comparing Arrays
```typescript
const arr1 = [1, 2, { name: "John" }];
const arr2 = [1, 3, { name: "Jane" }];
const result = deepCompareObjects(arr1, arr2);
// Result: { 1: 3, 2: { name: 'Jane' } }
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Author
Amir Farzamnia - [GitHub](https://github.com/amirfarzamnia)
## Support
If you find this package useful, please consider giving it a ⭐️ on GitHub!