match()

This function compares a JavaScript object to satisfy a certain structural pattern. It can handle objects with circular dependencies.

isShape() is an alias of this function.

Introduction

import {match, any} from 'deep6';

match({a: 1, b: 2}, {a: 1}); // true
match({a: 1, b: 2}, {b: 2}); // true
match({a: 1, b: 2}, {c: 3}); // false
match({a: 1, b: 2}, [1, 2]); // false

match({a: 1, b: 2}, {a: any}); // true
match({a: 1, b: 2}, {b: any}); // true
match({a: 1, b: 2}, {c: any}); // false

match({a: 1, b: 2}, any); // true

any is used to match any possible value.

API

match(object, pattern [, options])

Arguments:

• object — a required argument. It can be anything.

• pattern — a required argument. It can be anything, usually, an object, which lists desired properties, which should be present.

• options — an optional object. The following optional properties are recognized:

  • openObjects — a boolean flag. When true all objects in pattern are treated as incomplete, which causes to ignore the corresponding extra properties in object. Otherwise, all objects should match exactly.
  • openMaps — a boolean flag. When true all maps in pattern are treated as incomplete, which causes to ignore the corresponding extra properties in object. Otherwise, all maps should match exactly.
  • openSets — a boolean flag. When true all sets in pattern are treated as incomplete, which causes to ignore the corresponding extra properties in object. Otherwise, all sets should match exactly.
  • openArrays — a boolean flag. When true all arrays in pattern are treated as incomplete, which causes to ignore extra trailing elements in object.
  • circular — a boolean flag. When true, special algorithms are used to detect internal loops in objects.
    • It is totally safe to turn it on for all objects, but checks will require more memory and more CPU. In some cases, for performance reasons, you may want to turn it off.
  • symbols — a boolean flag. When true, symbol properties would be checked for equivalency as well.
    • Normally symbol properties are hidden from enumerating using classical means.
  • ignoreFunctions — a boolean flag. When true, if both properties are functions, they are assumed to be equivalent automatically.
  • loose — a boolean flag. When true, primitives are compared with == rather than ===.
  • Any other properties documented in Traverse: preprocess().

  The default: {openObjects: true, openArrays: true, openMaps: true, openSets: true, circular: true}.

The function returns a boolean value, which indicates that the first argument matches the second.

Notes

Implemented using unify() and Traverse: preprocess():

const defaultMatchOptions = {openObjects: true, openArrays: true, openMaps: true, openSets: true, circular: true};
const match = (object, pattern, options = defaultMatchOptions) => {
  const processedPattern = preprocess(pattern, options),
    unifyOptions = {
      circular: options.circular,
      symbols: options.symbols,
      loose: options.loose,
      ignoreFunctions: options.ignoreFunctions
    };
  return !!unify(object, processedPattern, null, unifyOptions);
};

The open* flags drive preprocess(), which wraps the pattern's containers with open(). They are not forwarded to unify() directly — the open semantics rides on the wrapped pattern.