lodash.uniqwith

The lodash method uniqWith exported as a Node.js module. Creates a duplicate-free version of an array using a custom comparator function to determine element equality, making it particularly useful for removing duplicates from arrays of objects or complex data structures.

Package Information

• Package Name: lodash.uniqwith
• Package Type: npm
• Language: JavaScript
• Installation: npm install lodash.uniqwith

Core Imports

const uniqWith = require('lodash.uniqwith');

For ES modules (when available):

import uniqWith from 'lodash.uniqwith';

Alternative import from main lodash library:

const { uniqWith } = require('lodash');
// or
import { uniqWith } from 'lodash';

Basic Usage

const uniqWith = require('lodash.uniqwith');
const isEqual = require('lodash.isequal');

// Remove duplicates from array of objects
const objects = [
  { 'x': 1, 'y': 2 }, 
  { 'x': 2, 'y': 1 }, 
  { 'x': 1, 'y': 2 }
];

const result = uniqWith(objects, isEqual);
console.log(result);
// => [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }]

// Custom comparator function
const users = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' },
  { id: 1, name: 'Alice' }
];

const uniqueUsers = uniqWith(users, (a, b) => a.id === b.id);
console.log(uniqueUsers);
// => [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]

Capabilities

Array Deduplication with Custom Comparator

Creates a duplicate-free version of an array using a comparator function to determine element equality.

/**
 * This method is like `_.uniq` except that it accepts `comparator` which
 * is invoked to compare elements of `array`. The comparator is invoked with
 * two arguments: (arrVal, othVal).
 * 
 * @static
 * @memberOf _
 * @category Array
 * @param {Array} array - The array to inspect
 * @param {Function} [comparator] - The comparator invoked per element
 * @returns {Array} Returns the new duplicate free array
 */
function uniqWith(array, comparator)

Parameters:

• array (Array): The array to inspect and remove duplicates from
• comparator (Function, optional): The comparator function invoked to compare elements. The comparator is invoked with two arguments: (arrVal, othVal)

Returns:

• (Array): Returns a new duplicate-free array

Behavior:

• Returns an empty array [] if the input array is falsy (null, undefined, false, 0, "") or empty
• Uses the provided comparator function to determine element equality
• The comparator function receives two arguments: (arrVal, othVal) where arrVal is the current array element and othVal is the element being compared against
• Elements are considered duplicates when the comparator returns a truthy value
• Preserves the order of the first occurrence of each unique element
• Does not modify the original array
• If no comparator is provided, the function still works but may not produce meaningful results for complex objects (use _.uniq for simple equality instead)

Usage Examples:

// Basic object comparison with lodash isEqual
const objects = [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }, { 'x': 1, 'y': 2 }];
const result = uniqWith(objects, isEqual);
// => [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }]

// Custom comparison logic
const items = [
  { name: 'apple', category: 'fruit' },
  { name: 'carrot', category: 'vegetable' },
  { name: 'banana', category: 'fruit' }
];

// Remove duplicates by category
const uniqueByCategory = uniqWith(items, (a, b) => a.category === b.category);
// => [{ name: 'apple', category: 'fruit' }, { name: 'carrot', category: 'vegetable' }]

// Case-insensitive string comparison
const names = ['Alice', 'bob', 'ALICE', 'Charlie'];
const uniqueNames = uniqWith(names, (a, b) => a.toLowerCase() === b.toLowerCase());
// => ['Alice', 'bob', 'Charlie']

// Handle edge cases
uniqWith([], (a, b) => a === b);        // => []
uniqWith(null, (a, b) => a === b);      // => []
uniqWith(undefined, (a, b) => a === b); // => []

Performance Characteristics

• Time Complexity: O(n²) in worst case due to comparison operations
• Space Complexity: O(n) for the result array
• Optimization: Uses internal lodash optimizations for large arrays through baseUniq function
• Memory Efficient: Creates a new array without modifying the original input

Error Handling

The function is designed to handle edge cases gracefully:

• Falsy Input: Returns empty array [] for null, undefined, or other falsy values
• Empty Array: Returns empty array [] for empty input arrays
• Invalid Comparator: If no comparator is provided, the function will still work but may not produce expected results for complex objects

Related Functions

This function is part of the lodash unique array methods family:

• lodash.uniq: Basic uniqueness without comparator
• lodash.uniqby: Uniqueness with iteratee function for property-based deduplication
• lodash.sorteduniq: Optimized for sorted arrays
• lodash.sorteduniqby: Sorted arrays with iteratee function