equals

Performs deep equality comparison between two values with optimized recursive traversal. Compares values recursively by examining all nested properties of objects and arrays. Provides special handling for NaN values (treats NaN === NaN as true, unlike standard equality). Supports optional property exclusion for partial comparisons and performance optimization.

Signature

const equals: <Left, Right>(left: Left, right: Right, omit?: Set<PropertyKey> | Array<PropertyKey>) => boolean

Parameters

Name	Type	Description
left	-	First value to compare
right	-	Second value to compare
omit	-	Set or array of property keys to exclude from comparison (optional)

Returns

true if the two values are deeply equal, false otherwise

Examples

Basic object and primitive comparisons

import { equals } from '@winglet/common-utils';

// Primitive values
console.log(equals(42, 42)); // true
console.log(equals('hello', 'hello')); // true
console.log(equals(null, null)); // true
console.log(equals(undefined, undefined)); // true

// NaN special case (unlike === operator)
console.log(equals(NaN, NaN)); // true
console.log(NaN === NaN); // false (standard behavior)

// Object comparison
const obj1 = { a: 1, b: 'test' };
const obj2 = { a: 1, b: 'test' };
console.log(equals(obj1, obj2)); // true
console.log(obj1 === obj2); // false (different references)

Deep nested structure comparison

// Nested objects and arrays
const complex1 = {
  user: { name: 'John', age: 30 },
  hobbies: ['reading', 'coding'],
  metadata: { created: new Date('2023-01-01'), active: true }
};

const complex2 = {
  user: { name: 'John', age: 30 },
  hobbies: ['reading', 'coding'],
  metadata: { created: new Date('2023-01-01'), active: true }
};

console.log(equals(complex1, complex2)); // true

// Property order doesn't matter
const reordered = {
  hobbies: ['reading', 'coding'],
  metadata: { active: true, created: new Date('2023-01-01') },
  user: { age: 30, name: 'John' }
};
console.log(equals(complex1, reordered)); // true

Array comparison with nested structures

const arr1 = [1, { name: 'Alice' }, [2, 3, { nested: true }]];
const arr2 = [1, { name: 'Alice' }, [2, 3, { nested: true }]];
const arr3 = [1, { name: 'Bob' }, [2, 3, { nested: true }]];

console.log(equals(arr1, arr2)); // true
console.log(equals(arr1, arr3)); // false (different name)

// Order matters in arrays
const ordered1 = [1, 2, 3];
const ordered2 = [3, 2, 1];
console.log(equals(ordered1, ordered2)); // false

Using property exclusion for partial comparison

const user1 = { id: 1, name: 'John', lastLogin: '2023-01-01', version: 1 };
const user2 = { id: 1, name: 'John', lastLogin: '2023-01-02', version: 2 };

// Compare ignoring timestamp and version fields
console.log(equals(user1, user2)); // false
console.log(equals(user1, user2, ['lastLogin', 'version'])); // true

// Using Set for omission (better performance for many keys)
const omitFields = new Set(['lastLogin', 'version', 'updatedAt']);
console.log(equals(user1, user2, omitFields)); // true

Edge cases and special values

// Mixed type comparisons
console.log(equals({}, [])); // false (object vs array)
console.log(equals(null, undefined)); // false
console.log(equals(0, false)); // false (different types)
console.log(equals('0', 0)); // false (string vs number)

// Function comparisons (reference equality)
const fn1 = () => 'hello';
const fn2 = () => 'hello';
const fn3 = fn1;
console.log(equals({ fn: fn1 }, { fn: fn1 })); // true (same reference)
console.log(equals({ fn: fn1 }, { fn: fn2 })); // false (different references)
console.log(equals({ fn: fn1 }, { fn: fn3 })); // true (same reference)

Playground

import { equals } from '@winglet/common-utils';

// Primitive values
console.log(equals(42, 42)); // true
console.log(equals('hello', 'hello')); // true
console.log(equals(null, null)); // true
console.log(equals(undefined, undefined)); // true

// NaN special case (unlike === operator)
console.log(equals(NaN, NaN)); // true
console.log(NaN === NaN); // false (standard behavior)

// Object comparison
const obj1 = { a: 1, b: 'test' };
const obj2 = { a: 1, b: 'test' };
console.log(equals(obj1, obj2)); // true
console.log(obj1 === obj2); // false (different references)

Notes

Performance Characteristics:

• Time Complexity: O(n) where n is the total number of properties/elements
• Space Complexity: O(d) where d is the maximum depth of nesting
• Optimizations: Early termination on first difference, reference equality check

Performance Benchmarks (Node.js v18, typical hardware):

• Small objects (< 100 props): ~0.01ms
• Medium objects (< 1000 props): ~0.15ms
• Large objects (< 10000 props): ~2ms
• Deep nesting (10 levels): ~0.3ms
• vs stableEquals: ~2x faster but fewer features
• vs JSON.stringify comparison: ~5x faster and more accurate
• vs Lodash isEqual: ~30% faster with similar features

Comparison Strategy:

• Primitives: Uses strict equality (===) with special NaN handling
• Objects: Compares all own enumerable properties recursively
• Arrays: Compares length and elements by index
• Mixed Types: Always returns false for different types

Supported Data Types:

• All primitive types (string, number, boolean, null, undefined, symbol, bigint)
• Plain objects and arrays (deeply nested)
• Functions (reference equality only)
• Built-in objects like Date, RegExp (compared by reference)

Function Selection Guide:

// Use equals() for:
- Performance-critical comparisons
- Simple objects without circular references
- Basic deep equality needs
- General boolean equality checks
- Objects with only string/number keys

// Use stableEquals() for:
- Objects with potential circular references
- Advanced type support (Date, RegExp, TypedArrays)
- Sparse arrays or complex data structures
- Objects with symbol properties
- Maximum reliability over performance

Error Cases and Stack Overflow:

// ⚠️ DANGER: Circular references cause stack overflow
const circular1: any = { name: 'obj1' };
const circular2: any = { name: 'obj2' };
circular1.ref = circular2;
circular2.ref = circular1;

// This will crash:
// equals(circular1, circular2); // RangeError: Maximum call stack size exceeded

// Safe alternatives:
// 1. Use stableEquals() instead
// 2. Remove circular references before comparison
// 3. Implement circular reference detection

TypeScript Usage Patterns:

// Basic equality checking
function compareObjects(obj1: any, obj2: any): boolean {
  return equals(obj1, obj2);
}

// Conditional logic based on equality
function processUserData(current: User, updated: User) {
  if (equals(current, updated, ['lastModified', 'version'])) {
    console.log('No meaningful changes detected');
    return current;
  }

  console.log('User data has changed');
  return { ...current, ...updated, lastModified: new Date() };
}

// Form validation
function isFormValid(formData: FormData, expectedStructure: FormData): boolean {
  return equals(formData, expectedStructure, ['timestamp', 'sessionId']);
}

// Note: For type narrowing, you need manual type assertions
function validateApiResponse(response: unknown) {
  const expectedStructure = { status: 'success', data: {} };

  if (equals(expectedStructure, response, ['data'])) {
    // Manual type assertion needed since equals() returns boolean
    const validResponse = response as { status: 'success'; data: any };
    return validResponse;
  }

  throw new Error('Invalid API response structure');
}

Limitations:

• Does not handle circular references (causes stack overflow)
• Functions are compared by reference only, not by implementation
• Built-in objects (Date, RegExp, etc.) use reference equality
• Does not compare non-enumerable properties
• Symbol properties are not compared
• Performance degrades with very deep nesting (>50 levels)

Production Considerations:

• Memory: Monitor stack usage with deeply nested objects
• Performance: Consider memoization for frequently compared objects
• Error Handling: Wrap in try-catch for user-provided data
• Security: Validate object depth to prevent stack overflow attacks
• Testing: Verify behavior with your specific data structures

Browser/Runtime Compatibility:

• ES5+: Compatible with all modern environments
• Node.js: v0.10+ (full compatibility)
• Browsers: IE9+ (uses Object.keys, Array.isArray)
• TypeScript: 2.0+ for generic type support
• No Dependencies: Self-contained implementation

Comparison with Alternatives:

• Native ===: Only reference equality, no deep comparison
• JSON.stringify comparison: Unreliable (property order, undefined handling)
• Lodash isEqual: Similar functionality, ~30% slower, heavier bundle
• Ramda equals: Similar performance, functional programming style
• stableEquals: More features but ~2x slower

Use Cases:

• Form validation and state comparison
• Memoization and caching logic
• Testing and assertion libraries
• Change detection in reactive systems
• API response validation
• General purpose deep equality checking