Lodash matches is a utility function that creates a predicate function for deep object comparison. It takes a source object as input and returns a function that tests whether other objects contain all the key-value pairs present in the source object, using deep equality comparison.
npm install lodashmatches (from lodash v3.1.0)CommonJS (primary method for v3.1.0):
const _ = require("lodash");
const matches = _.matches;Global usage (browser):
const matches = _.matches;AMD usage:
define(['lodash'], function(_) {
const matches = _.matches;
});const _ = require("lodash");
// Create sample data
const users = [
{ user: 'fred', age: 40 },
{ user: 'barney', age: 36 }
];
// Create a matcher function
const matchesAge = _.matches({ age: 36 });
// Use with collection methods
const result = _.filter(users, matchesAge);
// => [{ user: 'barney', age: 36 }]
const found = _.find(users, matchesAge);
// => { user: 'barney', age: 36 }Creates a function that performs deep comparison between objects and the provided source pattern.
/**
* Creates a function which performs a deep comparison between a given object
* and `source`, returning `true` if the given object has equivalent property
* values, else `false`.
*
* @static
* @memberOf _
* @category Utility
* @param {Object} source - The object of property values to match
* @returns {Function} Returns the new predicate function
*/
function matches(source);The returned predicate function signature:
/**
* @param {Object} object - The object to inspect
* @returns {boolean} Returns `true` if object matches, else `false`
*/
function predicate(object);Usage Examples:
const _ = require("lodash");
// Simple property matching
const matchName = _.matches({ name: 'fred' });
matchName({ name: 'fred', age: 40 }); // => true
matchName({ name: 'barney', age: 36 }); // => false
// Multiple property matching
const matchMultiple = _.matches({ age: 36, active: true });
matchMultiple({ name: 'barney', age: 36, active: true }); // => true
matchMultiple({ name: 'fred', age: 40, active: true }); // => false
// Deep object matching
const user = {
profile: {
name: 'fred',
settings: { theme: 'dark' }
},
status: 'active'
};
const matchNested = _.matches({
profile: {
settings: { theme: 'dark' }
}
});
matchNested(user); // => true
// Array and mixed type matching
const matchComplex = _.matches({
tags: ['javascript', 'lodash'],
metadata: { version: 1 }
});
matchComplex({
name: 'project',
tags: ['javascript', 'lodash'],
metadata: { version: 1, created: '2023-01-01' }
}); // => true===, but NaN equals NaN)const _ = require("lodash");
const products = [
{ name: 'laptop', category: 'electronics', price: 999, inStock: true },
{ name: 'book', category: 'media', price: 29, inStock: false },
{ name: 'phone', category: 'electronics', price: 599, inStock: true }
];
// Filter by category
const electronics = _.filter(products, _.matches({ category: 'electronics' }));
// Find available electronics
const availableElectronics = _.filter(products, _.matches({
category: 'electronics',
inStock: true
}));
// Check if any products match criteria
const hasAffordableElectronics = _.some(products, _.matches({
category: 'electronics',
price: 599
}));
// Use with array methods
const matchElectronics = _.matches({ category: 'electronics' });
const electronicsArray = products.filter(matchElectronics);const _ = require("lodash");
// Empty source object matches everything
const matchAll = _.matches({});
matchAll({ anything: 'here' }); // => true
matchAll({}); // => true
// NaN handling (SameValueZero comparison)
const matchNaN = _.matches({ value: NaN });
matchNaN({ value: NaN }); // => true (unlike === comparison)
// Null and undefined handling
const matchNull = _.matches({ value: null });
matchNull({ value: null }); // => true
matchNull({ value: undefined }); // => false
matchNull({}); // => false (missing property)
// Array matching requires exact order and values
const matchArray = _.matches({ items: [1, 2, 3] });
matchArray({ items: [1, 2, 3] }); // => true
matchArray({ items: [3, 2, 1] }); // => false (different order)
matchArray({ items: [1, 2, 3, 4] }); // => false (different length)
// Empty arrays and objects in source match any arrays/objects in target
const matchEmpty = _.matches({ items: [], config: {} });
matchEmpty({ items: [1, 2, 3], config: { theme: 'dark' } }); // => true
matchEmpty({ items: [], config: {} }); // => true
// Deep nested object matching
const matchDeep = _.matches({
user: {
profile: {
settings: { notifications: true }
}
}
});
matchDeep({
user: {
name: 'alice',
profile: {
age: 30,
settings: {
notifications: true,
theme: 'dark'
}
}
}
}); // => true (contains required nested structure)The matches function itself does not throw errors under normal usage. The returned predicate function handles:
false when the object to test is null or undefinedfalse when required properties are missingfalse when property values don't match using SameValueZero comparisonconst _ = require("lodash");
const matcher = _.matches({ name: 'fred' });
matcher(null); // => false
matcher(undefined); // => false
matcher({}); // => false (missing name property)
matcher({ name: 'fred' }); // => trueWhile this K-tile focuses on _.matches, Lodash v3.1.0 includes related functions that work with similar matching logic:
_.where(collection, source): Filters a collection using the same deep comparison logic as matches_.isMatch(object, source): Performs direct object comparison without creating a predicate function_.findWhere(collection, source): Finds the first element that matches the source objectThese functions use the same underlying matching algorithm and complement _.matches in collection operations.