0
# lodash.uniqwith
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: lodash.uniqwith
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install lodash.uniqwith`
10

11
## Core Imports
12

13
```javascript
14
const uniqWith = require('lodash.uniqwith');
15
```
16

17
For ES modules (when available):
18

19
```javascript
20
import uniqWith from 'lodash.uniqwith';
21
```
22

23
Alternative import from main lodash library:
24

25
```javascript
26
const { uniqWith } = require('lodash');
27
// or
28
import { uniqWith } from 'lodash';
29
```
30

31
## Basic Usage
32

33
```javascript
34
const uniqWith = require('lodash.uniqwith');
35
const isEqual = require('lodash.isequal');
36

37
// Remove duplicates from array of objects
38
const objects = [
39
  { 'x': 1, 'y': 2 }, 
40
  { 'x': 2, 'y': 1 }, 
41
  { 'x': 1, 'y': 2 }
42
];
43

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

48
// Custom comparator function
49
const users = [
50
  { id: 1, name: 'Alice' },
51
  { id: 2, name: 'Bob' },
52
  { id: 1, name: 'Alice' }
53
];
54

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

60
## Capabilities
61

62
### Array Deduplication with Custom Comparator
63

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

66
```javascript { .api }
67
/**
68
 * This method is like `_.uniq` except that it accepts `comparator` which
69
 * is invoked to compare elements of `array`. The comparator is invoked with
70
 * two arguments: (arrVal, othVal).
71
 * 
72
 * @static
73
 * @memberOf _
74
 * @category Array
75
 * @param {Array} array - The array to inspect
76
 * @param {Function} [comparator] - The comparator invoked per element
77
 * @returns {Array} Returns the new duplicate free array
78
 */
79
function uniqWith(array, comparator)
80
```
81

82
**Parameters:**
83

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

87
**Returns:**
88

89
- (Array): Returns a new duplicate-free array
90

91
**Behavior:**
92

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

101
**Usage Examples:**
102

103
```javascript
104
// Basic object comparison with lodash isEqual
105
const objects = [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }, { 'x': 1, 'y': 2 }];
106
const result = uniqWith(objects, isEqual);
107
// => [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }]
108

109
// Custom comparison logic
110
const items = [
111
  { name: 'apple', category: 'fruit' },
112
  { name: 'carrot', category: 'vegetable' },
113
  { name: 'banana', category: 'fruit' }
114
];
115

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

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

125
// Handle edge cases
126
uniqWith([], (a, b) => a === b);        // => []
127
uniqWith(null, (a, b) => a === b);      // => []
128
uniqWith(undefined, (a, b) => a === b); // => []
129
```
130

131
## Performance Characteristics
132

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

138
## Error Handling
139

140
The function is designed to handle edge cases gracefully:
141

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

146
## Related Functions
147

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

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