Comparator - Generic Object Comparison Library

A TypeScript-based utility for deep comparison of JavaScript objects with circular reference handling and detailed diff generation.

Overview

This library provides an extensible comparator framework that performs deep equality checks between two objects of any type. When objects differ, it returns a detailed diff object instead of simply returning false, enabling granular analysis of differences.

Installation

npm i @pourianof/cobjs

Core Components

Comparator (Abstract Class)

The base abstract class that implements the comparison algorithm. It handles primitive comparisons and delegates object comparison to concrete implementations.

ObjectComparator

Concrete implementation that handles object comparison with circular reference detection and asynchronous diff resolution.

DiffObj

Wrapper class that encapsulates diff objects and manages evaluation of pending comparisons.

InEqualityException

Custom exception thrown during equality checks when a mismatch is detected, allowing early termination of comparison.

API Reference

Constructor

new Comparator(a: T, b: T, configs?: ComparatorConfigs)

Configuration Options

| Option | Type | Default | Description | | ------------------------- | ------- | ------- | ---------------------------------------------------------- | | ignoreRecuriveReference | boolean | false | Controls circular reference behavior | | diffOnSecondParam | boolean | false | Flips parameter order for comparison | | rightJoin | boolean | false | Includes keys from second object that don't exist in first |

Methods

compare(forceToReCompare?: boolean): Obj | boolean

Performs comparison between the two objects.

• Returns: true if objects are identical, otherwise returns a diff object
• Parameter: forceToReCompare - When true, bypasses cache and performs fresh comparison

isEqual(configs?: { forceToReCompare?: boolean } & ComparatorConfigs): boolean

Performs equality check.

• Returns: boolean - true if objects are equal, false otherwise
• Parameter: Optional configuration override for the comparison

Diff Object Structure

When objects differ, the compare method returns an object where:

• Keys represent paths to differing values
• Values represent the actual differing values from the first object

With rightJoin: true, keys present only in the second object appear with undefined values.

Circular Reference Handling

The comparator tracks visited object pairs to prevent infinite recursion. When a circular reference is detected, pending comparisons are queued and resolved after the reference cycle completes.

Usage Examples

Basic Comparison

class MyComparator extends ObjectComparator {
  // Custom implementation if needed
}

const a = { name: "John", age: 30 };
const b = { name: "John", age: 31 };

const comparator = new MyComparator(a, b);
const result = comparator.compare();

// result = { age: 30 } - indicates difference at 'age' property

Equality Check

const comparator = new ObjectComparator(obj1, obj2);
const equal = comparator.isEqual(); // Returns boolean only

Right Join Mode

const comparator = new ObjectComparator(
  { name: "John" },
  { name: "John", age: 30 },
  { rightJoin: true },
);

const diff = comparator.compare();
// diff = { age: undefined } - indicates extra field in second object

Forcing Re-comparison

const comparator = new ObjectComparator(obj1, obj2);
comparator.compare(); // Caches result
comparator.compare(true); // Forces fresh comparison

Important Notes

• The compare method returns true when objects are identical
• When objects differ, compare returns a diff object (not false)
• For boolean-only equality checks, use the isEqual method
• Primitive values are compared by value using strict equality (===)
• Functions are always considered equal (compared by reference)
• undefined and null values are handled according to their types

Extending the Comparator

To create custom comparison logic:

class CustomComparator extends Comparator {
  protected handleObjectComparation(a: Obj, b: Obj): DiffObj {
    // Custom object comparison logic
    return new DiffObj({});
  }
}

Error Handling

• InEqualityException is thrown internally during isEqual() checks and caught to return false
• Other errors propagate through the call stack

Performance Considerations

• Results are cached by default - use forceToReCompare judiciously
• Circular references are handled without infinite loops
• Deep object traversal occurs recursively with visited object tracking

License

MIT