isMatch

The isMatch utility checks if an object contains a specific pattern of properties and values. It performs a partial comparison, meaning the checked object can have additional properties not present in the pattern.

Implementation

View Source Code

/**
 * Performs a partial deep comparison between object and source to determine if object contains equivalent property values.
 *
 * @example
 * ```ts
 * const object = { a: 1, b: 2, c: { d: 3 } };
 *
 * isMatch(object, { a: 1, c: { d: 3 } }); // true
 * isMatch(object, { a: 1, b: 2 }); // true
 * isMatch(object, { a: 1, c: { d: 4 } }); // false
 *
 * isMatch([1, 2, 3], [1, 2]); // true
 * isMatch([1, 2, 3], [1, 2, 3]); // true
 * isMatch([1, 2, 3], [1, 2, 4]); // false
 * ```
 *
 * @param object - The object to inspect.
 * @param source - The object of property values to match.
 *
 * @returns `true` if the object is a match, else `false`.
 */
// biome-ignore lint/suspicious/noExplicitAny: -
export function isMatch(object: any, source: any): boolean {
  if (object === source) return true;
  if (object == null || source == null) return false;

  const isObjArray = Array.isArray(object);
  const isSrcArray = Array.isArray(source);

  if (isObjArray !== isSrcArray) return false;

  if (isObjArray && isSrcArray) {
    if (source.length > object.length) return false;
    // biome-ignore lint/suspicious/noExplicitAny: -
    return source.every((item: any, i: number) => isMatch(object[i], item));
  }

  if (typeof source === 'object') {
    for (const key in source) {
      if (Object.hasOwn(source, key) && !isMatch(object?.[key], source[key])) {
        return false;
      }
    }
    return true;
  }

  return object === source;
}

Features

• Isomorphic: Works in both Browser and Node.js.
• Partial Matching: Only verifies the keys specified in the pattern.
• Regex Support: Allows matching string values against Regular Expressions.
• Deep Matching: Recursively checks nested objects within the pattern.

API

function isMatch(target: any, pattern: any): boolean;

Parameters

• obj: The object to validate.
• pattern: The shape or values to match against.

Returns

• true if the object matches the pattern; otherwise, false.

Examples

Partial Object Match

import { isMatch } from '@vielzeug/toolkit';

const user = { id: 1, name: 'Alice', role: 'admin', active: true };

// Only check name and role
isMatch(user, { name: 'Alice', role: 'admin' }); // true

// Missing property in pattern is fine
isMatch(user, { id: 1 }); // true

Regular Expression Matching

import { isMatch } from '@vielzeug/toolkit';

const product = { sku: 'PROD-123', category: 'electronics' };

// Match SKU using a regex
isMatch(product, { sku: /^PROD-/ }); // true

Nested Pattern Matching

import { isMatch } from '@vielzeug/toolkit';

const data = {
  meta: {
    status: 200,
    tags: ['new'],
  },
};

isMatch(data, { meta: { status: 200 } }); // true

Implementation Notes

• Uses deep equality (isEqual) for non-primitive values in the pattern.
• If a value in the pattern is a RegExp, it tests the corresponding value in the object using .test().
• Throws nothing; safely handles null, undefined, and non-object inputs by returning false.

See Also

• isEqual: Check for total structural identity.
• search: Fuzzy search across objects in an array.
• path: Retrieve a specific nested value.