unique-object-array

A lightweight JavaScript utility that filters an array of objects for uniqueness using deep equality comparison.

Installation

npm install unique-object-array

Usage

const uniqueArray = require('unique-object-array');

const arrayWithDuplicates = [
  { name: 'John', age: 30, address: { city: 'New York', zip: '10001' } },
  { name: 'Jane', age: 25, hobbies: ['reading', 'swimming'] },
  { name: 'John', age: 30, address: { city: 'New York', zip: '10001' } }, // duplicate
  { name: 'Bob', age: 35, pets: [{ type: 'dog', name: 'Rex' }] },
  { name: 'Jane', age: 25, hobbies: ['reading', 'swimming'] }, // duplicate
];

const uniqueObjects = uniqueArray(arrayWithDuplicates);
console.log(uniqueObjects);

Output:

[
  { name: 'John', age: 30, address: { city: 'New York', zip: '10001' } },
  { name: 'Jane', age: 25, hobbies: ['reading', 'swimming'] },
  { name: 'Bob', age: 35, pets: [{ type: 'dog', name: 'Rex' }] }
]

Features

• Deep equality comparison: Compares nested objects and arrays recursively
• Preserves order: Keeps the first occurrence of each unique object
• Handles complex structures: Works with nested objects, arrays, and mixed data types
• Null/undefined safe: Properly handles edge cases
• No dependencies: Pure JavaScript implementation

How it works

The function uses a custom deep comparison algorithm that:

1. Compares primitive values using strict equality (===)
2. Recursively compares object properties and array elements
3. Ensures both objects have the same keys and structure
4. Handles null, undefined, and type mismatches appropriately

API

uniqueArray(arrayOfObjects)

Parameters:

• arrayOfObjects (Array): Array of objects to filter for uniqueness

Returns:

• Array: New array containing only unique objects (first occurrence preserved)

Example with nested structures:

const data = [
  { 
    user: { id: 1, profile: { name: 'Alice', tags: ['admin', 'user'] } }
  },
  { 
    user: { id: 2, profile: { name: 'Bob', tags: ['user'] } }
  },
  { 
    user: { id: 1, profile: { name: 'Alice', tags: ['admin', 'user'] } }
  } // exact duplicate
];

const unique = uniqueArray(data);
// Returns first 2 objects only

Edge Cases

The function handles various edge cases:

• Null and undefined values: Compared using strict equality
• Different property order: Objects with same properties in different order are considered equal
• Array order matters: Arrays are compared element by element in order
• Type checking: Different types are never considered equal

// These are considered equal (same properties, different order)
const obj1 = { a: 1, b: 2 };
const obj2 = { b: 2, a: 1 };

// These are NOT equal (array order matters)
const arr1 = [1, 2, 3];
const arr2 = [3, 2, 1];

Limitations

• Performance: O(n²) time complexity for large arrays
• Circular references: Not supported (will cause infinite recursion)
• Special objects: Date objects, RegExp, etc. are compared as generic objects
• Functions: Compared by reference, not by implementation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

ISC

Changelog

1.0.0

• Initial release
• Deep equality comparison for objects and arrays
• Null/undefined safety
• Preserves order of first occurrence