object-deep-compare


A type-safe collection of comparison methods for objects and arrays in TypeScript/JavaScript. This library provides powerful tools for deep comparison of complex data structures with configurable options.

Features

- Type-safe: Written in TypeScript with full type definitions
- Zero dependencies: No external dependencies required
- Flexible equality: Choose between strict and loose equality with the strict option
- Special value support: Correctly handles comparison of special values like NaN, null, and undefined
- Date object support: Properly compares Date objects based on their time values
- RegExp support: Correctly compares RegExp objects
- Circular reference detection: Can detect and handle circular references in objects and arrays
- Path filtering: Ability to include or exclude specific properties from comparison using wildcard patterns
- Schema validation: Validate objects against expected schemas before comparison
- Performance optimized: Efficient algorithms to minimize processing time
- Configurable: Control comparison behavior through options
- Detailed difference reporting: Get detailed information about each difference including type and actual values

Installation

Using npm:
``bash
npm install object-deep-compare
`

Using yarn:
`bash
yarn add object-deep-compare
`

Usage

$3


`js
const {
CompareProperties,
CompareArrays,
CompareValuesWithConflicts,
CompareValuesWithDetailedDifferences,
// Other functions as needed...
} = require('object-deep-compare');
`

$3

`ts
import {
CompareProperties,
CompareArrays,
CompareValuesWithConflicts,
CompareValuesWithDetailedDifferences,
TypeSafeCompareObjects,
ObjectsAreEqual,
IsSubset,
// Schema validation
ValidateObjectsAgainstSchemas,
// Types
ComparisonOptions,
CircularReferenceHandling,
PathFilter,
PathFilterMode,
SchemaValidation
// Other functions and types as needed...
} from 'object-deep-compare';
`

All functions are named exports, so you can import only the specific functions you need.

Schema Validation

The library offers optional schema validation to ensure objects match an expected structure before comparison. This helps catch structural issues early, ensuring that objects conform to expected schemas.

$3

`ts
import {
CompareValuesWithDetailedDifferences,
SchemaValidation
} from 'object-deep-compare';

// Define a schema for user objects
const userSchema = {
id: 'string',
name: 'string',
age: 'number',
isActive: 'boolean',
metadata: {
createdAt: 'string',
updatedAt: 'string'
}
};

// Objects to compare
const user1 = {
id: '1001',
name: 'Alice',
age: 32,
isActive: true,
metadata: {
createdAt: '2023-01-01',
updatedAt: '2023-05-15'
}
};

const user2 = {
id: '1002',
name: 'Bob',
age: 'twenty-eight', // Wrong type - should be a number
isActive: true,
metadata: {
createdAt: '2023-02-10'
// Missing updatedAt field
}
};

// Set validation options
const schemaValidation: SchemaValidation = {
firstObjectSchema: userSchema,
secondObjectSchema: userSchema,
throwOnValidationFailure: true // Will throw an error if validation fails
};

try {
// Compare with schema validation
const differences = CompareValuesWithDetailedDifferences(
user1,
user2,
'',
{ schemaValidation }
);
console.log('Differences:', differences);
} catch (error) {
console.error('Schema validation failed:', error.message);
console.log('Validation result:', error.validationResult);
/*
ValidationResult will contain:
{
firstObjectValid: true,
secondObjectValid: false,
secondObjectErrors: [
'Property age should be of type number but got string',
'Missing required property: metadata.updatedAt'
]
}
*/
}
`

$3

The schema definition is a simple object structure where:

- String values represent expected types: 'string', 'number', 'boolean', 'object', 'array', etc.
- Use 'any' to skip type checking for a property
- Use objects for nested structure validation
- Use arrays with a single object to define schemas for array items

#### Array Schema Example:

`ts
// Schema for an array of user objects
const usersSchema = [
{
id: 'string',
name: 'string',
age: 'number'
}
];

// Or using array notation
const tagsSchema = 'array';
`

$3

You can validate objects against schemas without performing comparisons:

`ts
import { ValidateObjectsAgainstSchemas, SchemaValidation } from 'object-deep-compare';

const schema = {
id: 'string',
items: 'array