0
# Lodash isMatch
1

2
The `isMatch` method from the lodash utility library performs deep comparison to determine if an object contains equivalent property values to a source object. Part of lodash's comprehensive collection of JavaScript utilities, this method supports nested objects, arrays, and custom comparison functions.
3

4
## Package Information
5

6
- **Package Name**: lodash
7
- **Package Type**: npm 
8
- **Language**: JavaScript
9
- **Installation**: `npm install lodash`
10
- **Documentation**: https://lodash.com/docs
11

12
## Core Imports
13

14
```javascript
15
import _ from "lodash";
16
// or
17
import { isMatch } from "lodash";
18
```
19

20
For CommonJS:
21

22
```javascript
23
const _ = require("lodash");
24
// or  
25
const { isMatch } = require("lodash");
26
```
27

28
For AMD:
29

30
```javascript
31
define(['lodash'], function(_) {
32
  return _.isMatch;
33
});
34
```
35

36
## Basic Usage
37

38
```javascript
39
import _ from "lodash";
40

41
const user = { name: 'fred', age: 40, city: 'NYC' };
42

43
// Basic property matching
44
_.isMatch(user, { age: 40 });
45
// => true
46

47
_.isMatch(user, { age: 30 });  
48
// => false
49

50
// Multiple property matching
51
_.isMatch(user, { name: 'fred', age: 40 });
52
// => true
53

54
// Nested object matching
55
const profile = {
56
  user: { name: 'fred', age: 40 },
57
  preferences: { theme: 'dark' }
58
};
59

60
_.isMatch(profile, { user: { name: 'fred' } });
61
// => true
62
```
63

64
## Capabilities
65

66
### Deep Object Comparison
67

68
Performs deep comparison between an object and a source object to determine if the object contains equivalent property values.
69

70
```javascript { .api }
71
/**
72
 * Performs a deep comparison between `object` and `source` to determine if
73
 * `object` contains equivalent property values. If `customizer` is provided
74
 * it is invoked to compare values. If `customizer` returns `undefined`
75
 * comparisons are handled by the method instead.
76
 * 
77
 * @param {Object} object - The object to inspect
78
 * @param {Object} source - The object of property values to match
79
 * @param {Function} [customizer] - The function to customize comparing values
80
 * @param {*} [thisArg] - The `this` binding of `customizer`
81
 * @returns {boolean} Returns `true` if `object` is a match, else `false`
82
 */
83
function isMatch(object, source, customizer, thisArg);
84
```
85

86
**Usage Examples:**
87

88
```javascript
89
import _ from "lodash";
90

91
// Basic matching
92
const object = { 'user': 'fred', 'age': 40 };
93
_.isMatch(object, { 'age': 40 });
94
// => true
95

96
_.isMatch(object, { 'age': 36 });
97
// => false
98

99
// Deep nested matching  
100
const nested = { 
101
  a: { b: { c: 1, d: 2 }, e: 3 }, 
102
  f: 4 
103
};
104
_.isMatch(nested, { a: { b: { c: 1 } } });
105
// => true
106

107
// Array matching searches within arrays
108
const withArray = { items: ['a', 'b', 'c'], name: 'test' };
109
_.isMatch(withArray, { items: ['b'] });
110
// => true (searches for elements within the array)
111

112
_.isMatch(withArray, { items: ['a', 'b'] });
113
// => true (all source elements found in target array)
114

115
_.isMatch(withArray, { items: ['b', 'a'] });
116
// => true (order doesn't matter for element search)
117

118
// Empty source always matches
119
_.isMatch({ a: 1 }, {});
120
// => true
121

122
// Null/undefined object handling
123
_.isMatch(null, { a: 1 });
124
// => false
125

126
// Undefined value matching requires explicit undefined property
127
_.isMatch({ a: 1 }, { b: undefined });
128
// => false (object lacks property 'b')
129

130
_.isMatch({ a: 1, b: 2 }, { b: undefined });
131
// => false (object has property 'b' but value is not undefined)
132

133
_.isMatch({ a: 1, b: undefined }, { b: undefined });
134
// => true (object has property 'b' with undefined value)
135
```
136

137
### Custom Comparison Logic
138

139
Allows custom comparison functions for specialized matching logic.
140

141
```javascript { .api }
142
/**
143
 * Custom comparison function signature
144
 * @param {*} value - The value from the object being inspected
145
 * @param {*} other - The value from the source object
146
 * @param {string|number} indexOrKey - The property key being compared (or array index)
147
 * @returns {boolean|undefined} Return boolean for custom comparison, undefined for default behavior
148
 */
149
type CustomizerFunction = (value: any, other: any, indexOrKey: string | number) => boolean | undefined;
150
```
151

152
**Usage Examples:**
153

154
```javascript
155
import _ from "lodash";
156

157
// Custom string matching (case-insensitive)
158
const object = { greeting: 'hello' };
159
const source = { greeting: 'HELLO' };
160

161
_.isMatch(object, source, function(value, other) {
162
  if (typeof value === 'string' && typeof other === 'string') {
163
    return value.toLowerCase() === other.toLowerCase();
164
  }
165
  return undefined; // Use default comparison for non-strings
166
});
167
// => true
168

169
// Custom numeric tolerance matching
170
const measurement = { temperature: 25.1, humidity: 60.3 };
171
const target = { temperature: 25, humidity: 60 };
172

173
_.isMatch(measurement, target, function(value, other) {
174
  if (typeof value === 'number' && typeof other === 'number') {
175
    return Math.abs(value - other) <= 1; // 1 unit tolerance
176
  }
177
  return undefined;
178
});
179
// => true
180

181
// Using thisArg for context
182
const config = { tolerance: 0.5 };
183
_.isMatch(
184
  { price: 10.3 }, 
185
  { price: 10 }, 
186
  function(value, other) {
187
    if (typeof value === 'number' && typeof other === 'number') {
188
      return Math.abs(value - other) <= this.tolerance;
189
    }
190
    return undefined;
191
  },
192
  config
193
);
194
// => true
195
```
196

197
## Type Definitions
198

199
```typescript { .api }
200
/**
201
 * Deep comparison function interface
202
 */
203
interface IsMatchFunction {
204
  (object: any, source: any): boolean;
205
  (object: any, source: any, customizer: CustomizerFunction): boolean;
206
  (object: any, source: any, customizer: CustomizerFunction, thisArg: any): boolean;
207
}
208

209
/**
210
 * Custom comparison function type
211
 */
212
type CustomizerFunction = (value: any, other: any, indexOrKey: string | number) => boolean | undefined;
213

214
/**
215
 * Lodash namespace containing isMatch
216
 */
217
interface LoDashStatic {
218
  isMatch: IsMatchFunction;
219
}
220
```
221

222
## Supported Data Types
223

224
### Primitive Types
225
- **Strings**: Exact string matching
226
- **Numbers**: Exact numeric matching (including NaN handling)
227
- **Booleans**: Exact boolean matching
228
- **null/undefined**: Exact null/undefined matching
229

230
### Object Types
231
- **Objects**: Deep property comparison
232
- **Arrays**: Searches for source elements within target arrays (order independent)
233
- **Dates**: Date value comparison
234
- **RegExp**: RegExp source and flags comparison
235

236
### Unsupported Types
237
- **Functions**: Not supported without custom comparator
238
- **DOM Nodes**: Not supported without custom comparator
239

240
## Performance Notes
241

242
- **Single Property Optimization**: When matching a single property with a primitive value, uses fast strict equality comparison
243
- **Deep Comparison**: For complex objects, delegates to internal `baseIsMatch` for comprehensive comparison
244
- **Lazy Evaluation**: Only compares properties that exist in the source object
245
- **Short-Circuit**: Returns `false` immediately if object is `null`/`undefined` and source has properties
246

247
## Error Handling
248

249
The function is designed to be safe and won't throw errors under normal usage:
250

251
- **Null/undefined objects**: Returns `false` if object is null/undefined and source has properties
252
- **Missing properties**: Returns `false` if object lacks a property present in source
253
- **Type mismatches**: Returns `false` for incompatible types (unless custom comparator handles it)
254
- **Circular references**: May cause stack overflow (not explicitly handled in lodash 3.2.0)
255

256
## Common Use Cases
257

258
```javascript
259
// Filtering arrays of objects
260
const users = [
261
  { name: 'john', age: 25, active: true, tags: ['admin', 'user'] },
262
  { name: 'jane', age: 30, active: false, tags: ['user'] },
263
  { name: 'bob', age: 25, active: true, tags: ['user', 'premium'] }
264
];
265

266
// Filter by properties
267
const activeUsers25 = users.filter(user => 
268
  _.isMatch(user, { age: 25, active: true })
269
);
270
// => [{ name: 'john', age: 25, active: true, tags: ['admin', 'user'] }, 
271
//     { name: 'bob', age: 25, active: true, tags: ['user', 'premium'] }]
272

273
// Filter by array contents
274
const adminUsers = users.filter(user =>
275
  _.isMatch(user, { tags: ['admin'] })
276
);
277
// => [{ name: 'john', age: 25, active: true, tags: ['admin', 'user'] }]
278

279
// Form validation
280
const formData = { 
281
  username: 'john123', 
282
  email: 'john@example.com',
283
  age: 25 
284
};
285

286
const requiredFields = { username: 'john123', email: 'john@example.com' };
287
const hasRequiredFields = _.isMatch(formData, requiredFields);
288
// => true
289

290
// API response validation
291
const apiResponse = {
292
  status: 'success',
293
  data: { id: 1, name: 'Product' },
294
  meta: { timestamp: '2023-01-01' }
295
};
296

297
const expectedShape = { 
298
  status: 'success', 
299
  data: { id: 1 } 
300
};
301
const isValidResponse = _.isMatch(apiResponse, expectedShape);
302
// => true
303
```