0
# lodash.isequal
1

2
Deep equality comparison function for JavaScript values. Performs comprehensive comparisons between two values to determine if they are equivalent, supporting arrays, booleans, Date objects, numbers, Object objects, regexes, and strings.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const isEqual = require('lodash.isequal');
15
```
16

17
For ES modules (if supported by your environment):
18

19
```javascript
20
import isEqual from 'lodash.isequal';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const isEqual = require('lodash.isequal');
27

28
// Basic object comparison
29
const object = { 'user': 'fred' };
30
const other = { 'user': 'fred' };
31

32
object == other;
33
// => false
34

35
isEqual(object, other);
36
// => true
37

38
// Array comparison
39
const arr1 = [1, 2, 3];
40
const arr2 = [1, 2, 3];
41
isEqual(arr1, arr2);
42
// => true
43

44
// Deep nested comparison
45
const complex1 = { 
46
  users: [{ name: 'alice', data: { active: true } }],
47
  count: 1 
48
};
49
const complex2 = { 
50
  users: [{ name: 'alice', data: { active: true } }],
51
  count: 1 
52
};
53
isEqual(complex1, complex2);
54
// => true
55
```
56

57
## Capabilities
58

59
### Deep Equality Comparison
60

61
Performs a deep comparison between two values to determine if they are equivalent.
62

63
```javascript { .api }
64
/**
65
 * Performs a deep comparison between two values to determine if they are
66
 * equivalent. Supports circular reference detection and custom comparison logic.
67
 * If customizer is provided it's invoked to compare values. If customizer returns
68
 * undefined comparisons are handled by the method instead. The customizer is bound
69
 * to thisArg and invoked with up to three arguments: (value, other [, index|key]).
70
 *
71
 * @param {*} value The value to compare.
72
 * @param {*} other The other value to compare.
73
 * @param {Function} [customizer] The function to customize value comparisons.
74
 * @param {*} [thisArg] The this binding of customizer.
75
 * @returns {boolean} Returns true if the values are equivalent, else false.
76
 */
77
function isEqual(value, other, customizer, thisArg);
78
```
79

80
**Supported Types:**
81
- Arrays (including nested arrays and typed arrays)
82
- Booleans  
83
- Date objects
84
- Error objects (compared by name and message properties)
85
- Numbers (with special handling for NaN, +0/-0)
86
- Object objects (compared by own enumerable properties, not inherited)
87
- Regular expressions
88
- Strings
89
- Arguments objects (treated as regular objects)
90

91
**Special Behaviors:**
92
- **Circular References**: Automatically detected and handled to prevent infinite recursion
93
- **NaN Comparison**: `NaN` values are considered equal to each other
94
- **Zero Comparison**: Distinguishes between `+0` and `-0` (they are not equal)
95
- **Wrapped Objects**: Supports lodash wrapped objects via `__wrapped__` property
96

97
**Not Supported (without custom comparator):**
98
- Functions 
99
- DOM nodes
100

101
**Usage Examples:**
102

103
```javascript
104
const isEqual = require('lodash.isequal');
105

106
// Different data types
107
isEqual(1, 1);                    // => true
108
isEqual('hello', 'hello');        // => true
109
isEqual(true, true);              // => true
110
isEqual([1, 2], [1, 2]);          // => true
111
isEqual({ a: 1 }, { a: 1 });      // => true
112

113
// Date objects
114
const date1 = new Date('2023-01-01');
115
const date2 = new Date('2023-01-01');
116
isEqual(date1, date2);            // => true
117

118
// Regular expressions
119
isEqual(/abc/g, /abc/g);          // => true
120

121
// Special number handling
122
isEqual(NaN, NaN);                // => true (special case)
123
isEqual(+0, -0);                  // => false (distinguishes zero signs)
124

125
// Error objects  
126
const err1 = new Error('test');
127
const err2 = new Error('test');
128
isEqual(err1, err2);              // => true (compared by name and message)
129

130
// Custom comparator
131
const array = ['hello', 'goodbye'];
132
const other = ['hi', 'goodbye'];
133

134
isEqual(array, other, function(value, other) {
135
  if (RegExp.prototype.test.call(/^h(?:i|ello)$/, value) && 
136
      RegExp.prototype.test.call(/^h(?:i|ello)$/, other)) {
137
    return true;
138
  }
139
});
140
// => true
141
```
142

143
### Custom Comparison Logic
144

145
The optional `customizer` function allows extending comparison support for additional value types and custom comparison logic.
146

147
**Customizer Function Signature:**
148
- **Parameters**: 
149
  - `value` - The value from the first object being compared
150
  - `other` - The value from the second object being compared  
151
  - `index|key` (optional) - The index (for arrays) or key (for objects) being compared
152
- **Returns**: 
153
  - `boolean` - For definitive custom comparison result
154
  - `undefined` - To defer to default lodash comparison logic
155
- **Binding**: Bound to `thisArg` if provided (uses `thisArg` as the `this` context)
156
- **Invocation**: Called for every value pair during deep comparison traversal
157

158
**Example with custom comparator:**
159

160
```javascript
161
function customEqual(a, b) {
162
  return isEqual(a, b, function(objValue, othValue) {
163
    // Custom logic for comparing special objects
164
    if (objValue && objValue.isSpecialType) {
165
      return objValue.id === othValue.id;
166
    }
167
    // Return undefined to use default comparison
168
  });
169
}
170

171
const obj1 = { isSpecialType: true, id: 'abc', data: 'different' };
172
const obj2 = { isSpecialType: true, id: 'abc', data: 'values' };
173
customEqual(obj1, obj2); // => true (compared by id only)
174
```
175

176
### Circular Reference Handling
177

178
The `isEqual` function automatically detects and handles circular references in objects and arrays to prevent infinite recursion:
179

180
```javascript
181
const isEqual = require('lodash.isequal');
182

183
// Create objects with circular references
184
const obj1 = { name: 'test' };
185
obj1.self = obj1;
186

187
const obj2 = { name: 'test' };
188
obj2.self = obj2;
189

190
isEqual(obj1, obj2); // => true
191

192
// Works with arrays too
193
const arr1 = [1, 2];
194
arr1[2] = arr1;
195

196
const arr2 = [1, 2];
197
arr2[2] = arr2;
198

199
isEqual(arr1, arr2); // => true
200

201
// Mixed circular references
202
const complex1 = { data: { users: [] } };
203
complex1.data.users.push(complex1);
204

205
const complex2 = { data: { users: [] } };
206
complex2.data.users.push(complex2);
207

208
isEqual(complex1, complex2); // => true
209
```
210

211
## Error Handling
212

213
The `isEqual` function itself does not throw errors and will return `false` for comparisons that cannot be performed. However, custom comparator functions may throw errors if they encounter unexpected input:
214

215
```javascript
216
const isEqual = require('lodash.isequal');
217

218
// Function handles type mismatches gracefully
219
isEqual(null, undefined);     // => false
220
isEqual({}, null);           // => false
221
isEqual(1, "1");             // => false
222

223
// Custom comparator errors are not caught
224
try {
225
  isEqual(obj1, obj2, function() {
226
    throw new Error('Custom error');
227
  });
228
} catch (error) {
229
  console.log('Caught:', error.message); // => 'Caught: Custom error'
230
}
231
```